diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml index 8193e5e839..bf6f030683 100644 --- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml @@ -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-06-21-bounded-llm-request-recovery.md -2026-06-21-bounded-llm-request-recovery.md: 5c76ed5d754ea40f41dff78cb56ee7fc139a32b1 -2026-06-21-bounded-llm-request-recovery.zh.md: 1fa56f3fe0405cab663c2843d423a78d910170dd +2026-06-21-bounded-llm-request-recovery.md: 24725dcf300cf69e9cc72580d0c8afe937d4e2b9 +2026-06-21-bounded-llm-request-recovery.zh.md: 5f03a65b00be8d3349addce82e4f3faa2af1fe7e diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md index 5c76ed5d75..24725dcf30 100644 --- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md +++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md @@ -84,7 +84,7 @@ Boundary tests prove termination at both actual transports. The hand-written ada A failed attempt may leave `assistant/chunk` events in its closed step, but it never appends `assistant/message` and never dispatches a tool. A retry closes the failed turn, opens the next numbered turn, reconstructs the request from the durable surface, and produces its own chunks. UIs may render live chunks while a step is open, then mark or clear that transient view when `llm/retry` identifies the failed step or `turn/end` records failure. Web validates the complete retry payload contract, clears the failed partial at `llm/retry`, projects consecutive retry-turn events into one stable row updated to the latest attempt, and derives scheduled, started, or cancelled status from subsequent turn facts. Its countdown anchors the scheduled delay to browser receipt rather than the Host event clock, uses ceiling-rounded seconds with a one-second floor, animates only while unresolved, and keeps exact latest failure details collapsed behind the row. Retry nodes anchor their own trajectory turn even when the failed attempt has no assistant node. Message derivation continues to ignore the failed chunks, and Web applies the same projection during history rebuild so refreshing cannot resurrect discarded partials or duplicate retry rows. -If recovery is exhausted, the final failure is stored once on `turn/end.reason` with the structured facts. If transient recovery continues, `llm/retry` is the durable home for that attempt's failure and delay. No standalone final-error event or response-id vocabulary is added. +If recovery is exhausted, the final failure is stored once on `turn/end.reason` with the structured facts. Web derives one `turn-error` node at that sequence position and renders its display-safe message and optional code inline; AUTH projections replace provider copy that may echo credential fragments with `API key is invalid`, while the raw diagnostic remains in the session log. The same fold runs for live events and history replay. If transient recovery continues, `llm/retry` is the durable home for that attempt's failure and delay, so its failed turn does not also gain a terminal error row. No standalone final-error event or response-id vocabulary is added. ## Out of scope diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md index 1fa56f3fe0..5f03a65b00 100644 --- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md +++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md @@ -84,7 +84,7 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次 一次失败尝试可以在已关闭的步骤中留下 `assistant/chunk` 事件，但绝不会追加 `assistant/message`，也不会分发工具。重试会关闭失败轮次，开启下一个编号轮次，从持久表层重建请求，并生成自己的分片。步骤仍处于打开状态时，UI 可以渲染实时分片；当 `llm/retry` 标识失败步骤，或 `turn/end` 记录失败时，UI 再标记或清除这份暂时视图。Web 会验证完整的重试载荷契约，在 `llm/retry` 到达时清除失败的部分输出，将连续重试轮次的事件投影为稳定的一行，并用最新一次尝试更新该行，再从后续轮次事实派生 scheduled、started 或 cancelled 状态。倒计时以浏览器收到事件的时刻为计划延迟的起点，而不是使用 Host 事件时钟；它按向上取整且不低于 1 秒的秒数显示，仅在重试尚未结束时显示动画，并把最近一次失败的准确详情折叠在该行之后。即使失败尝试没有 assistant 节点，重试节点也会锚定自身的轨迹轮次。消息派生仍会忽略失败分片；Web 在重建历史时也会应用同一投影，因此刷新页面不会让已丢弃的部分输出重新出现，也不会生成重复的重试行。 -如果恢复预算耗尽，最终失败会连同结构化事实在 `turn/end.reason` 中存储一次。如果暂时性恢复继续，`llm/retry` 就是该次尝试的失败与延迟的持久归属位置。本决策不增加独立的最终错误事件或响应 id 词汇。 +如果恢复预算耗尽，最终失败会连同结构化事实在 `turn/end.reason` 中存储一次。Web 会在该序列位置派生一个 `turn-error` 节点，并内联渲染适合展示的消息与可选错误码；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。实时事件和历史回放使用同一套折叠逻辑。如果暂时性恢复继续，`llm/retry` 就是该次尝试的失败与延迟的持久归属位置，因此该失败轮次不会再获得终态错误行。本决策不增加独立的最终错误事件或响应 id 词汇。 ## 不在范围内 diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml index 09ab4376b5..52c7c71e1a 100644 --- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml @@ -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: c3deadb34d3a633525dde701c92bcc98c05e5d6e -2026-07-25-web-input-machine-and-slash-pipeline.zh.md: 7a6988423dcdffebb0a28735146439c8ade0a862 +2026-07-25-web-input-machine-and-slash-pipeline.md: 977df6508e1a1cd54cf1ddb469a6bfb835f60071 +2026-07-25-web-input-machine-and-slash-pipeline.zh.md: 929a885bf54a31605805814ba1e15c901e560434 diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md index c3deadb34d..977df6508e 100644 --- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md +++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md @@ -72,7 +72,7 @@ A trigger/menu/pick pipeline with zero knowledge of "commands": - Each materialized Session has exactly one `SessionInputShell` (the facade), created and torn down with the session scope; with no session, no input machine is built. `ConversationRoot` is itself the `session-maybe` resident shell, holding HeroShell, the Workspace picker, the composer stack, and the chain-fallback frame. - The composer bar is one `session-maybe` slot entry rendered unconditionally: with no session the same InputBar renders inert (machine faces absent, `disabled` owner prop), and once `connectWorkspace` returns a blank session the same instance goes live — the textarea DOM survives the no-session → blank transition and every later phase flip; `ConversationRoot`, the Hero, and the layout skeleton hold throughout. - ConversationRoot's Hero criterion is `sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || openState === 'loading'))`. The first submit enters engaging synchronously, and a failure keeps the composer and the error context rather than falling back to the blank Hero; the sidebar's blank bit flips false only after a prompt is successfully accepted. -- Sending unifies in the hub defaultSink: after an optimistic draft clear it goes only through `session.prompt {mode:'queue'|'steer'}`; backfill happens only when it fails and the live draft is still empty — a user who has kept typing is never overwritten. No Draft materialize or attach transaction exists. +- Sending unifies in the hub defaultSink: after an optimistic draft clear it goes only through `session.prompt` with `mode:'queue'` (the Web UI has no steer entry; host-wire `mode:'steer'` remains outside this machine); backfill happens only when it fails and the live draft is still empty — a user who has kept typing is never overwritten. No Draft materialize or attach transaction exists. - When the blank Hero re-picks the Workspace, the shell calls `connectWorkspace`; if the target session differs, the non-empty draft moves from the current shell to the target shell before the new id is opened, and the old blank session survives but is no longer current. - The Notifier's two-bit contract: `dirty` (snapshot freshness, clearable by an `ensureFresh` pull) and `notifyPending` (notification debt, cleared only by a flush) are mutually independent — a pull must not swallow a push, and object-layer push subscribers (watchTransaction) depend on this guarantee. diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md index 7a6988423d..929a885bf5 100644 --- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md @@ -72,7 +72,7 @@ occurrence 表与 chip 三投影： - 每个实体 Session 只有一个 `SessionInputShell`（facade），随 session scope 创建和拆除；无 session 时不造 input machine。`ConversationRoot` 自身是 `session-maybe` 常驻外壳，持有 HeroShell、Workspace picker、composer stack 与 chain fallback 外框。 - composer bar 是一个无条件渲染的 `session-maybe` slot entry：无 session 时同一个 InputBar 以惰性态渲染（machine face 缺席、`disabled` owner prop），`connectWorkspace` 返回 blank session 后同一实例转为 live——textarea DOM 在无 session → blank 切换及其后每次 phase 翻转中都不重建；`ConversationRoot`、Hero 与布局骨架全程保持。 - ConversationRoot 的 Hero 判据是 `sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || openState === 'loading'))`。首次 submit 同步进入 engaging，失败也保留 composer 与错误上下文，不退回 blank Hero；sidebar 的 blank 位只在 prompt 成功受理后翻 false。 -- 发送统一在 hub defaultSink：乐观清稿后只走 `session.prompt {mode:'queue'|'steer'}`；失败且 live draft 仍为空才回填，用户已经继续输入则不覆盖。不存在 Draft materialize 或 attach 事务。 +- 发送统一在 hub defaultSink：乐观清稿后只走 `session.prompt` 且固定 `mode:'queue'`（Web UI 无 steer 入口；host 线缆上的 `mode:'steer'` 不经此 machine）；失败且 live draft 仍为空才回填，用户已经继续输入则不覆盖。不存在 Draft materialize 或 attach 事务。 - blank Hero 改选 Workspace 时，外壳调用 `connectWorkspace`；目标 session 不同时把非空 draft 从当前 shell 搬到目标 shell，再 open 新 id，旧 blank session 留存但不再 current。 - Notifier 双位契约：`dirty`（快照新鲜度，`ensureFresh` 拉取可清）与 `notifyPending`（通知欠账，只有 flush 清）各自独立——拉取不得吞推送，对象层推订阅者（watchTransaction）依赖这一保证。 diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml index 27911294a6..6855a0af2b 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml @@ -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-28-directory-picker-capability-seam.md -2026-07-28-directory-picker-capability-seam.md: 495062f910785e1bb2f421dbb25c01c399d45567 -2026-07-28-directory-picker-capability-seam.zh.md: 62fc87212ab627ea8819dab55e3a769b4a5afc42 +2026-07-28-directory-picker-capability-seam.md: 9884385cf9e0d51604bab9e4fd3c4bee77448331 +2026-07-28-directory-picker-capability-seam.zh.md: 8c229b9fb08d5052ba8a512f2153a89a9e5fd455 diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md index 495062f910..9884385cf9 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md @@ -12,7 +12,7 @@ The web GUI's "Open local folder" flow was hardwired to one interaction: `host.p A three-package capability seam in `packages/host/` — `directory-picker` (interface), `directory-picker-native`, `directory-picker-browse` (backends) — with one contract method: `capability()` returns a **discriminated union**, `{ kind: 'native', pick(signal) }` or `{ kind: 'browse', list(path?), createDirectory(path, name) }`. The gateway (`dsh-host-apiproxy`) injects `directoryPicker`, serves the matching RPCs, and answers `directory-picker-unavailable` for the other kind. The union is discriminated because the backends differ in *interaction shape* — flattening them into one method set would force every backend to fake the other's shape. -**The client side is slot-composed, not advertisement-branched.** ui-workspace's two trigger surfaces each declare a `single` directory-flow hole (`conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`; two keys because a hole has exactly one declaring slot entry — same owner contract, same occupant). Backend packages are **dual-face**: the browser half registers the matching interaction into both holes — `-native` a renderless occupant driving `host.pickDirectory`, `-browse` the in-app Select Workspace Directory dialog. The hole's owner conversation (`open`/`busy`/`onPicked`/`onCancel`/`onError`) carries the whole exchange: ui-workspace keeps the trigger (menu entry rendered only while the hole is occupied) and the adoption (`createWorkspace({path})`, conflict/error dialog, Choose again), the occupant owns everything between `open` and the picked path. One `cordis.yml` row therefore swaps the host capability and the client flow together; a mismatch is impossible by construction, and mounting two flow packages fails at client load (`single` hole). The earlier `host.describe.directoryPicker` advertisement and the client's kind branching are deleted — with composition wiring both sides, a wire fact for the client to branch on had no remaining consumer. The hole registry (`ctx.slots.entries`) replaces it as the per-menu-open occupancy read. +**The client side is slot-composed, not advertisement-branched.** ui-workspace's two trigger surfaces each declare a `single` directory-flow hole (`conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`; two keys because a hole has exactly one declaring slot entry — same owner contract, same occupant). Backend packages are **dual-face**: the browser half registers the matching interaction into both holes — `-native` a renderless occupant driving `host.pickDirectory`, `-browse` the in-app Select Workspace Directory dialog. The hole's owner conversation (`open`/`busy`/`onPicked`/`onCancel`/`onError`) carries the whole exchange: ui-workspace keeps the trigger (menu entry rendered only while the hole is occupied) and the adoption (`createWorkspace({path})`, retryable error dialog, Choose again), the occupant owns everything between `open` and the picked path. One `cordis.yml` row therefore swaps the host capability and the client flow together; a mismatch is impossible by construction, and mounting two flow packages fails at client load (`single` hole). The earlier `host.describe.directoryPicker` advertisement and the client's kind branching are deleted — with composition wiring both sides, a wire fact for the client to branch on had no remaining consumer. The hole registry (`ctx.slots.entries`) replaces it as the per-menu-open occupancy read. Placement and policy rulings folded into this decision: diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md index 62fc87212a..8c229b9fb0 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md @@ -12,7 +12,7 @@ web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pick 在 `packages/host/` 落一个三包能力 seam——`directory-picker`（接口）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一契约方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在**交互形态**——压平成统一方法集会逼每个后端伪装另一方的形态。 -**client 侧靠 slot 组合，而非按广播分支。** ui-workspace 的两个触发表层各自声明一个 `single` 目录流洞（`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`；之所以是两个 key，是因为一个洞只有一个声明它的 slot entry——owner 契约相同、占用者相同）。后端包是**双面包**：browser half 把匹配的交互注册进两个洞——`-native` 是驱动 `host.pickDirectory` 的无渲染占用者，`-browse` 是应用内的选择工作区目录对话框。洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）承载整个交换：ui-workspace 保留触发（菜单入口仅在洞被占用时渲染）与接纳（`createWorkspace({path})`、冲突／错误对话框、重新选择），占用者持有从 `open` 到所选路径之间的一切。因此一行 `cordis.yml` 同时切换宿主能力与 client 流程；错配在构造上不可能，同时挂两个流程包会在 client 加载期失败（`single` 洞）。早先的 `host.describe.directoryPicker` 广播与客户端 kind 分支被删除——组合已经接好两侧后，供客户端分支用的 wire 事实不再有任何消费者。洞注册表（`ctx.slots.entries`）取而代之，成为每次打开菜单的占用读取。 +**client 侧靠 slot 组合，而非按广播分支。** ui-workspace 的两个触发表层各自声明一个 `single` 目录流洞（`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`；之所以是两个 key，是因为一个洞只有一个声明它的 slot entry——owner 契约相同、占用者相同）。后端包是**双面包**：browser half 把匹配的交互注册进两个洞——`-native` 是驱动 `host.pickDirectory` 的无渲染占用者，`-browse` 是应用内的选择工作区目录对话框。洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）承载整个交换：ui-workspace 保留触发（菜单入口仅在洞被占用时渲染）与接纳（`createWorkspace({path})`、可重试的错误对话框、重新选择），占用者持有从 `open` 到所选路径之间的一切。因此一行 `cordis.yml` 同时切换宿主能力与 client 流程；错配在构造上不可能，同时挂两个流程包会在 client 加载期失败（`single` 洞）。早先的 `host.describe.directoryPicker` 广播与客户端 kind 分支被删除——组合已经接好两侧后，供客户端分支用的 wire 事实不再有任何消费者。洞注册表（`ctx.slots.entries`）取而代之，成为每次打开菜单的占用读取。 并入本决策的位置与策略裁决： diff --git a/.agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.i18n.yaml index 8fc7c8966f..3b0e42df8c 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.i18n.yaml @@ -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-28-launcher-owned-resume-identity.md -2026-07-28-launcher-owned-resume-identity.md: e11431716305ff18e951ca45921c71dcd105974c -2026-07-28-launcher-owned-resume-identity.zh.md: e4078023cb1519288f0367f8973788f361aaa0bd +2026-07-28-launcher-owned-resume-identity.md: 167c9e848a9101c9d1e93cf3af968b00279db32b +2026-07-28-launcher-owned-resume-identity.zh.md: 218b69581e65e8566ff1047603bb71c9537d3486 diff --git a/.agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.md b/.agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.md index e114317163..167c9e848a 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.md +++ b/.agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.md @@ -10,7 +10,7 @@ Two facts a launcher owns were shipped as deployment config keys on the TUI app Routing them through YAML made them silently droppable. `@cordisjs/plugin-include` applies a targeted patch by replacing whole top-level keys (`target[key] = value`), so a personal `~/.dsh/config.yaml` patching the `tui-agent` entry's `config` replaces the shipped block entirely. A user overlay written to change provider and model therefore deleted every resume key it did not restate, and nothing reported it: absent `resumeCommand` legitimately means "no fallback configured". -Both failures were live in one real overlay. The exit hint stopped printing, because the overlay omitted `resumeCommand`. Worse, the overlay carried `resumeSessionId: !!js process.env.RESUME_SESSION_ID` — a stale line from before [the env-var bridge was removed](../../archived/architecture/2026-07-24-dsh-commander-argument-adapter.md) — which overwrote the shipped `!!js "typeof resumeSessionId === 'string' ? …"` intake with a read of a variable nothing sets. `dsh --resume ` then started a *fresh* session and said nothing, reproduced directly: the banner showed a newly minted id, not the requested one. The [`dsh meta`](../feature/2026-07-28-dsh-meta-source-workspace.md) note had recorded this silent resume as an unexplained pre-existing defect; the overlay's shallow replacement is the cause. +Both failures were live in one real overlay. The exit hint stopped printing, because the overlay omitted `resumeCommand`. Worse, the overlay carried `resumeSessionId: !!js process.env.RESUME_SESSION_ID` — a stale line from before [the env-var bridge was removed](../../archived/architecture/2026-07-24-dsh-commander-argument-adapter.md) — which overwrote the shipped `!!js "typeof resumeSessionId === 'string' ? …"` intake with a read of a variable nothing sets. `dsh --resume ` then started a *fresh* session and said nothing, reproduced directly: the banner showed a newly minted id, not the requested one. The [`dsh experimental-meta`](../feature/2026-07-28-dsh-meta-source-workspace.md) note had recorded this silent resume as an unexplained pre-existing defect; the overlay's shallow replacement is the cause. A config key cannot express these facts safely, because the deployment is not the authority on them. @@ -25,7 +25,7 @@ Both sit beside the existing `tuiResumeHost` host capability, which set the prec Identity belongs to `agent-loop` because that is the plugin which creates configured agents, and because a patch replaces a row's whole `config`: an overlay repointing the agent row's model route would erase a launcher-set identity key. See [the shared-base overlay note](../simplification/2026-07-29-shared-base-config-overlays.md). -`apps/cli` mints or selects the id and builds the line from the invocation it is reproducing, sharing one `resumeArgs` helper with the `/resume` execve handoff so the printed command and the in-place handoff cannot diverge. The line now names `--config` when one was passed, and reproduces `dsh meta --resume ` in meta mode — closing the mode-aware hint deferred by the `dsh meta` note, where a copied hint previously only worked from the checkout. +`apps/cli` mints or selects the id and builds the line from the invocation it is reproducing, sharing one `resumeArgs` helper with the `/resume` execve handoff so the printed command and the in-place handoff cannot diverge. The line names `--config` when one was passed. Resume always re-enters the default surface through `dsh --resume `; `dsh experimental-meta` accepts no options and always starts fresh. **`ctx.provide` is the only channel from launcher argv into a Loader-mounted plugin.** Config `!!js` expressions evaluate as `with (entry.ctx) { eval(expr) }` (`vendor/loader/src/config/utils.ts`), so a bare identifier resolves against the entry's context and nothing else reaches it. The slot therefore cannot be removed while the app bundle is mounted from YAML; what changes is that it is now internal launcher↔app plumbing instead of a documented key a config author must wire correctly. diff --git a/.agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.zh.md b/.agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.zh.md index e4078023cb..218b69581e 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.zh.md @@ -10,7 +10,7 @@ Status: implemented 把它们经由 YAML 传递，使其可被静默丢弃。`@cordisjs/plugin-include` 施加定向补丁的方式是替换整个顶层键（`target[key] = value`），因此一份对 `tui-agent` 条目的 `config` 打补丁的个人 `~/.dsh/config.yaml`，会把交付时的整块内容整体替换掉。于是，一份为改动 provider 和 model 而写的用户 overlay，会删掉它未重述的每一个 resume 键，且没有任何东西报告这一点：缺失 `resumeCommand` 合法地意味着「未配置回退」。 -两处失效在同一份真实的 overlay 中同时存在。退出提示不再打印，因为该 overlay 省略了 `resumeCommand`。更糟的是，该 overlay 带着 `resumeSessionId: !!js process.env.RESUME_SESSION_ID`——一行来自 [env 变量桥被移除](../../archived/architecture/2026-07-24-dsh-commander-argument-adapter.md)之前的陈旧代码——它用一次对某个无人设置的变量的读取，覆盖掉了交付时的 `!!js "typeof resumeSessionId === 'string' ? …"` 入口。此后 `dsh --resume ` 会开启一个*全新*会话且什么都不说，并被直接复现：banner 显示的是一个新铸造的 id，而非所请求的那个。[`dsh meta`](../feature/2026-07-28-dsh-meta-source-workspace.md) note 曾把这次静默的 resume 记为一处无法解释的既有缺陷；而 overlay 的浅层替换正是其成因。 +两处失效在同一份真实的 overlay 中同时存在。退出提示不再打印，因为该 overlay 省略了 `resumeCommand`。更糟的是，该 overlay 带着 `resumeSessionId: !!js process.env.RESUME_SESSION_ID`——一行来自 [env 变量桥被移除](../../archived/architecture/2026-07-24-dsh-commander-argument-adapter.md)之前的陈旧代码——它用一次对某个无人设置的变量的读取，覆盖掉了交付时的 `!!js "typeof resumeSessionId === 'string' ? …"` 入口。此后 `dsh --resume ` 会开启一个*全新*会话且什么都不说，并被直接复现：banner 显示的是一个新铸造的 id，而非所请求的那个。[`dsh experimental-meta`](../feature/2026-07-28-dsh-meta-source-workspace.md) note 曾把这次静默的 resume 记为一处无法解释的既有缺陷；而 overlay 的浅层替换正是其成因。 一个配置键无法安全地表达这些事实，因为部署方并非它们的权威。 @@ -25,7 +25,7 @@ Status: implemented 身份归属于 `agent-loop`，因为它才是创建所配置 agent 的插件；也因为 patch 会整体替换配置项的 `config`：重新指向 agent 配置项模型路由的 overlay 会抹掉启动器设置的身份键。参见[共享 base overlay note](../simplification/2026-07-29-shared-base-config-overlays.md)。 -`apps/cli` 铸造或选定 id，并依据它所复现的那次调用构建该行，与 `/resume` 的 execve 移交共用同一个 `resumeArgs` 助手，从而使打印出的命令与原地移交不会分歧。该行现在会在传入了 `--config` 时命名它，并在 meta 模式下复现 `dsh meta --resume `——从而收口了 `dsh meta` note 所推迟的随 mode 变化的提示，在那里被复制的提示此前只有在检出目录中才有效。 +`apps/cli` 铸造或选定 id，并依据它所复现的那次调用构建该行，与 `/resume` 的 execve 移交共用同一个 `resumeArgs` 助手，从而使打印出的命令与原地移交不会分歧。该行会在传入了 `--config` 时将其写入命令。恢复始终通过 `dsh --resume ` 重新进入默认界面；`dsh experimental-meta` 不接受任何选项，并且总是启动新会话。 **`ctx.provide` 是从启动器 argv 进入被 Loader 挂载的插件的唯一通道。** 配置的 `!!js` 表达式会以 `with (entry.ctx) { eval(expr) }`（`vendor/loader/src/config/utils.ts`）求值，因此一个裸标识符会针对该条目的上下文解析，别无它物可达。于是只要应用 bundle 仍从 YAML 挂载，这个槽位就无法被移除；变化之处在于它现在是启动器↔应用之间的内部管线，而不再是一个配置作者必须正确接线的、有文档记载的键。 diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml index cc25329fed..01334b2d8b 100644 --- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml @@ -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-30-session-end-seed-log-boundary.md -2026-07-30-session-end-seed-log-boundary.md: 268646e192d0b8e0a5dde03957a18ef155b7038e -2026-07-30-session-end-seed-log-boundary.zh.md: dca87e16de5e567ff85d2b32b8243f76ebed1c4a +2026-07-30-session-end-seed-log-boundary.md: ca6145f3ce404b88d2a144483c6f1145fe0a9a7e +2026-07-30-session-end-seed-log-boundary.zh.md: d492c4ac5f39328e75d991b285004e2d19c56283 diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md index 268646e192..ca6145f3ce 100644 --- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md +++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md @@ -52,4 +52,4 @@ Cost: a seeded session's log is one event longer, including an empty resumed log `session/end-seed` joins the on-disk vocabulary. Under the pre-release stance (`SESSION_FORMAT_VERSION` pinned at `0`, no compatibility promise) older logs simply lack it, and a log without a boundary correctly classifies nothing as constructor-seed history. -Not built here: no plugin reads the boundary yet. Wiring the compaction seam's staleness check to it is the follow-up that motivated this boundary; the predicate helper belongs with that seam, where a real consumer decides its shape, rather than shipping into core untested against one. +The [queued manual compaction decision](../feature/2026-07-30-queued-manual-compaction.md) now supplies the first consumer. Its tail scan independently finds the unmatched `compact/start` and newest end-seed, treats only a start after that boundary as live, and clears the invariant trace on the same replay transition. The predicate remains in the compaction package rather than becoming a generic core helper. diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md index dca87e16de..d492c4ac5f 100644 --- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md @@ -52,4 +52,4 @@ Status: implemented `session/end-seed` 加入了落盘词汇表。在预发布立场下（`SESSION_FORMAT_VERSION` 固定为 `0`，不作兼容承诺），更旧的日志只是没有它，而没有边界的日志会正确地判定没有任何内容属于构造种子历史。 -此处未做：还没有任何插件读取该边界。把压缩 seam 的陈旧性检查接到它上面，是催生这条边界的后续工作；谓词辅助函数应当归属那个 seam——在那里由真实消费方决定它的形状——而不是未经真实消费方检验就先落进核心。 +[排队手动压缩决策](../feature/2026-07-30-queued-manual-compaction.md)如今提供了第一个消费方。其尾部扫描会分别查找未匹配的 `compact/start` 与最新 end-seed，只把位于该边界之后的 start 视为活动锁，并在同一个回放转换上清除不变量追踪状态。该谓词仍位于压缩包中，不会成为通用核心辅助函数。 diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml index 7ee4b1fac8..8926d51744 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml @@ -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/bug-fix/2026-07-29-human-transcript-append-origin.md -2026-07-29-human-transcript-append-origin.md: dcc4a786c6f1926f06dce03124ec1d8ca805d7ae -2026-07-29-human-transcript-append-origin.zh.md: 0fefc52afa52e99cdec2bcea1a86b9c28711dd67 +2026-07-29-human-transcript-append-origin.md: a47dd49dd831cdd32d520137417bf47d2c056a09 +2026-07-29-human-transcript-append-origin.zh.md: 31639bd9aac5d6dace80392004f37c747bff2c36 diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md index dcc4a786c6..a47dd49dd8 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md @@ -26,7 +26,7 @@ No persisted event, RPC envelope, compaction transaction, or model-visible surfa The browser client is fixed separately, in [the web transcript projection note](2026-07-30-web-transcript-log-ordered-projection.md): it projects the same append-origin transcript in log order and renders a marker component, and it closes the pagination hole this change opened — because `session.history` no longer spends quota on the checkpoint, it never cuts on the checkpoint's provenance group, so a page can carry a checkpoint citing a `surfaceOp.start` outside the window, which the browser's surface fold rejected. That hole predates this change (counting could already run past a checkpoint into the range it shadows), but the old rule accidentally covered the case where the checkpoint was the oldest counted message and pulled the whole shadowed range onto its page. -Rendering compaction *progress* — a terminal indicator while a compaction runs — needs the bracket-first ordering that the queued manual `/compact` work introduces, and is out of scope here. The marker also carries no scale: the checkpoint's `sourceEventSeqs` already hold the shadowed count, so a count or range would tell a reader how much each row folded. That belongs with progress, where the reader meets the other half of the same information. Whoever takes it should fold the terminal's two replacement branches — replay and the live listener, textually identical and 600 lines apart — into one `renderReplacement(event)` first, so the marker's content has a single home. +The terminal's [live compaction progress decision](../feature/2026-07-30-compaction-progress-visibility.md) uses standalone bracket events to drive the existing one-cell indicator. It does not change the completion marker owned here or add scale: the checkpoint's `sourceEventSeqs` remain available for a separately justified count or range. Progress therefore needs neither marker-content changes nor a prerequisite `renderReplacement(event)` extraction. ## Alternatives considered diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md index 0fefc52afa..31639bd9aa 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md @@ -26,7 +26,7 @@ Status: implemented 浏览器客户端在[Web 记录投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份 append 来源记录并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝该范围。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，其溯源分组把整段被遮蔽的范围一起拉到该页。 -渲染压缩*进度*——压缩运行期间的终端指示——需要排队式手动 `/compact` 工作引入的“先开括号”顺序，不在本次范围内。标记同样不携带规模信息：检查点的 `sourceEventSeqs` 已经包含被遮蔽的数量，因此一个计数或区间可以告诉读者每一行折叠了多少内容。这件事属于进度那一侧，读者正是在那里遇到同一份信息的另一半。接手者应当先把终端里两处替换分支——回放与实时监听器，文本完全相同却相隔 600 行——合并为一个 `renderReplacement(event)`，让标记的内容只有一个归处。 +终端的[实时压缩进度决策](../feature/2026-07-30-compaction-progress-visibility.md)使用独立标记对中的事件驱动现有的单格指示器。它既不改变本文所负责的完成标记，也不添加规模信息：检查点的 `sourceEventSeqs` 仍可供经另行论证的计数或区间使用。因此，进度显示既不需要修改标记内容，也不以提取 `renderReplacement(event)` 为前置条件。 ## Alternatives considered diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml index ff33e2219c..5d12a08e36 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml @@ -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/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md -2026-07-30-web-transcript-log-ordered-projection.md: 9fb338643774efaeb9deab6f66920a9f4276ce67 -2026-07-30-web-transcript-log-ordered-projection.zh.md: 7962dd432b8bbf115acde9dd480eba9c91f35bfc +2026-07-30-web-transcript-log-ordered-projection.md: 4bc629bfa619a2858ec0335a6136d3a5a24b025a +2026-07-30-web-transcript-log-ordered-projection.zh.md: d011ce9453bc1dbb9fdb62372aa1126c95ffb143 diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md index 9fb3386437..4bc629bfa6 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md +++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md @@ -69,4 +69,4 @@ The web e2e scenario now seeds a real compaction transaction over its recorded t ## Deferred -Compaction **progress** — an indicator while a compaction runs — needs the bracket-first ordering the queued manual-compaction work introduces, and stays out of scope here as it did in the terminal. The marker also carries no **scale**: the checkpoint's `sourceEventSeqs` already hold the shadowed count, so a count or range would tell a reader how much each row folded. Both belong together, where the reader meets the two halves of the same information. +The terminal's [compaction progress decision](../feature/2026-07-30-compaction-progress-visibility.md) uses the live standalone bracket to drive a one-cell indicator and does not change this browser projection. The marker still carries no **scale**: the checkpoint's `sourceEventSeqs` hold the shadowed count, so a separately justified count or range can be added without coupling it to progress. diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md index 7962dd432b..d011ce9453 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md @@ -69,4 +69,4 @@ Web e2e 场景现在在它录制的那一轮之上播种一次真实的压缩事 ## Deferred -压缩**进度**——压缩运行期间的指示——需要排队式手动压缩工作引入的“先开括号”顺序，与终端一样不在本次范围内。标记同样不携带**规模**信息：检查点的 `sourceEventSeqs` 已经包含被遮蔽的数量，因此一个计数或区间可以告诉读者每一行折叠了多少内容。两者应当放在一起，读者正是在那里遇到同一份信息的两半。 +终端的[压缩进度决策](../feature/2026-07-30-compaction-progress-visibility.md)使用实时独立标记对驱动单格指示器，并不改变此浏览器投影。标记仍不携带**规模**信息：检查点的 `sourceEventSeqs` 保存被遮蔽的数量，因此可以另行论证后添加计数或区间，而无须将其与进度耦合。 diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.i18n.yaml new file mode 100644 index 0000000000..12b3982d54 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.i18n.yaml @@ -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-07-31-hero-visible-while-blank-session-opens.md +2026-07-31-hero-visible-while-blank-session-opens.md: b39963beffa403ef6fa44735aa88395a99139751 +2026-07-31-hero-visible-while-blank-session-opens.zh.md: b451d7c00ec7eb8d736134e738d72e5e07fd1b04 diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md b/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md new file mode 100644 index 0000000000..b39963beff --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md @@ -0,0 +1,35 @@ +# Agent Note: Hero stays visible while a blank session opens + +Status: implemented + +English | [中文](2026-07-31-hero-visible-while-blank-session-opens.zh.md) + +## Problem + +The conversation root has a `settling` phase for a session that is still opening while its composer reads `blank`: the hero-versus-docked outcome is unknowable until history arrives, so the composer seat is hidden (`visibility:hidden`) rather than flashing the centered hero and snapping to the docked bar. Startup auto-selection turned that guard into the defect it was meant to prevent. From the no-workspace hero, `WorkspacesService.startInitialSelection` connects the most recent workspace and opens its blank session; `openState` flips to `loading` the moment `open()` lands, so the center column went blank for the whole history round-trip and then repainted, which reads as a full-page refresh on every launch. + +## Decision + +`ConversationRoot` reads the session list summary's `blank` flag alongside the conversation snapshot and exempts summary-proven blank sessions from settling: `settling` additionally requires `summaryBlank !== true`, and `hero` accepts a blank composer whenever the summary proves the session blank, in every open state rather than only `loading`. A session the list already reports as blank can only land on the hero, so hiding buys nothing and costs the visible flash; the same proof holds before the open starts (`cold`) and after one fails (`error`), where the previous conditions fell through to the active phase and rendered a docked bare composer under chrome `ConversationSession` hides for blank sessions. Whenever the summary does not prove the session blank — a row reporting `blank: false`, or no row at all because the list has not caught up — `summaryBlank` is not `true` and the conservative settling hide is unchanged. + +The summary flag and the snapshot's own `blank` are distinct sources: the snapshot describes the session being opened, the summary is the list row that already exists before the open resolves. Only the latter is available early enough to decide the phase. + +## Alternatives considered + +**Drop the settling phase entirely.** Rejected because it still earns its keep for a session with no summary row: without a prior claim about emptiness, hero-versus-docked is genuinely unknowable and the flash it prevents is the worse one. + +**Delay the `loading` flip until history returns.** Rejected because `openState` is authoritative about the open operation; deferring it to suppress a presentation artifact would misreport the data state to every other consumer. + +**Cross-fade or otherwise animate the settling hide.** Rejected because the column has nothing to show during the round-trip either way — the fix is to not hide content whose outcome is already known, not to decorate the hiding. + +## Deferred + +The no-session→session tree relocation in `ConversationRoot` (the hero/composer subtree moves into the `conversation.session` outlet) still rebuilds the composer DOM on the same transition; removing it means moving `conversation.session` to `session-maybe` scope, a slot-contract change that needs its own proposal. + +Object-layer reference churn found while diagnosing this — no-op projections minting fresh snapshots, the create path projecting twice, `select()` using `notifyNow` from async continuations — is real but independent of the visible flash. + +## Consequences + +Startup auto-selection renders the hero immediately and keeps the composer seat and header visible through the history round-trip, so launching into a recent workspace no longer looks like a page reload. Sessions whose summary does not prove them blank keep the previous settling behavior, so the guard still covers the case it was written for. Skeleton tests pin all three summary shapes: a row reporting `blank: false` settles, an absent row settles, and a summary-proven blank session opening under `loading` renders hero chrome with a live textarea. + +The assembled coverage is `apps/web/tests/startup-auto-selection.e2e.ts` (keyless web browser lane): it registers a workspace, holds the `session.history` response open at the browser's network boundary, and asserts the visible frame while the auto-selected open is in flight — hero phase, hero title, painted composer — plus a recorded phase timeline of exactly `['hero']` for the whole load. Holding the round-trip is what makes it a regression test rather than a race: against a loopback host the open settles too fast to sample, and with the exemption reverted the held window is precisely when the root reports `settling`. diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md new file mode 100644 index 0000000000..b451d7c00e --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md @@ -0,0 +1,35 @@ +# Agent Note: 空白会话打开期间保持 hero 可见 + +Status: implemented + +[English](2026-07-31-hero-visible-while-blank-session-opens.md) | 中文 + +## 问题 + +会话根节点为"正在打开且 composer 处于 `blank`"的会话保留了一个 `settling` 阶段：在历史记录返回之前，hero 与 docked 的归属不可知，因此宁可隐藏 composer 座位（`visibility:hidden`），也不要先闪出居中的 hero 再跳到底部输入条。启动时的自动选择把这道防护变成了它本要防止的缺陷。从无工作区的 hero 进入时，`WorkspacesService.startInitialSelection` 会连接最近的工作区并打开其空白会话；`open()` 一落地 `openState` 立即翻为 `loading`，中间栏因此在整个历史往返期间保持空白，随后重绘一次——每次启动看起来都像整页刷新。 + +## 决策 + +`ConversationRoot` 在读取会话快照的同时读取会话列表摘要的 `blank` 标志，并让"摘要已证明为空白"的会话豁免 settling：`settling` 额外要求 `summaryBlank !== true`，而 `hero` 在摘要证明会话为空白时接受处于 blank 的 composer——覆盖全部 open state，而非仅 `loading`。列表已报告为空白的会话只可能落到 hero，因此隐藏毫无收益，只换来一次可见闪烁；同一份证明在打开开始之前（`cold`）与打开失败之后（`error`）同样成立，而此前的条件会在这两种状态下落到 active 阶段，在 `ConversationSession` 为空白会话隐藏的外壳之下渲染出一条停靠的裸 composer。只要摘要没有证明会话为空白——无论是报告 `blank: false` 的行，还是列表尚未跟上因而根本没有该行——`summaryBlank` 都不为 `true`，保守的 settling 隐藏行为保持不变。 + +摘要标志与快照自身的 `blank` 是两个不同来源：快照描述正在打开的这个会话，摘要则是在打开操作完成之前就已存在的列表行。只有后者足够早，可用于决定阶段。 + +## 备选方案 + +**彻底移除 settling 阶段。** 否决，因为对没有摘要行的会话它仍有价值：在缺少任何关于"是否为空"的先验断言时，hero 与 docked 的归属确实不可知，而它所防止的那种闪烁更糟糕。 + +**推迟 `loading` 的翻转，直到历史返回。** 否决，因为 `openState` 是打开操作的权威状态；为了压制一个呈现层瑕疵而推迟它，会向其他所有消费者误报数据状态。 + +**为 settling 的隐藏加交叉淡入或其他动画。** 否决，因为无论如何该栏在往返期间都没有内容可展示——正确的修复是不隐藏结局已知的内容，而不是把隐藏装饰得好看些。 + +## 推迟事项 + +`ConversationRoot` 中"无会话→有会话"的树位置迁移（hero/composer 子树移入 `conversation.session` 出口）仍会在同一次转换中重建 composer 的 DOM；消除它意味着把 `conversation.session` 移到 `session-maybe` 作用域，这是一次插槽契约变更，需要单独立项。 + +诊断期间发现的对象层引用抖动——空操作投影铸造出新的快照、创建路径重复投影一次、`select()` 在异步续体中使用 `notifyNow`——确实存在，但与这次可见闪烁相互独立。 + +## 影响 + +启动自动选择会立即渲染 hero，并在整个历史往返期间保持 composer 座位与 header 可见，因此启动进入最近工作区不再像页面重载。摘要未证明为空白的会话保持原有的 settling 行为，这道防护仍覆盖它当初针对的场景。骨架测试固定了摘要的三种形态：报告 `blank: false` 的行进入 settling；根本没有该行同样进入 settling；摘要已证明为空白的会话在 `loading` 期间渲染 hero 外壳与可用的文本框。 + +组装级覆盖是 `apps/web/tests/startup-auto-selection.e2e.ts`（无密钥的 Web 浏览器泳道）：它注册一个工作区，在浏览器网络边界上扣住 `session.history` 的响应，并在自动选择的打开仍在飞行途中断言可见画面——hero 阶段、hero 标题、已绘制的 composer——外加整次加载记录到的阶段时间线恰好为 `['hero']`。扣住这次往返正是它成为回归测试而非竞态的原因：对着回环主机，打开会快到无从采样；而一旦回退这条豁免，被扣住的这段窗口恰恰就是根节点报告 `settling` 的时刻。 diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-same-basename-workspace-adoption.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-same-basename-workspace-adoption.i18n.yaml new file mode 100644 index 0000000000..990e7e39bb --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-31-same-basename-workspace-adoption.i18n.yaml @@ -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-07-31-same-basename-workspace-adoption.md +2026-07-31-same-basename-workspace-adoption.md: ed53804ea64df0d61db16e579c3d65af803dbb97 +2026-07-31-same-basename-workspace-adoption.zh.md: 82cfb7d90afca28f8e666742a758fda0202909f3 diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-same-basename-workspace-adoption.md b/.agents/notes/implemented/bug-fix/2026-07-31-same-basename-workspace-adoption.md new file mode 100644 index 0000000000..ed53804ea6 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-31-same-basename-workspace-adoption.md @@ -0,0 +1,37 @@ +# Agent Note: Same-basename Workspace adoption + +Status: implemented + +English | [中文](2026-07-31-same-basename-workspace-adoption.zh.md) + +## Problem + +A Workspace is identified by its stable id and canonical directory path, while its title is mutable display metadata. The registry nevertheless rejected a new canonical path when its basename-derived title matched another Workspace. Common directory layouts such as `/a/xx` and `/b/xx` therefore could not coexist in the Web UI, even though the [domain design](../../proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md) already permits duplicate titles and every client operation addresses a Workspace by id. + +## Decision + +`ctx.workspace.create(path, title?)` treats canonical path as the only uniqueness key. Repeating the same path remains idempotent and preserves the registered title. Different canonical paths create different Workspace records and may share a title; when no title is supplied, each record still derives its title from `basename(path)` without suffixing or rewriting it. + +The Host's `workspace.create({ path })` adoption route inherits that rule. The Workspace manager, picker, grouping tree, selection, rename, deletion, and Session creation continue to use `WorkspaceId`, so equal labels neither merge records nor redirect an operation. The sidebar hover card exposes each canonical path when the labels need disambiguation. + +Explicit naming remains stricter. `workspace.create({ name })` and `workspace.rename` continue to reject a title already registered, as described by [manual Workspace naming](../feature/2026-07-25-session-list-browsing-and-manual-order.md). This prevents a user from deliberately introducing another ambiguous label while accepting collisions imposed by existing directory names. The path-adoption rule supersedes only the title-conflict clauses in the [Workspace product flow](../feature/2026-07-25-workspace-ui-product-flow.md) and [native directory picker](../feature/2026-07-27-native-workspace-directory-picker.md). + +The durable schema does not change: Workspace records already store id, path, and title independently, bootstrap can derive equal basenames, and startup validates duplicate paths rather than titles. + +## Verification + +Workspace registry and Host API tests create two real directories under different parents with the same final segment and assert distinct ids, paths, and durable order. The picker component renders equal labels as separate id-keyed entries. The keyless Web browser scenario adopts both directories through the composed directory flow and observes two registered and rendered Workspaces. + +## Alternatives considered + +**Keep title uniqueness and reject the second directory.** A display label would remain an accidental identity key and ordinary multi-root layouts would stay impossible to register. + +**Suffix colliding titles automatically.** A generated label such as `xx (2)` would no longer be the directory-derived title, would need stable allocation rules across deletion and reload, and would add state solely to conceal an identity mistake. + +**Use the full path as every Workspace title.** This removes the collision but makes the primary navigation label unnecessarily long. The full path remains available in the hover detail while the concise basename stays useful. + +**Permit collisions from explicit rename and create-by-name operations too.** The registry supports that state, but those operations intentionally ask the user to choose a display name. Retaining their conflict response preserves the existing naming guard without blocking filesystem-selected paths. + +## Consequences + +Two Workspace rows may carry the same visible title. They remain independently selectable and actionable because ids own identity; users can inspect the path or rename either row to disambiguate it. An explicit rename cannot select another row's current title, including a title that arose from same-basename adoption. No storage migration or compatibility path is required. diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-same-basename-workspace-adoption.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-same-basename-workspace-adoption.zh.md new file mode 100644 index 0000000000..82cfb7d90a --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-31-same-basename-workspace-adoption.zh.md @@ -0,0 +1,37 @@ +# Agent Note: 接纳 basename 相同的 Workspace + +Status: implemented + +[English](2026-07-31-same-basename-workspace-adoption.md) | 中文 + +## 问题 + +Workspace 的身份由其稳定 id 和规范目录路径确定，标题则是可变的显示元数据。然而，只要新规范路径按 basename 派生出的标题与另一个 Workspace 相同，注册表就会拒绝该路径。因此，`/a/xx` 和 `/b/xx` 等常见目录布局无法同时出现在 Web UI 中，尽管[领域设计](../../proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)早已允许标题重复，而且每项客户端操作都通过 id 定位 Workspace。 + +## 决策 + +`ctx.workspace.create(path, title?)` 仅以规范路径作为唯一性键。重复传入同一路径仍保持幂等，并保留已注册的标题。不同的规范路径会创建不同的 Workspace 记录，且可以共用标题；未提供标题时，每条记录仍从 `basename(path)` 派生标题，不添加后缀，也不改写标题。 + +Host 的 `workspace.create({ path })` 接纳入口沿用该规则。Workspace 管理器、选择器、分组树、选择、重命名、删除和 Session 创建仍使用 `WorkspaceId`，因此相同标签既不会合并记录，也不会把操作指向其他记录。需要区分相同标签时，侧边栏悬停详情卡会显示各自的规范路径。 + +显式命名仍采用更严格的规则。`workspace.create({ name })` 和 `workspace.rename` 仍会拒绝已注册的标题，具体见[手动 Workspace 命名](../feature/2026-07-25-session-list-browsing-and-manual-order.md)。这既防止用户主动引入另一个难以区分的标签，又允许既有目录名称造成的重名。路径接纳规则仅取代 [Workspace 产品流](../feature/2026-07-25-workspace-ui-product-flow.md)和[原生目录选择器](../feature/2026-07-27-native-workspace-directory-picker.md)中的标题冲突条款。 + +持久化 schema 未变：Workspace 记录本就分别存储 id、path 和 title，引导初始化可以派生出相同的 basename，启动校验检查的是重复路径而非重复标题。 + +## 验证 + +Workspace 注册表与 Host API 测试会在不同父目录下创建两个末级名称相同的真实目录，并断言其 id 和路径互不相同，且持久顺序正确。选择器组件将相同标签渲染为按 id 区分的独立条目。无密钥 Web 浏览器场景通过组合而成的目录流程接纳这两个目录，并观察到两个 Workspace 均已注册且完成渲染。 + +## 考虑过的替代方案 + +**保持标题唯一，并拒绝第二个目录。** 显示标签仍会意外充当身份键，普通的多根目录布局仍无法注册。 + +**自动为冲突标题添加后缀。** 像 `xx (2)` 这样的生成标签将不再是从目录派生的标题；系统还需要制定跨删除与重载保持稳定的分配规则，并且只为掩盖身份判定错误而增加状态。 + +**将完整路径用作每个 Workspace 的标题。** 这会消除冲突，却使主导航标签不必要地过长。完整路径仍可在悬停详情中查看，而简洁的 basename 仍有价值。 + +**也允许显式重命名和按名称创建操作产生重名。** 注册表支持这种状态，但这些操作本就是明确要求用户选择显示名称。保留冲突响应可维持现有命名防护，同时不阻止从文件系统选取的路径。 + +## 后果 + +两个 Workspace 行可能显示相同的可见标题。id 负责身份，因此两行仍可独立选择和操作；用户可以查看路径或重命名任一行以作区分。显式重命名不能采用另一个行当前使用的标题，即使该标题源自 basename 相同的目录接纳。无需存储迁移或兼容路径。 diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml new file mode 100644 index 0000000000..c20d347fc9 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml @@ -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-07-31-web-stop-preserves-queue.md +2026-07-31-web-stop-preserves-queue.md: 943e95d6951a28929c4f8ce4d0b6e17224b08ede +2026-07-31-web-stop-preserves-queue.zh.md: bbadd8adf8fd5bb0604ef87d322e48ce4c2ed759 diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.md b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.md new file mode 100644 index 0000000000..943e95d695 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.md @@ -0,0 +1,37 @@ +# Agent Note: Web stop preserves pending Queue + +Status: implemented + +English | [中文](2026-07-31-web-stop-preserves-queue.zh.md) + +## Problem + +The Web stop button reached `session.cancel`, which mapped to broad `agent.cancel({ kind: 'user' })`. During an active turn, ordinary composer submissions are already accepted as independently addressable Queue occurrences. Broad cancellation discarded every occurrence when the user intended to stop only the current generation, conflating turn interruption with the Queue's explicit delete operation. + +The browser cannot repair that loss by resending visible rows. It does not own their live `InboxItemId`, wake policy, or claim race, and a resend can duplicate work that the Host has already claimed. + +## Decision + +`session.cancel` is the Web Host API's active-turn stop. It calls `agent.cancel({ kind: 'user' }, { keepInbox: true })`, preserving pending inbox work while cooperatively aborting the current turn. The underlying option preserves queued and steering entries; the Web Queue projection continues to expose only queued entries. + +The AgentLoop starts no concurrent replacement turn. It closes and flushes the interrupted turn, reaches cancellation quiescence, and then claims the next waking queued occurrence through its existing FIFO driver. That claim emits `agent/inbox/dequeue`, so the Host's authoritative `session/queue` snapshot retires the claimed row and leaves the remaining tail visible. The browser neither resends nor promotes any row. Work that ignores cancellation delays this handoff until it settles. + +This mapping changes only the Host `session.cancel` endpoint used by Web clients. The default `Agent.cancel()` contract remains broad, ACP and TUI retain their existing cancellation policies, and `AgentHandle.dispose()` still clears pending work during teardown. Queue row removal remains the explicit Web action for discarding one pending occurrence. + +## Alternatives considered + +**Keep broad cancellation for the stop button.** Rejected because stopping one generation should not destroy independently queued user intent; the Queue already owns explicit deletion. + +**Resend the next row from the browser after cancellation.** Rejected because the Host owns occurrence identity and claim order. Client resubmission can duplicate work, reorder the FIFO, or race an authoritative dequeue. + +**Start the next turn before cancelled work reaches quiescence.** Rejected because two turns would concurrently mutate one session log and share Agent-owned resources. Cooperative cancellation waits truthfully for the active work to settle. + +**Add a wire option for broad versus preserving cancellation.** Rejected until the Web product has a separate “stop and clear Queue” interaction. The existing stop button has one policy, while per-row delete already supplies the current discard control. + +## Verification + +AgentLoop coverage holds an active model stream, queues two waking turns, cancels with `keepInbox`, and pins the aborted-then-completed turn reasons, FIFO user-message order, absence of discard events, and eventual idle state. The keyless Web scenario drives the built composition over HTTP/SSE: it stops one hung turn, observes the next queued occurrence start while the tail remains visible, stops that turn, and observes the final queued occurrence complete. Its accessibility snapshot pins the intermediate preserved-Queue state. + +## Consequences + +Web stop preserves accepted queued intent and advances it automatically after truthful cancellation settlement. Queue rows may remain visible while uncooperative active work winds down, and external steering preserved by the same inbox option can enter the next admitted turn even though Web does not render steering in QueueDock. A future bulk-clear interaction requires an explicit product action rather than overloading stop. diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md new file mode 100644 index 0000000000..bbadd8adf8 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md @@ -0,0 +1,37 @@ +# Agent Note: Web 停止操作保留待处理 Queue + +Status: implemented + +[English](2026-07-31-web-stop-preserves-queue.md) | 中文 + +## 问题 + +Web 停止按钮调用 `session.cancel`，后者映射到广义 `agent.cancel({ kind: 'user' })`。在活动轮次期间，普通 composer 提交已经被接纳为可独立寻址的 Queue 入队项。用户只想停止当前生成时，广义取消却会丢弃所有入队项，混淆了轮次中断与 Queue 的显式删除操作。 + +浏览器无法通过重发可见行修复这一损失。它不拥有这些行的实时 `InboxItemId`、唤醒策略或认领竞态；重发还可能重复 Host 已认领的工作。 + +## 决策 + +`session.cancel` 是 Web Host API 的活动轮次停止操作。它调用 `agent.cancel({ kind: 'user' }, { keepInbox: true })`，在协作式中止当前轮次的同时保留待处理 inbox 工作。底层选项会保留 queued 和 steering 入队项；Web Queue 投影继续只暴露 queued 入队项。 + +AgentLoop 不会启动并发的替代轮次。它会关闭并 flush 被中断的轮次，达到取消的完全停稳，然后通过现有 FIFO 驱动器认领下一个可唤醒的 queued 入队项。该认领会发出 `agent/inbox/dequeue`，因此 Host 的权威 `session/queue` 快照会退役已认领行，并使剩余队尾保持可见。浏览器既不重发，也不提升任何行。忽略取消的工作会延迟这一交接，直到该工作结算。 + +该映射只更改 Web 客户端使用的 Host `session.cancel` 端点。`Agent.cancel()` 默认契约仍为广义取消，ACP 和 TUI 保留既有取消策略，`AgentHandle.dispose()` 在拆卸期间仍会清除待处理工作。移除 Queue 行仍是用于丢弃单个待处理入队项的显式 Web 操作。 + +## 考虑过的替代方案 + +**停止按钮继续使用广义取消。** 之所以否决：停止一次生成不应销毁已独立排队的用户意图；Queue 已拥有显式删除操作。 + +**取消后由浏览器重发下一行。** 之所以否决：Host 拥有入队项标识和认领顺序。客户端重新提交可能重复工作、重排 FIFO，或与权威出队产生竞态。 + +**被取消工作达到完全停稳之前启动下一轮次。** 之所以否决：两个轮次会并发修改同一会话日志，并共享 Agent 拥有的资源。协作式取消会如实等待活动工作结算。 + +**为广义取消与保留式取消添加协议选项。** 之所以否决：在 Web 产品提供独立的「停止并清空 Queue」交互之前，不需要此选项。现有停止按钮只有一项策略，而逐行删除已提供当前的丢弃控件。 + +## 验证 + +AgentLoop 覆盖会保持一个活动模型流，将两个可唤醒轮次排队，使用 `keepInbox` 取消，并固定验证先中止、后完成的轮次原因，FIFO 用户消息顺序，不存在 discard 事件，以及最终空闲状态。无密钥 Web 场景通过 HTTP／SSE 驱动已组装组合：它停止一个卡住的轮次，观察队尾保持可见时下一个 queued 入队项开始，再停止该轮次，并观察最后一个 queued 入队项完成。其可访问性快照固定了中间的 Queue 保留状态。 + +## 后果 + +Web 停止会保留已接纳的排队意图，并在取消如实结算后自动推进。不配合取消的活动工作收尾时，Queue 行可能仍保持可见；由同一 inbox 选项保留的外部 steering 可以进入下一个已接纳轮次，尽管 Web 不会在 QueueDock 中渲染 steering。未来的批量清空交互需要显式的产品操作，而不是过载停止。 diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml index 414c63211a..714b75d942 100644 --- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml @@ -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-06-18-compaction-capability-seam.md -2026-06-18-compaction-capability-seam.md: 3c219b734e148b963fb5857de89c16f28c2bd402 -2026-06-18-compaction-capability-seam.zh.md: b2c7e9720b596705b60a284e6ccf1448a782b7fc +2026-06-18-compaction-capability-seam.md: ef37313bc6fb984689793fa5a3e7ac4d9238ea88 +2026-06-18-compaction-capability-seam.zh.md: 9f123a8c40f303a2635af78cafd34de448e27e03 diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md index 3c219b734e..ef37313bc6 100644 --- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md +++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md @@ -18,10 +18,10 @@ Two forces shape the design. First, compaction policy and reusable token measure Per the [capability-seams Agent Note](../architecture/2026-06-13-capability-seams.md), compaction ships as separate packages so the contract, the algorithm, and (later) the consumer surface evolve independently: -1. **Interface** — `@deepseek-ai/dsh-compact`: an abstract `CompactService` owning the `ctx.compact` key, the `CompactionResult` vocabulary, the `compact/*` session events, and the canonical checkpoint message source. It declares `compactIfNeeded()` and `compactRegion()` as **abstract** — the contract states *what* compaction does, not *how*. +1. **Interface** — `@deepseek-ai/dsh-compact`: an abstract `CompactService` owning the `ctx.compact` key, the `CompactionResult` vocabulary, the `compact/*` session events, the manual failure taxonomy, and the canonical checkpoint message source. It declares `compactIfNeeded()`, `compactNow()`, and `compactRegion()` as **abstract** — the contract states *what* compaction does, not *how*. 2. **Implementation** — `@deepseek-ai/dsh-compact-basic`: a concrete `BasicCompactService` that consumes `ctx.tokenMeter` and owns the tail→head retention walk, summarization via `ctx.llm.stream()`, the surface replacement, the lock, post-step pressure, and canonical context-overflow recovery. `summarize()` is its sole subclass hook; pricing and replay stay with the meter. 3. **Model-free companion** — `@deepseek-ai/dsh-compact-tool-result-prune`: a concrete optional service that rewrites oversized current `tool/result` nodes before the backend selects a summary range. It is not a second compaction implementation and does not implement `CompactService`. -4. **Consumer** — deferred. A `/compact` tool and slash command will `inject: ['compact']` and call the contract; they are intentionally out of scope here so the seam settles first. +4. **Human consumer** — `@deepseek-ai/dsh-command-compact` registers argument-free `/compact` through `ctx.commands` and calls the backend-independent `compactNow()` operation. It is direct human control, not a model-facing tool. ### The contract depends on `dsh-session` and `dsh-llm` — a deliberate deviation @@ -29,11 +29,11 @@ The capability-seams Agent Note states the interface package "depends only on co This is not a coupling smell — it is the contract's domain. The "only cordis" guidance was always shorthand for "the interface depends only on what the contract genuinely names, and never on an implementation." `dsh-session` and `dsh-llm` are themselves interface/vocabulary packages, not implementations; `dsh-compact` still imports no backend. The seam's real invariant — *consumers and implementations evolve independently behind an abstract service* — holds intact. -### Abstract `compactIfNeeded` / `compactRegion`, algorithm in the backend +### Three abstract operations, algorithm in the backend -An earlier draft put the full algorithm (the retention walk, token-summing, text extraction) as concrete methods on the interface. That recouples the contract to one strategy: a backend that wants a different retention policy or event sequence would have to fight inherited concrete code. Making both core methods abstract puts every *how* decision in the backend and keeps the interface a statement of *what*. Token measurement is not a compaction hook at all; the singleton service lets multiple consumers share one per-session replay fold. +An earlier draft put the full algorithm (the retention walk, token-summing, text extraction) as concrete methods on the interface. That recouples the contract to one strategy: a backend that wants a different retention policy or event sequence would have to fight inherited concrete code. Making all three operations abstract puts every *how* decision in the backend and keeps the interface a statement of *what*. Token measurement is not a compaction hook at all; the singleton service lets multiple consumers share one per-session replay fold. -`compactIfNeeded(agent, trigger, signal)` takes an explicit `'pressure' | 'context-overflow'` trigger and cancellation. It reads only the latest durable routed request; no header means no work, while any routed provider/model target uses the singleton estimator. `compactRegion(start, end, agent, signal?)` uses `agent.session` as its single session identity and keeps an optional signal for manual callers. The default summarizer resolves its target from explicit config, the latest logged routed target, then agent options, and records the provider/model pair after any `llm/stream` routing. It replays the routed request's prefix and appends the compaction directive as a trailing user message so the provider's warm KV cache is reused — see the [summary prefix-cache Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md). The call sets the provider-neutral `GenerateOptions.purpose` to `compaction`; adapters may map that purpose to model-hidden transport metadata, and the DeepSeek adapter sends `x-deepseek-harness-compact: 1`. +`compactIfNeeded(agent, trigger, signal)` takes an explicit `'pressure' | 'context-overflow'` trigger and cancellation. It reads only the latest durable routed request; no header means no work, while any routed provider/model target uses the singleton estimator. `compactNow(agent, signal)` reserves idle turn admission and performs one useful balanced reduction even below pressure, returning `null` without writes when none exists. `compactRegion(start, end, agent, signal?)` uses `agent.session` as its single session identity and keeps an optional signal for explicit callers. The default summarizer resolves its target from explicit config, the latest logged routed target, then agent options, and records the provider/model pair after any `llm/stream` routing. It replays the routed request's prefix and appends the compaction directive as a trailing user message so the provider's warm KV cache is reused — see the [summary prefix-cache Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md). The call sets the provider-neutral `GenerateOptions.purpose` to `compaction`; adapters may map that purpose to model-hidden transport metadata, and the DeepSeek adapter sends `x-deepseek-harness-compact: 1`. ### Automatic pressure runs after successful durable step work @@ -91,42 +91,44 @@ The basic backend wraps the summary as established checkpoint context and tags i ### Blocking via a log-recorded lock, plus a crash/recoverable failure taxonomy -The `compact/start … compact/end` bracket is justified, in order of what now does the work: +The `compact/start … compact/end` bracket is justified by two roles: 1. **Crash-detectable orphan + provenance** (primary). Summarization is a slow model call persisted *after* `compact/start`. A crash mid-summarization leaves a `compact/start` with no matching `compact/end` — a detectable orphan. Releasing the lock last (rather than first) converts the crash window from *silent corruption* into that detectable orphan. -2. **Prevents concurrent compaction.** `compactRegion` refuses to start if the current turn holds an unmatched `compact/start`. (The loop is single-threaded across either awaited automatic seam, so this is also a re-entry tripwire — a thrown "already in progress" signals a real bug.) +2. **Prevents concurrent compaction.** Every automatic, manual, and explicit-range entry point refuses a live unmatched `compact/start`. The bracket is the single lock; no process-local mutex duplicates it. -The lock excludes another compaction, not unrelated log-only facts. The basic backend snapshots the token meter's surface nodes after `compact/start` and compares them again after asynchronous summarization; any surface mutation rejects before replacement, while a title or other log-only append leaves the selected span valid. +The lock excludes another compaction, not unrelated facts. Its markers are time points rather than an exclusive container, so idle injected context may appear between a standalone manual start and end. Automatic work requires whole-surface stability inside its turn. Manual work revalidates only the selected positional span, letting append-only context outside it remain visible after replacement. -Two failure paths, both documented: +The lifecycle boundary makes crash state unambiguous: -- **Crash** (the loop dies mid-summarization): a dangling `compact/start`, no closer. Because `compact/*` are **log-only**, the orphan is **inert** — no summary replacement lands. The derived surface remains the durable surface present at `compact/start`: full history when pruning made no replacement, or the already-pruned history when it did. Generic turn-repair (`interruptedTurnClosers`) closes the turn with a synthetic `turn/end`; the orphan sits *before* that `turn/end`, so the turn-scoped in-progress check never sees it and a crash cannot wedge future compaction. -- **Recoverable** (summarization throws but the loop survives): the backend appends `compact/end` with its **`error`** field set and lands no summary replacement. Post-step pressure warns and continues from the latest durable surface — full history if no replacement preceded the attempt, or the pruned surface if pruning already landed. Overflow recovery delegates only before any replacement; generation progress from earlier pruning authorizes a retry from that durable surface unless cancellation or disposal wins. +- **Current lifecycle:** a dangling `compact/start` after the newest `session/end-seed` is the live durable lock and reports busy. +- **Later lifecycle:** a newer constructor-written `session/end-seed` proves that the older unmatched start is stale, so resume, fork, and adoption do not remain wedged by a dead writer. +- **Recoverable failure:** once start lands, the backend makes exactly one `compact/end { error }` attempt. Summary or stability failure leaves the conversation surface unchanged while preserving the failed attempt in the log. If the close append fails, the unmatched start remains intentionally blocking. `compact/end` keeps its `error?` field (mirroring `tool/result`'s self-contained error — one event tells success from failure without correlating a sibling). There is no separate `compact/error` event. -**Core session repair stays compaction-agnostic — deliberately.** `interruptedTurnClosers` is never taught about `compact/*`. Teaching it would force every future `xxx/start … xxx/end` plugin pair to patch a core module — exactly the coupling the capability-seam architecture exists to avoid. Because the log-only orphan is inert, no special repair is needed: generic turn-repair plus the inertness of an un-landed surface mutation is sufficient. +**Core session repair stays compaction-agnostic — deliberately.** `interruptedTurnClosers` is never taught about `compact/*`. The general `session/end-seed` lifecycle boundary supplies the evidence the compaction owner needs; the compaction invariant and backend interpret it without adding plugin-specific repair to core. ## Alternatives considered -- **The full algorithm as concrete interface methods** — rejected because it recouples the contract to one retention strategy. Both core methods are abstract; reusable measurement is a separate LLM-family service and `summarize()` is basic's sole hook. +- **The full algorithm as concrete interface methods** — rejected because it recouples the contract to one retention strategy. All three operations are abstract; reusable measurement is a separate LLM-family service and `summarize()` is basic's sole hook. - **Compaction on `agent/request` or provisional `agent/pre-step` inputs** — rejected because neither proves the final durable request and both couple generic lifecycle to compaction-specific envelope data. Post-step replay plus canonical overflow recovery covers both successful and rejected calls. - **A `compact` boolean or untyped request metadata map** — rejected because multiple auxiliary call kinds would become mutually exclusive flags, while an open bag would discard compiler-checked vocabulary. One typed `purpose` discriminant extends with additional call kinds without adding another `GenerateOptions` field. - **A separate `compact/error` event** — rejected: `compact/end` keeps an `error?` field, mirroring `tool/result`'s self-contained error — one event tells success from failure without correlating a sibling. -- **Teaching core turn-repair about `compact/*`** — rejected: the log-only orphan is inert, and a core module patched for every future `xxx/start … xxx/end` plugin pair is exactly the coupling the capability-seam architecture exists to avoid. +- **Teaching core turn-repair about `compact/*`** — rejected: the general end-seed boundary already distinguishes prior-lifecycle history, and patching core for every future `xxx/start … xxx/end` pair is exactly the coupling the capability-seam architecture exists to avoid. ## Consequences -- **Packages**: `packages/compact/compact` supplies the interface, `compact-basic` supplies the backend, and `compact-tool-result-prune` supplies optional deterministic rewriting. `packages/llm/token-meter` owns replay-aware measurement independently. The consumer tier is deferred. +- **Packages**: `packages/compact/compact` supplies the interface, `compact-basic` supplies the backend, `compact-tool-result-prune` supplies optional deterministic rewriting, and `command-compact` supplies human `/compact`. `packages/llm/token-meter` owns replay-aware measurement independently. - **Automatic seams**: `agent/post-step` (`@mode serial`) handles successful-call pressure and `agent/request-error` (`@mode waterfall`) handles final request failures after the failed step closes. Generic `agent/pre-step` remains a four-argument checkpoint with no compaction-only prompt/prefix payload. - **`SessionEventMap`** gains `compact/start` / `compact/summary` / `compact/end` by declaration merging (merge-extensible); `SurfaceEventType` is **not** touched. These are session events, not cordis `Events`, so the event-taxonomy gate needs no entry. - **`dsh-compact`** owns `COMPACT_CHECKPOINT_SOURCE`, `isCompactCheckpointSource(source)`, `toolPairingBalancedBefore(session, seq)`, and `toolPairingBalancedAfter(session, seq)`. The marker identifies replacement summaries across backend implementations. The cached surface-edge checks prevent `compactRegion` and `compactIfNeeded` from splitting a tool-call/result pair, validate current membership by seq, answer both edges from one per-cut balance sequence, and reject stale or missing seqs and orphan results. -- **`dsh-session`** validates positional replacement, complete provenance, and content-only single-node `tool/result` rewrites through its one surface manager. Its invariant companion treats fresh appended tool results as executions that require an open step and pending call; validated replacements remain turn-enclosed rewrites. -- **Wiring**: `examples/tui-agent/cordis.yml` loads zero-config `dsh-token-meter`, `dsh-compact-tool-result-prune`, then `dsh-compact-basic`; service-wide defaults make the composition usable without repeated numeric policy. +- **`dsh-session`** validates positional replacement, complete provenance, and content-only single-node `tool/result` rewrites through its one surface manager. Its invariant companion treats fresh appended tool results as executions that require an open step and pending call, while the compaction companion owns numeric-turn versus standalone-null bracket relations. +- **Wiring**: `examples/tui-agent/cordis.yml` loads zero-config `dsh-token-meter`, `dsh-compact-tool-result-prune`, `dsh-compact-basic`, then `dsh-command-compact`; service-wide defaults make the composition usable without repeated numeric policy. ## Testing - **Unit:** Real Loader and invariant plugins cover whole-unit retention, pruning configuration and replay, rich-block ordering, metadata preservation, convergence, both `compact/end` outcomes, open-tail refusal, pruning-only and summarized overflow recovery, generation proof, caps, and original-error preservation. - **Loop:** Tests pin post-step after durable tool results and before `step/end`, actual `agent/request` routing, closed failed steps, fresh retry numbering, and complete thrown/in-band overflow → compaction → reconstructed retry composition. +- **Manual:** Admission, marker ordering, injection retention, live/stale orphan classification, cancellation, close/flush failures, command mapping, and the queued TUI journey are pinned without a model key. - **With-key e2e:** A real model and bash session with lowered limits triggers compaction, records a complete `compact/start…end` pair, shrinks the surface, and finishes the task. - **Snapshot gap:** Runaway-turn compaction cannot yet replay because the summarization call records no `assistant/chunk` events or `sessionId`; interleaved summarization-call replay remains follow-up work. diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md index b2c7e9720b..9f123a8c40 100644 --- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md +++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md @@ -18,10 +18,10 @@ Status: implemented 遵循[能力 seam Agent Note（agent 决策记录）](../architecture/2026-06-13-capability-seams.md)，压缩以独立包（package）发布，使契约、算法和（后续的）消费方 surface 各自独立演进： -1. **接口** — `@deepseek-ai/dsh-compact`：抽象 `CompactService`，拥有 `ctx.compact` 键、`CompactionResult` 词汇、`compact/*` 会话事件以及规范的检查点消息来源。它将 `compactIfNeeded()` 和 `compactRegion()` 声明为**抽象方法**——契约说明压缩*做什么*，而非*怎么做*。 +1. **接口** — `@deepseek-ai/dsh-compact`：抽象 `CompactService`，拥有 `ctx.compact` 键、`CompactionResult` 词汇、`compact/*` 会话事件、手动失败分类体系以及规范的检查点消息来源。它将 `compactIfNeeded()`、`compactNow()` 和 `compactRegion()` 声明为**抽象方法**——契约说明压缩*做什么*，而非*怎么做*。 2. **实现** — `@deepseek-ai/dsh-compact-basic`：具体的 `BasicCompactService`，消费 `ctx.tokenMeter`，并拥有尾→头保留遍历、通过 `ctx.llm.stream()` 生成摘要、surface 替换、锁、步骤后压力处理和规范的上下文溢出恢复。`summarize()` 是其唯一的子类钩子；计价与回放仍归 meter 所有。 3. **无模型配套服务** — `@deepseek-ai/dsh-compact-tool-result-prune`：一个具体的可选服务，在后端选择摘要范围之前，重写当前过大的 `tool/result` 节点。它不是第二种压缩实现，也不实现 `CompactService`。 -4. **消费方** — 推迟。一个 `/compact` 工具和斜杠命令将 `inject: ['compact']` 并调用契约；它们被有意排除在本 Agent Note 范围之外，以便 seam 先稳定下来。 +4. **面向用户的消费方** — `@deepseek-ai/dsh-command-compact` 通过 `ctx.commands` 注册无参数 `/compact`，并调用后端无关的 `compactNow()` 操作。它是供用户直接控制的命令，不是面向模型的工具。 ### 契约依赖 `dsh-session` 和 `dsh-llm`——有意为之的偏离 @@ -29,11 +29,11 @@ Status: implemented 这不是耦合异味，而是契约的领域所在。「仅 cordis」的指导原则一直是「接口仅依赖契约真正需要命名的东西，绝不依赖实现」的简写。`dsh-session` 和 `dsh-llm` 本身是接口/词汇包，不是实现；`dsh-compact` 仍然不导入任何后端。seam 的真正不变式——*消费方和实现在抽象服务背后独立演进*——完好无损。 -### 抽象 `compactIfNeeded` / `compactRegion`，算法在后端 +### 三个抽象操作，算法在后端 -早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将契约重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将两个核心方法都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。 +早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将契约重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。 -`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为手动调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。 +`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 会预留空闲轮次接纳，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。 ### 成功的持久步骤工作完成后运行自动压力检查 @@ -91,42 +91,44 @@ compact/end → log-only. Releases the lock (carries `error` on a recoverab ### 通过日志记录的锁实现阻塞，加上崩溃/可恢复失败的分类 -`compact/start … compact/end` 括号的存在理由，按当前实际承担的职责排序： +`compact/start … compact/end` 标记对承担两项职责： 1. **可检测的崩溃孤儿 + 来源追溯**（首要）。摘要生成是一次慢速模型调用，持久化在 `compact/start` *之后*。摘要生成中途崩溃会留下一个没有匹配 `compact/end` 的 `compact/start`——一个可检测的孤儿。最后释放锁（而非最先）将崩溃窗口从*静默损坏*转变为可检测的孤儿。 -2. **防止并发压缩。** 如果当前轮次持有未匹配的 `compact/start`，`compactRegion` 拒绝启动。（循环在任一 awaited 自动 seam 上都是单线程的，因此这也是重入绊线——抛出「already in progress」表示真正的 bug。） +2. **防止并发压缩。** 每个自动、手动和显式范围入口点都会拒绝活动的未匹配 `compact/start`。该标记对就是唯一的锁；没有进程本地 mutex 重复承担同一职责。 -该锁只排除另一项压缩，不排除无关的仅日志事实。基础后端会在 `compact/start` 之后对 token meter 的 surface 节点取快照，并在异步摘要后再次比较；任何 surface 变更都会使替换前的检查失败，而标题或其他仅日志追加不会使已选范围失效。 +该锁只排除另一项压缩，不排除无关事实。其标记是时间点，而不是排他的容器，因此空闲注入的上下文可以出现在独立手动 start 与 end 之间。自动工作要求其轮次内的整个 surface 保持稳定。手动工作只重新验证所选位置 span，使其外部的仅追加上下文在替换后保持可见。 -两种失败路径，均有文档记录： +生命周期边界使崩溃状态含义明确： -- **崩溃**（循环在摘要生成中途死亡）：悬空的 `compact/start`，无关闭事件。由于 `compact/*` 是**仅日志**事件，孤儿是**惰性的**，不会落地摘要替换。派生 surface 保持为 `compact/start` 时已经持久化的 surface：如果修剪未产生替换，就是完整历史；如果已经修剪，就是已修剪历史。通用轮次修复（`interruptedTurnClosers`）用合成的 `turn/end` 关闭轮次；孤儿位于该 `turn/end` *之前*，因此轮次范围内的进行中检查永远看不到它，崩溃不会卡住未来的压缩。 -- **可恢复**（摘要生成抛出异常但循环存活）：后端追加设置了 **`error`** 字段的 `compact/end`，但不落地摘要替换。步骤后压力处理发出警告，并从最新的持久 surface 继续：如果尝试前没有替换，就是完整历史；如果修剪已经落地，就是已修剪 surface。溢出恢复只会在没有任何替换前委托；先前修剪带来的 generation 进展允许从该持久 surface 重试，除非取消或资源释放胜出。 +- **当前生命周期：** 最新 `session/end-seed` 之后悬空的 `compact/start` 是活动的持久锁，并报告 busy。 +- **后续生命周期：** 构造函数写入的较新 `session/end-seed` 证明更早的未匹配 start 已陈旧，因此恢复、fork 和接手不会被已死的写入方持续卡住。 +- **可恢复失败：** start 落地后，后端会恰好尝试一次 `compact/end { error }`。摘要或稳定性失败会保持会话 surface 不变，同时在日志中保留失败尝试。如果追加闭合事件失败，未匹配 start 会继续有意阻塞。 `compact/end` 保留其 `error?` 字段（与 `tool/result` 的自包含错误一致——一个事件即可区分成功与失败，无需关联兄弟事件）。没有单独的 `compact/error` 事件。 -**核心会话修复保持对压缩无感知——这是有意为之。** `interruptedTurnClosers` 从不被教导 `compact/*`。如果教导它，每个未来的 `xxx/start … xxx/end` 插件对都必须修补核心模块——这恰好是能力 seam 架构存在的意义所要避免的耦合。由于仅日志的孤儿是惰性的，不需要特殊修复：通用轮次修复加上未落地 surface 变更的惰性就足够了。 +**核心会话修复保持对压缩无感知——这是有意为之。** `interruptedTurnClosers` 从不被教导 `compact/*`。通用 `session/end-seed` 生命周期边界提供压缩所有方所需的证据；压缩不变量与后端负责解释它，无需向核心添加插件专属修复。 ## 曾考虑的替代方案 -- **完整算法作为接口的具体方法**——否决，因为它将契约重新耦合到一种保留策略。两个核心方法都是抽象的；可复用测量属于单独的 LLM 系列服务，`summarize()` 是 basic 唯一的钩子。 +- **完整算法作为接口的具体方法**——否决，因为它将契约重新耦合到一种保留策略。三个操作都是抽象的；可复用测量属于单独的 LLM 系列服务，`summarize()` 是 basic 唯一的钩子。 - **在 `agent/request` 或临时 `agent/pre-step` 输入上执行压缩**——否决，因为两者都无法证明最终的持久请求，而且都会将通用生命周期耦合到压缩专属的信封数据。步骤后回放与规范溢出恢复同时覆盖成功和被拒绝的调用。 - **`compact` 布尔值或无类型的请求元数据 map**——否决，因为多个辅助调用种类会变成互斥标志，而开放 map 会丢弃由编译器检查的词汇。一个类型化的 `purpose` 判别字段可以扩展其他调用种类，而无需再为 `GenerateOptions` 添加字段。 - **单独的 `compact/error` 事件**——否决：`compact/end` 保留 `error?` 字段，与 `tool/result` 的自包含错误一致——一个事件即可区分成功与失败，无需关联兄弟事件。 -- **教导核心轮次修复识别 `compact/*`**——否决：仅日志的孤儿是惰性的，为每个未来的 `xxx/start … xxx/end` 插件对修补核心模块恰好是能力 seam 架构存在的意义所要避免的耦合。 +- **教导核心轮次修复识别 `compact/*`**——否决：通用 end-seed 边界已经能够区分先前生命周期的历史；为每个未来的 `xxx/start … xxx/end` 插件对修补核心模块，恰好是能力 seam 架构存在的意义所要避免的耦合。 ## 后果 -- **包**：`packages/compact/compact` 提供接口，`compact-basic` 提供后端，`compact-tool-result-prune` 提供可选的确定性重写。`packages/llm/token-meter` 独立拥有回放感知的测量。消费方层推迟。 +- **包**：`packages/compact/compact` 提供接口，`compact-basic` 提供后端，`compact-tool-result-prune` 提供可选的确定性重写，`command-compact` 提供面向用户的 `/compact`。`packages/llm/token-meter` 独立拥有回放感知的测量。 - **自动 seam**：`agent/post-step`（`@mode serial`）处理成功调用的压力，`agent/request-error`（`@mode waterfall`）处理失败步骤关闭后的最终请求失败。通用 `agent/pre-step` 保持为四参数检查点，不携带压缩专属的提示词/前缀 payload。 - **`SessionEventMap`** 通过可合并扩展的声明合并获得 `compact/start` / `compact/summary` / `compact/end`；`SurfaceEventType` **未被**触及。这些是会话事件，不是 cordis `Events`，因此事件分类门禁无需新增条目。 - **`dsh-compact`** 拥有 `COMPACT_CHECKPOINT_SOURCE`、`isCompactCheckpointSource(source)`、`toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`。该标记用于跨后端实现识别替换摘要。带缓存的 surface 边缘检查会防止 `compactRegion` 和 `compactIfNeeded` 拆分工具调用/结果对，按 seq 校验当前成员关系，从每个切割点的一条平衡序列回答两侧边缘，并拒绝陈旧或缺失的 seq 与孤立结果。 -- **`dsh-session`** 通过唯一的 surface 管理器校验位置替换、完整溯源信息和仅内容的单节点 `tool/result` 重写。其不变式配套插件将新追加的工具结果视为执行，要求存在已打开的步骤与待处理调用；已校验的替换仍是位于轮次内的重写。 -- **接线**：`examples/tui-agent/cordis.yml` 依次加载零配置的 `dsh-token-meter`、`dsh-compact-tool-result-prune` 和 `dsh-compact-basic`；服务级默认值使组合无需重复数值策略即可使用。 +- **`dsh-session`** 通过唯一的 surface 管理器校验位置替换、完整溯源信息和仅内容的单节点 `tool/result` 重写。其不变式配套插件将新追加的工具结果视为执行，要求存在已打开的步骤与待处理调用，而压缩配套组件拥有数字轮次归属与独立 `null` 归属标记对之间的关系。 +- **接线**：`examples/tui-agent/cordis.yml` 依次加载零配置的 `dsh-token-meter`、`dsh-compact-tool-result-prune`、`dsh-compact-basic`，然后加载 `dsh-command-compact`；服务级默认值使组合无需重复数值策略即可使用。 ## 测试 - **单元测试：** 使用真实 Loader 和 invariant 插件覆盖完整单元保留、修剪配置与回放、富块顺序、元数据保留、收敛、`compact/end` 的两种结果、开放尾部拒绝、仅修剪与带摘要的溢出恢复、generation 证明、上限和原始错误保留。 - **循环测试：** 测试固定步骤后处理发生在持久工具结果之后、`step/end` 之前，使用实际 `agent/request` 路由，关闭失败步骤，分配新的重试编号，并覆盖完整的抛出/带内溢出 → 压缩 → 重建重试组合。 +- **手动测试：** 无需模型密钥即可固定接纳、标记顺序、注入保留、活动／陈旧未匹配标记分类、取消、闭合／flush 失败、命令映射以及排队 TUI 流程。 - **带密钥 e2e：** 真实模型和 bash 会话在降低的限制下触发压缩，记录完整的 `compact/start…end` 对，缩小 surface，并完成任务。 - **快照缺口：** 失控轮次压缩尚无法回放，因为摘要调用未记录 `assistant/chunk` 事件或 `sessionId`；交错摘要调用的回放仍是后续工作。 diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml index 9087db9dd7..ce1ef3af95 100644 --- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml @@ -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 -2026-07-24-model-facing-session-query-tools.md: 2a9a20a8b39dea309e759f4eb6ddcdabe25dd8be -2026-07-24-model-facing-session-query-tools.zh.md: 7fbe746681b329b3e50ae74608a8b2e5167c5ae9 +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md +2026-07-24-model-facing-session-query-tools.md: 82fb70349a94916af2e99b83fcbdac765aae3dd0 +2026-07-24-model-facing-session-query-tools.zh.md: 3ffc142b2a27c612bb8a3238823f536871e5ea17 diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md index 2a9a20a8b3..82fb70349a 100644 --- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md +++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md @@ -36,7 +36,7 @@ Session-level results include the latest folded title when available. Each tool ## Host composition -The consumer is an opt-in plugin. The shipped ACP and TUI apps mount `ctx.sessionQuery` for non-model consumers, while the shared Web/headless composition mounts neither the query service nor the consumer. No shipped composition mounts `@deepseek-ai/dsh-tool-session-query`, so default model requests gain no query prompt or schemas. A composition that opts in also chooses whether to mount the generic timeout and spill policies; the dedicated ACP snapshot fixture mounts both and uses private local spill storage. Generic tool presentation requires no session-query-specific client plugin. +The consumer is an opt-in plugin. The shipped TUI, Web, and headless compositions mount both `ctx.sessionQuery` and `@deepseek-ai/dsh-tool-session-query` through their shared base, so their default model requests include the query prompt and five schemas; the automation-only ACP composition mounts neither. These compositions also supply the generic timeout and spill policies. The dedicated ACP snapshot fixture mounts the consumer and both policies explicitly, with private local spill storage. Generic tool presentation requires no session-query-specific client plugin. ## Alternatives considered @@ -48,7 +48,7 @@ The consumer is an opt-in plugin. The shipped ACP and TUI apps mount `ctx.sessio ## Verification -Package tests pin argument validation, filter translation, timestamp normalization, exact-workspace authorization, parent-filter preauthorization and oracle resistance, changed-observation rejection, service-diagnostic redaction for ordinary and adversarial unknown values, best-effort cyclic-cause logging, logger-failure containment, missing-identity behavior, hidden-boundary pruning, current-step exclusion, internal provider paging, exclusive search and parallel exact-read classification, count caps, exact-signal forwarding, abort-reason preservation, persistence cleanup quiescence, one-scan bounded batch title enrichment, projection-before-dequeue ordering, queued-work suppression, started-worker quiescence, per-header validation, title fallbacks, representative search/trace/read rendering, generic presentation, and disposable registration. Integration coverage uses the real SQLite FTS provider over live and persisted sessions. Shipped configuration, app composition tests, and assembled ACP request-header snapshots prove that the model-facing consumer remains absent while `ctx.sessionQuery` stays available where mounted. A package-owned Loader smoke and dedicated keyless ACP snapshot explicitly mount the consumer with timeout and spill support, pinning its prompt guidance, schemas, and path-independent exact event-read retention behavior. +Package tests pin argument validation, filter translation, timestamp normalization, exact-workspace authorization, parent-filter preauthorization and oracle resistance, changed-observation rejection, service-diagnostic redaction for ordinary and adversarial unknown values, best-effort cyclic-cause logging, logger-failure containment, missing-identity behavior, hidden-boundary pruning, current-step exclusion, internal provider paging, exclusive search and parallel exact-read classification, count caps, exact-signal forwarding, abort-reason preservation, persistence cleanup quiescence, one-scan bounded batch title enrichment, projection-before-dequeue ordering, queued-work suppression, started-worker quiescence, per-header validation, title fallbacks, representative search/trace/read rendering, generic presentation, and disposable registration. Integration coverage uses the real SQLite FTS provider over live and persisted sessions. Shipped configuration and the TUI/Web composition tests prove that the model-facing consumer is present on the TUI, Web, and headless surfaces, while assembled ACP request-header snapshots prove that the automation surface omits it by default. A package-owned Loader smoke and dedicated keyless ACP snapshot explicitly mount the consumer with timeout and spill support, pinning its prompt guidance, schemas, and path-independent exact event-read retention behavior. ## Consequences diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md index 7fbe746681..3ffc142b2a 100644 --- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md +++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md @@ -36,7 +36,7 @@ Status: implemented ## 宿主组合 -该消费方是一个需显式启用的插件。发布的 ACP 与 TUI 应用为非模型消费方挂载 `ctx.sessionQuery`，而 Web/headless 共享组合既不挂载查询服务，也不挂载该消费方。发布的组合均未挂载 `@deepseek-ai/dsh-tool-session-query`，因此默认模型请求中不包含查询提示词或 schema。选择启用该插件的组合还要决定是否挂载通用的超时与 spill 策略；专用的 ACP 快照 fixture（测试前置数据）同时挂载这两项策略，并使用私有的本地 spill 存储。通用工具表现无需会话查询专用客户端插件。 +该消费方是一个需显式启用的插件。已交付的 TUI、Web 与无头组合通过共享 base 同时挂载 `ctx.sessionQuery` 和 `@deepseek-ai/dsh-tool-session-query`，因此其默认模型请求包含查询提示词与五个 schema；仅用于自动化的 ACP 组合两者均不挂载。这些组合还提供通用的超时与 spill 策略。专用的 ACP 快照 fixture（测试前置数据）显式挂载该消费方与这两项策略，并使用私有的本地 spill 存储。通用工具表现无需会话查询专用客户端插件。 ## 考虑过的替代方案 @@ -48,7 +48,7 @@ Status: implemented ## 验证 -包级测试固定参数校验、过滤条件转换、时间戳规范化、精确工作区授权、父级过滤预授权与抵御预言机探测、变更观测拒绝、普通值与对抗性未知值的服务诊断脱敏、尽力记录循环 cause、日志失败隔离、身份缺失行为、隐藏边界裁剪、当前步骤排除、内部提供方翻页、搜索独占与精确读取并行分类、数量上限、精确信号传递、中止原因保留、持久化清理静止、单次扫描且并发有界的批量标题扩充、先投影再取出下一个任务的顺序、抑制排队工作、等待已启动 worker 静止、逐会话头校验、标题回退、代表性搜索／追踪／读取渲染、通用表现与可释放注册。集成覆盖使用真实 SQLite FTS 提供方查询实时与持久化会话。发布配置、应用组合测试与组装后的 ACP 请求头快照证明：面向模型的消费方仍未挂载，而 `ctx.sessionQuery` 在已经挂载该服务的组合中保持可用。包自身的 Loader 冒烟测试与专用无密钥 ACP 快照显式挂载该消费方，并配套启用超时与 spill 支持，固定其提示词指引、schema 以及与路径无关的精确事件读取保留行为。 +包级测试固定参数校验、过滤条件转换、时间戳规范化、精确工作区授权、父级过滤预授权与抵御预言机探测、变更观测拒绝、普通值与对抗性未知值的服务诊断脱敏、尽力记录循环 cause、日志失败隔离、身份缺失行为、隐藏边界裁剪、当前步骤排除、内部提供方翻页、搜索独占与精确读取并行分类、数量上限、精确信号传递、中止原因保留、持久化清理静止、单次扫描且并发有界的批量标题扩充、先投影再取出下一个任务的顺序、抑制排队工作、等待已启动 worker 静止、逐会话头校验、标题回退、代表性搜索／追踪／读取渲染、通用表现与可释放注册。集成覆盖使用真实 SQLite FTS 提供方查询实时与持久化会话。发布配置与 TUI/Web 组合测试证明面向模型的消费方存在于 TUI、Web 与无头界面，而组装后的 ACP 请求头快照证明自动化界面默认不包含它。包自身的 Loader 冒烟测试与专用无密钥 ACP 快照显式挂载该消费方，并配套启用超时与 spill 支持，固定其提示词指引、schema 以及与路径无关的精确事件读取保留行为。 ## 后果 diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml index 9259180188..fe955d125d 100644 --- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml @@ -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-25-session-list-browsing-and-manual-order.md -2026-07-25-session-list-browsing-and-manual-order.md: 5af9cf026c5a0e32837822b3d8cff827c052b07f -2026-07-25-session-list-browsing-and-manual-order.zh.md: 2cfa4efe2f0e53b419b264c9af0aff878d321cac +2026-07-25-session-list-browsing-and-manual-order.md: bd04e7f74c8a4540d68e60ad68965e05de76bce9 +2026-07-25-session-list-browsing-and-manual-order.zh.md: 8ec5f71943a68a70f46fbd4c7702e4556b1892ec diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md index 5af9cf026c..bd04e7f74c 100644 --- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md +++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md @@ -24,7 +24,7 @@ The group-by menu offers two modes, WorkSpace / In one list. WorkSpace mode rend ### workspace.rename -`workspace.rename({ workspaceId, title })`: the title is trimmed and must be non-blank; both the same-title no-op and the duplicate check evaluate inside the host's serialized workspace-creation chain (shared with create, so concurrent create/rename cannot interleave a duplicate or an out-of-order fake success), and a conflict returns `workspace-name-conflict`. Durability goes through `setTitle`'s mutate path, and the `domain/changed` listener broadcasts the `host/workspace-changed` frame automatically. The UI is a standard modal with a client-side duplicate pre-check. +`workspace.rename({ workspaceId, title })`: the title is trimmed and must be non-blank; both the same-title no-op and the duplicate check evaluate inside the Host's serialized workspace-operation chain (shared with create-by-name, so concurrent explicit naming operations cannot interleave a duplicate or an out-of-order fake success), and a conflict returns `workspace-name-conflict`. Path adoption may derive a title already present because canonical path, not title, owns identity ([decision](../bug-fix/2026-07-31-same-basename-workspace-adoption.md)). Durability goes through `setTitle`'s mutate path, and the `domain/changed` listener broadcasts the `host/workspace-changed` frame automatically. The UI is a standard modal with a client-side duplicate pre-check. ### Manual order: insertSessionBefore replaces activity pinning diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md index 2cfa4efe2f..8ec5f71943 100644 --- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md +++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md @@ -24,7 +24,7 @@ group-by 菜单提供 WorkSpace / In one list 两种模式。WorkSpace 模式按 ### workspace.rename -`workspace.rename({ workspaceId, title })`:title trim 后非空;同名 no-op 与重名查重都在 host 的 workspace 创建串行链内求值(与 create 共链,并发 create/rename 不能穿插出重名或乱序假成功),冲突回 `workspace-name-conflict`。落盘经 `setTitle` 的 mutate 通道,`domain/changed` 监听自动广播 `host/workspace-changed` 帧。UI 为标准 Modal,client 侧另做重名预检。 +`workspace.rename({ workspaceId, title })`：title trim 后非空；同名 no-op 与重名查重都在 Host 的 Workspace 操作串行链内求值（与按名称创建共链，并发的显式命名操作不能穿插出重名或乱序假成功），冲突返回 `workspace-name-conflict`。按路径收编可以派生出已有 title，因为拥有身份的是 canonical path，而不是 title（见[身份决策](../bug-fix/2026-07-31-same-basename-workspace-adoption.md)）。落盘经 `setTitle` 的 mutate 通道，`domain/changed` 监听自动广播 `host/workspace-changed` 帧。UI 为标准 Modal，client 侧另做重名预检。 ### 手动排序:insertSessionBefore 取代活动置顶 diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml index b876fa890c..d8232afa44 100644 --- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml @@ -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-25-workspace-ui-product-flow.md -2026-07-25-workspace-ui-product-flow.md: 7e3338cfcb04c1588bbc97f6e8aa1cd2dac59141 -2026-07-25-workspace-ui-product-flow.zh.md: 8c092151f737b6bc10aa8424281eeda359f07c1d +2026-07-25-workspace-ui-product-flow.md: 7a6a41e19d2930fbcbf7ba5fc9e6809d96e23166 +2026-07-25-workspace-ui-product-flow.zh.md: a40f374fd794b11bff0de72cbc822fd638cd267c diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md index 7e3338cfcb..7a6a41e19d 100644 --- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md +++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md @@ -20,7 +20,7 @@ The Host provides the following GUI wiring on the Workspace entity: | --- | --- | | `workspace.list` | Returns persistent Workspaces in order and filters out Session ids that fail header validation | | `workspace.create({ name })` | Creates a directory and Workspace at `workspaceRoot/name`; fails on a display-name conflict | -| `workspace.create({ path })` | Adopts an existing directory and does not create an arbitrary path | +| `workspace.create({ path })` | Adopts an existing directory by canonical path; basename-derived display titles may repeat | | `workspace.delete({ workspaceId })` | Removes the Workspace registration while retaining its directory and session logs; its Sessions become Ungrouped | | `session.create({ workspaceId, sessionId? })` | Resolves cwd from the Workspace, idempotently creates a Session with an optional preallocated id, and attaches it | | `session.create({ cwd })` | Remains available to non-Workspace callers and creates an Ungrouped Session | @@ -52,7 +52,7 @@ When no Workspace exists, the page creates a frontend Workspace object named `wo Top-level New Session, the plus button on a Workspace row, and the Workspace picker all invoke the same New Session action. An explicit Workspace id becomes the target directly; when none is specified, the action uses the most recent Workspace, or the Workspace Intent if no real Workspace exists. The Workspace picker's one Add workspace action ([one-route Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md); it was a pair of Use-an-existing-folder and create-by-name actions when this was decided) immediately creates a real Workspace when the user confirms a directory, then retargets the frontend Session to it; an explicitly created empty Workspace remains even if the user sends no message. -A new Workspace takes its display name from the directory it was created in, and the Host rejects a title already registered (the UI's own duplicate-name pre-check went with the create-by-name dialog). Moving Sessions across Workspaces, manual adoption from Ungrouped, and separate display-name and directory-name inputs remain outside this flow. +A new Workspace takes its display name from the directory it was created in. Distinct canonical paths may share the same basename-derived title ([identity decision](../bug-fix/2026-07-31-same-basename-workspace-adoption.md)); explicit create-by-name and rename operations retain their duplicate-title checks. Moving Sessions across Workspaces, manual adoption from Ungrouped, and separate display-name and directory-name inputs remain outside this flow. ### First send and recovery @@ -108,7 +108,7 @@ The Sidebar and conversation empty hero receive standardized actions through slo - Workspace list performs one reentrant bootstrap using only headers; an initialized empty registry does not initialize again after restart, and membership reads validate both the index and canonical cwd. - The initial default target is determined exactly once after both baselines are ready; Workspace groups are not reordered as a whole by hydration or Session activity, and an active Session moves only itself to the front. - A frontend Session under a real Workspace temporarily counts toward the sidebar total, while a Workspace Intent remains hidden; neither publication nor refresh leaves duplicate rows or counts. -- Both the UI and Host reject duplicate Workspace names; cwd-only Sessions, Sessions with invalid historical cwd values, and unattached Sessions remain Ungrouped. +- The UI and Host admit distinct same-basename directories as separate Workspaces, while explicit create-by-name and rename operations reject duplicate titles; cwd-only Sessions, Sessions with invalid historical cwd values, and unattached Sessions remain Ungrouped. - Confirmed Workspace deletion removes only the registration, retains the current Session, directory, files, and session log, and survives reload; package tests pin unary/frame/baseline races and failure rollback. - Keyless runnable snapshots cover the zero state, explicit creation, and the first send; package-level tests cover bootstrap, membership validation, ordering, idempotency, failure recovery, and arbitrary frame order. diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md index 8c092151f7..a40f374fd7 100644 --- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md +++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md @@ -20,7 +20,7 @@ Host 在 Workspace entity 上提供以下 GUI 接线： | --- | --- | | `workspace.list` | 返回持久有序的 Workspace，并过滤未通过 header 校验的 Session id | | `workspace.create({ name })` | 在 `workspaceRoot/name` 创建目录和 Workspace；显示名冲突时失败 | -| `workspace.create({ path })` | 收编已经存在的目录，不为任意路径创建目录 | +| `workspace.create({ path })` | 按 canonical path 收编已有目录；由 basename 派生的显示名可以重复 | | `workspace.delete({ workspaceId })` | 移除 Workspace 注册记录，同时保留目录和会话日志；相关 Session 进入 Ungrouped | | `session.create({ workspaceId, sessionId? })` | 从 Workspace 解析 cwd，以可选预分配 id 幂等创建 Session 并 attach | | `session.create({ cwd })` | 保留给非 Workspace 调用方，创建 Ungrouped Session | @@ -52,7 +52,7 @@ Session 自己持有首条输入并驱动一条内部流水线：必要时以预 顶部 New Session、Workspace 行内加号和 Workspace picker 最终都调用同一 New Session 动作：显式 Workspace id 直接成为目标，未指定时使用最近 Workspace，没有真实 Workspace 时使用 Workspace Intent。Workspace picker 的单一 Add workspace 动作（见[单一路径 Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)；本决策做出时是 Use an existing folder 与按名称创建两个动作）会在用户确认目录时立即创建真实 Workspace，再把前端 Session 定位到该 Workspace；即使用户不发送消息，显式创建的空 Workspace 也保留。 -新建 Workspace 的显示名取自其所在目录，Host 拒绝已注册的同名 title（UI 侧的重名预检随按名称创建的对话框一并删除）。跨 Workspace 移动 Session、从 Ungrouped 手动收编以及分别输入显示名和目录名仍不在此动线范围内。 +新建 Workspace 的显示名取自其所在目录。不同 canonical path 可以拥有相同的 basename 派生显示名（见[身份决策](../bug-fix/2026-07-31-same-basename-workspace-adoption.md)）；显式的按名称创建和重命名操作仍保留显示名重名检查。跨 Workspace 移动 Session、从 Ungrouped 手动收编以及分别输入显示名和目录名仍不在此动线范围内。 ### 首次发送与恢复 @@ -108,7 +108,7 @@ Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSe - Workspace list 只读取 header 完成一次可重入 bootstrap；initialized 的空 registry 重启不重复初始化，成员读取同时校验索引与 canonical cwd。 - 初始默认目标只在两份基线 ready 后确定一次；Workspace 组不因 hydration 或 Session 活跃整体重排，单个活跃 Session 只前移自身。 - 真实 Workspace 下的前端 Session 临时计入 sidebar 数量，Workspace Intent 保持隐藏，发布与刷新都不会留下重复行或重复计数。 -- UI 与 Host 两层拒绝同名 Workspace；cwd-only Session、无效历史 cwd 和未 attach Session 保持 Ungrouped。 +- UI 与 Host 会将 canonical path 不同但 basename 相同的目录接纳为独立 Workspace，而显式的按名称创建和重命名操作会拒绝重复显示名；cwd-only Session、无效历史 cwd 和未 attach Session 保持 Ungrouped。 - 经确认的 Workspace 删除只移除注册记录，保留当前 Session、目录、文件和会话日志，并在刷新后保持该状态；包级测试固定一元响应／帧／基线竞态和失败回滚行为。 - keyless runnable snapshot 覆盖零态、显式创建和首次发送；包级测试覆盖 bootstrap、成员校验、排序、幂等、失败恢复及任意 frame 顺序。 diff --git a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml index a2b2e940fd..1faf10a4c8 100644 --- a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml @@ -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-27-native-workspace-directory-picker.md -2026-07-27-native-workspace-directory-picker.md: 8dd7084eb8ffa417d9366cbc54bcbc59170c64fe -2026-07-27-native-workspace-directory-picker.zh.md: 9efc6571207b1f6a6996b9990c2a55afb70872bd +2026-07-27-native-workspace-directory-picker.md: 98f9dc9bed5358e816d4324462d5ea7657f9007f +2026-07-27-native-workspace-directory-picker.zh.md: ca765778fae734fd47a05652aea7021328ed4ab6 diff --git a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.md b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.md index 8dd7084eb8..98f9dc9bed 100644 --- a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.md +++ b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.md @@ -19,7 +19,7 @@ The workspace manager must upsert the returned workspace before the selection ca - The picker accepts one directory on macOS, Windows, and Linux. - Cancelling the system dialog is silent and returns `null`. - A duplicate path selects the existing workspace. -- A different path whose derived title conflicts with another workspace shows a focused error with **Choose again** and **Cancel** actions. +- A different canonical path adopts a separate Workspace even when its derived title matches another Workspace ([identity decision](../bug-fix/2026-07-31-same-basename-workspace-adoption.md)). - Other picker failures show a compact retryable error. - The create-by-name flow this decision left untouched is gone; picking a directory is now the whole of adding a workspace ([one-route Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)). @@ -41,9 +41,9 @@ Platform adapters invoke native tools without a shell: ## Consequences -The current GUI opens one local folder through a native picker on macOS, Windows, and Linux. Cancelling changes no state, failures remain retryable, and duplicate paths are idempotent while title conflicts require an explicit new choice. The selected workspace and its displayed name refresh before a new blank session starts. This picker is now the only route to a workspace ([one-route Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)): the operator picks an existing directory, or creates one inside the chooser. +The current GUI opens one local folder through a native picker on macOS, Windows, and Linux. Cancelling changes no state, failures remain retryable, duplicate paths are idempotent, and distinct same-basename paths coexist as separate Workspaces. The selected workspace and its displayed name refresh before a new blank session starts. This picker is now the only route to a workspace ([one-route Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)): the operator picks an existing directory, or creates one inside the chooser. -The added host, runtime, component, and GUI tests cover the native boundary, request trust checks, cancellation and failure handling, existing-path reuse, title conflicts, and the immediate visible-name update. The privileged RPC remains specific to the local desktop carrier; a remote Web directory browser is outside this decision. +The added host, runtime, component, and GUI tests cover the native boundary, request trust checks, cancellation and failure handling, existing-path reuse, same-basename adoption, and the immediate visible-name update. The privileged RPC remains specific to the local desktop carrier; a remote Web directory browser is outside this decision. ## Risks diff --git a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md index 9efc657120..ca765778fa 100644 --- a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md +++ b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md @@ -19,7 +19,7 @@ Status: implemented - 在 macOS、Windows 和 Linux 上，选择器一次只允许选择一个目录。 - 取消系统对话框不会显示提示，并返回 `null`。 - 路径重复时，选中现有工作区。 -- 如果路径不同，但其派生标题与另一个工作区冲突，则显示明确指出该冲突的错误提示，其中包含 **重新选择** 和 **取消** 操作。 +- 即使派生显示名与另一个 Workspace 相同，不同 canonical path 也会被收编为独立 Workspace（见[身份决策](../bug-fix/2026-07-31-same-basename-workspace-adoption.md)）。 - 选择器的其他故障会显示简洁且可重试的错误提示。 - 本决策当时未触碰的按名称创建流程现已删除；选择目录就是添加工作区的全部（见[单一路径 Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)）。 @@ -41,9 +41,9 @@ Status: implemented ## 后果 -当前 GUI 可以在 macOS、Windows 和 Linux 上通过原生选择器打开一个本地文件夹。取消操作不会改变任何状态，故障仍可重试；重复路径的处理具有幂等性，标题冲突则要求用户明确重新选择。选中的工作区及其显示名称会在启动新的空白会话前完成刷新。该选择器现已是获得工作区的唯一路径（见[单一路径 Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)）：操作者要么选一个已有目录，要么在选择器内新建一个。 +当前 GUI 可以在 macOS、Windows 和 Linux 上通过原生选择器打开一个本地文件夹。取消操作不会改变任何状态，故障仍可重试；重复路径的处理具有幂等性，basename 相同的不同路径则可作为独立 Workspace 共存。选中的工作区及其显示名称会在启动新的空白会话前完成刷新。该选择器现已是获得工作区的唯一路径（见[单一路径 Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)）：操作者要么选一个已有目录，要么在选择器内新建一个。 -新增的宿主、运行时、组件和 GUI 测试覆盖原生边界、请求信任校验、取消与故障处理、已有路径复用、标题冲突和可见名称即时更新。该特权 RPC 仍仅面向本地桌面载体；远程 Web 目录浏览器不属于本次决策范围。 +新增的宿主、运行时、组件和 GUI 测试覆盖原生边界、请求信任校验、取消与故障处理、已有路径复用、同 basename 路径收编和可见名称即时更新。该特权 RPC 仍仅面向本地桌面载体；远程 Web 目录浏览器不属于本次决策范围。 ## 风险 diff --git a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.i18n.yaml index b5fa2609a4..e670431c9c 100644 --- a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.i18n.yaml @@ -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-27-tmux-location-context.md -2026-07-27-tmux-location-context.md: bac5861f7f55c259de04d153115f164d90c415ad -2026-07-27-tmux-location-context.zh.md: 03cd722381c45604f7aae8f3d0a9f9fbb8b12bb5 +2026-07-27-tmux-location-context.md: 9f5e931e56565b0bf3ee219567c6913c40ef1d97 +2026-07-27-tmux-location-context.zh.md: e47eb43c5a9c64bab4518d118cb4dfd580de64e9 diff --git a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md index bac5861f7f..9f5e931e56 100644 --- a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md +++ b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md @@ -12,7 +12,7 @@ tmux exposes this without a daemon: `$TMUX_PANE` names the process's pane, and ` ## Decision -`@deepseek-ai/dsh-tmux-context` is an opt-in function plugin in `packages/context/tmux-context/`, alongside the other bounded request-context enrichments that define neither a tool nor a service. Shipped examples do not mount it because tmux-location disclosure and its token cost are deployment policy. +`@deepseek-ai/dsh-tmux-context` is an opt-in function plugin in `packages/context/tmux-context/`, alongside the other bounded request-context enrichments that define neither a tool nor a service. The shipped TUI mounts it because terminal-multiplexer context is specific to that surface; `dsh-agent-spine-demo` and the Web/headless surfaces stay silent. **Pull on the first step of each turn, not a tmux push.** The plugin prepends an `agent/step` listener and acts only when `step === 1`. A pull model needs no background process, no hook installation in the user's tmux, and no teardown; it re-reads current state each turn so a moved, renamed, or re-laid-out pane is picked up naturally. Gating on the first step makes the reading per-turn: a location is stable within a turn, and re-querying every step would add cost without new information. A pane moved mid-turn is reflected on the next turn, which is the accepted tradeoff for the simpler design. @@ -42,7 +42,7 @@ The published `./invariant` companion registers no runtime check: a reading is a ## Consequences -An agent booted inside tmux now receives its own session/window/pane location and window layout as durable, source-attributed context, updated per turn when the location changes. Deployments opt in through cordis.yml; the default spine and shipped examples stay silent. Outside a real tmux pane — including a terminal that merely inherited `$TMUX`/`$TMUX_PANE` — or without a `ctx.bash` executor, the plugin is inert with no error, so composing it is safe everywhere. Because the reading is one durable `user/message`, it survives compaction as ordinary history, contributes nothing to system-prompt assembly or request headers, and costs at most one two-line message per changed turn. The pull model adds one `tmux display-message` subprocess (through the sandboxed bash seam) on the first step of each turn that is due. The optional interval floor is checked before the query and so suppresses both; an unchanged location is detected only by comparing the returned state, so it suppresses the injection while still paying for the query. +An agent booted inside tmux now receives its own session/window/pane location and window layout as durable, source-attributed context, updated per turn when the location changes. The shipped TUI opts in; custom deployments may compose the plugin directly. Outside a real tmux pane — including a terminal that merely inherited `$TMUX`/`$TMUX_PANE` — or without a `ctx.bash` executor, the plugin is inert with no error, so composing it is safe everywhere. Because the reading is one durable `user/message`, it survives compaction as ordinary history, contributes nothing to system-prompt assembly or request headers, and costs at most one two-line message per changed turn. The pull model adds one `tmux display-message` subprocess (through the sandboxed bash seam) on the first step of each turn that is due. The optional interval floor is checked before the query and so suppresses both; an unchanged location is detected only by comparing the returned state, so it suppresses the injection while still paying for the query. ## Testing diff --git a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md index 03cd722381..e47eb43c5a 100644 --- a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md +++ b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md @@ -12,7 +12,7 @@ tmux 无需守护进程即可暴露这些信息：`$TMUX_PANE` 标识进程所 ## 决策 -`@deepseek-ai/dsh-tmux-context` 是位于 `packages/context/tmux-context/` 的可选启用型函数插件，与其他既不定义工具也不定义服务的有界请求上下文增强并列。随附示例不挂载它，因为 tmux 位置披露及其 token 成本属于部署策略。 +`@deepseek-ai/dsh-tmux-context` 是位于 `packages/context/tmux-context/` 的可选启用型函数插件，与其他既不定义工具也不定义服务的有界请求上下文增强并列。已交付的 TUI 会挂载它，因为终端复用器上下文是该界面特有的；`dsh-agent-spine-demo` 与 Web／无头界面保持沉默。 **在每轮的第一个 step 拉取，而非 tmux 推送。** 插件前置注册一个 `agent/step` 监听器，仅在 `step === 1` 时动作。拉取模型无需后台进程、无需在用户的 tmux 中安装 hook、也无需清理；它每轮重新读取当前状态，因此被移动、改名或重新布局的 pane 都会被自然感知。以第一个 step 为门槛使读数按轮次生成：位置在一轮内是稳定的，逐步骤重复查询只会增加成本而不带来新信息。轮次中途移动的 pane 会在下一轮反映，这是换取更简单设计所接受的取舍。 @@ -42,7 +42,7 @@ window active=<0|1>, pane active=<0|1>, layout ## 后果 -启动于 tmux 内的 agent 现在会以持久、带来源标记的上下文收到自身的 session/window/pane 位置及 window 布局，并在位置变化时按轮次更新。部署方通过 cordis.yml 选择启用；默认 spine 与随附示例保持沉默。在真实 tmux pane 之外——包括仅继承了 `$TMUX`／`$TMUX_PANE` 的终端——或没有 `ctx.bash` 执行器时，插件保持惰性且不报错，因此在任何地方组合它都安全。由于读数是一条持久的 `user/message`，它作为普通历史经受压缩，对系统提示装配与请求头毫无贡献，且每个发生变化的轮次至多花费一条两行消息。拉取模型在每个到期轮次的第一个 step 增加一次 `tmux display-message` 子进程（经沙箱化的 bash seam）。可选的间隔下限在查询之前检查，因此同时抑制查询与注入；而位置未变化只能通过比较查询返回的状态得知，因此它只抑制注入，查询开销仍会付出。 +启动于 tmux 内的 agent 现在会以持久、带来源标记的上下文收到自身的 session/window/pane 位置及 window 布局，并在位置变化时按轮次更新。已交付的 TUI 选择启用；自定义部署可直接组合该插件。在真实 tmux pane 之外——包括仅继承了 `$TMUX`／`$TMUX_PANE` 的终端——或没有 `ctx.bash` 执行器时，插件保持惰性且不报错，因此在任何地方组合它都安全。由于读数是一条持久的 `user/message`，它作为普通历史经受压缩，对系统提示装配与请求头毫无贡献，且每个发生变化的轮次至多花费一条两行消息。拉取模型在每个到期轮次的第一个 step 增加一次 `tmux display-message` 子进程（经沙箱化的 bash seam）。可选的间隔下限在查询之前检查，因此同时抑制查询与注入；而位置未变化只能通过比较查询返回的状态得知，因此它只抑制注入，查询开销仍会付出。 ## 测试 diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml index d576fb10e5..5b8cb4481f 100644 --- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml @@ -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-27-workspace-registration-deletion.md -2026-07-27-workspace-registration-deletion.md: 8168b0832ca39e6023f6981815ffe758b5695361 -2026-07-27-workspace-registration-deletion.zh.md: b0df6982ac81426a5b0ce2f0e2b0e744212e3f5b +2026-07-27-workspace-registration-deletion.md: ae12b09979f20385336eef8d805173dd9c08d887 +2026-07-27-workspace-registration-deletion.zh.md: 2e43b25ec0b68703d68f6346796482d1c5ed3e8a diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md index 8168b0832c..ae12b09979 100644 --- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md +++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md @@ -28,7 +28,7 @@ Create and delete write a durable `pendingMutation` before their record/order pa `WorkspaceManager` treats both `host/workspace-changed` and `host/workspace-removed` as ordered deltas replayed over an in-flight `workspace.list` response. A successful unary delete removes the row immediately instead of waiting for its own stream echo. Removal is idempotent, and a process-local tombstone rejects late changed frames or stale baseline rows for the never-reused Workspace id. A reconnect still refreshes from `workspace.list`; Session state is never pruned by a Workspace delta. -The delete confirmation remains pending until the React Workspace projection has committed the removed id, so the next create gesture cannot observe one stale list frame. During create, duplicate-name validation is suppressed while the request is pending because the committed `host/workspace-changed` frame may publish the newly created Workspace before its unary response; after failure returns the form to editing, validation uses the latest list again. +The delete confirmation remains pending until the React Workspace projection has committed the removed id, so the next Workspace gesture cannot observe or target one stale list frame. ## Confirmation interaction @@ -50,7 +50,7 @@ The menu, Modal, and buttons retain their existing structure and design tokens. ## Verification -Workspace package tests pin successful metadata-only deletion, same-path re-registration, unknown-id idempotence, table-failure rollback, explicit-marker restart recovery, unexplained-corruption rejection, and cache/table invariant behavior. Apiproxy and carrier tests pin the schema, handler, `workspace-not-found`, retained Session/folder, fresh-id re-registration, and committed `host/workspace-removed` frame. Client tests pin unary direct echo, duplicate removal, late changed frames, and deletion racing an in-flight baseline. Component tests pin confirmation, projection-settled closing, pending-state duplicate suppression, success-frame-before-unary ordering, failure, Cancel, Escape, and Close. The browser scenario observes every transient alert, slot error, console error, and page error while reusing a deleted title for a different directory. +Workspace package tests pin successful metadata-only deletion, same-path re-registration, unknown-id idempotence, table-failure rollback, explicit-marker restart recovery, unexplained-corruption rejection, and cache/table invariant behavior. Apiproxy and carrier tests pin the schema, handler, `workspace-not-found`, retained Session/folder, fresh-id re-registration, and committed `host/workspace-removed` frame. Client tests pin unary direct echo, duplicate removal, late changed frames, and deletion racing an in-flight baseline. Component tests pin confirmation, projection-settled closing, success-frame-before-unary ordering, failure, Cancel, Escape, and Close. The browser scenario observes every transient alert, slot error, console error, and page error while reusing a deleted title for a different directory. The assembled keyless Web scenario registers an existing temporary project directory, accounts a persisted Session, makes that Session current, confirms deletion in Chromium, and verifies the Workspace group disappears while Ungrouped retains the current Session. It checks the user file and JSONL log before and after deletion and repeats the UI, directory, and log assertions after reload. diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md index b0df6982ac..2e43b25ec0 100644 --- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md +++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md @@ -28,7 +28,7 @@ Create 与 delete 会在记录／顺序对可能分叉之前写入持久 `pendin `WorkspaceManager` 将 `host/workspace-changed` 与 `host/workspace-removed` 都视为有序增量，并在进行中的 `workspace.list` 响应之上回放。成功的一元删除会立即移除行，无需等待本次操作自己的流回显。移除操作具有幂等性；由于 Workspace id 永不复用，进程本地删除标记会拒绝延迟到达的 changed 帧或陈旧基线行。重连仍从 `workspace.list` 刷新；Workspace 增量绝不会剪除会话状态。 -删除确认框会保持待处理，直到 React Workspace 投影已经提交目标 id 的移除，因此下一次创建操作不会读到一帧陈旧列表。创建请求进行中会暂停重复名称校验，因为已提交的 `host/workspace-changed` 帧可能先于一元响应发布刚创建的 Workspace；如果请求失败并让表单回到可编辑状态，系统会重新使用最新列表执行校验。 +删除确认框会保持待处理，直到 React Workspace 投影已经提交目标 id 的移除，因此下一次 Workspace 操作不会观察或定位到陈旧列表帧中的内容。 ## 确认交互 @@ -50,7 +50,7 @@ Create 与 delete 会在记录／顺序对可能分叉之前写入持久 `pendin ## Verification -Workspace 包测试固定了仅删除元数据的成功路径、同路径重新注册、未知 id 的幂等行为、表操作失败回滚、明确标记的重启恢复、来源不明损坏的拒绝，以及缓存／表不变量行为。Apiproxy 与载体测试固定了 schema、处理器、`workspace-not-found`、保留会话／文件夹、使用新 id 重新注册，以及已提交的 `host/workspace-removed` 帧。客户端测试固定了一元直接回显、重复移除、延迟到达的 changed 帧，以及删除与进行中基线并发的行为。组件测试固定了确认交互、投影稳定后关闭、待处理状态下抑制重复提交、成功帧先于一元响应、失败、Cancel、Escape 与 Close。浏览器场景会在为不同目录复用已删除名称时，观测每一次瞬时 alert、slot error、console error 与 page error。 +Workspace 包测试固定了仅删除元数据的成功路径、同路径重新注册、未知 id 的幂等行为、表操作失败回滚、明确标记的重启恢复、来源不明损坏的拒绝，以及缓存／表不变量行为。Apiproxy 与载体测试固定了 schema、处理器、`workspace-not-found`、保留会话／文件夹、使用新 id 重新注册，以及已提交的 `host/workspace-removed` 帧。客户端测试固定了一元直接回显、重复移除、延迟到达的 changed 帧，以及删除与进行中基线并发的行为。组件测试固定了确认交互、投影稳定后关闭、成功帧先于一元响应、失败、Cancel、Escape 与 Close。浏览器场景会在为不同目录复用已删除名称时，观测每一次瞬时 alert、slot error、console error 与 page error。 组装后的无密钥 Web 场景会注册一个已有临时项目目录，将持久化会话计入账本，把该会话设为当前会话，在 Chromium 中确认删除，并验证 Workspace 分组消失，而 Ungrouped 保留当前会话。该场景在删除前后检查用户文件和 JSONL 日志，并在刷新后重复验证 UI、目录与日志。 diff --git a/.agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml index c60a7f0127..f50a69e7a8 100644 --- a/.agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml @@ -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-28-dsh-guided-skill-session-commands.md -2026-07-28-dsh-guided-skill-session-commands.md: a11807dca9ad1640857cd95a8b528df691b8a27e -2026-07-28-dsh-guided-skill-session-commands.zh.md: e48420ed77496d8c336031473364f9008fccced7 +2026-07-28-dsh-guided-skill-session-commands.md: 9d5341880e92d88781278238f21380919c962820 +2026-07-28-dsh-guided-skill-session-commands.zh.md: 90c47d64173161fa4ef1f975de37b9cd42e02c99 diff --git a/.agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.md b/.agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.md index a11807dca9..9d5341880e 100644 --- a/.agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.md +++ b/.agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.md @@ -1,4 +1,4 @@ -# Agent Note: `dsh migrate`/`dsh upgrade` seed the first turn with a skill +# Agent Note: `dsh migrate`/`dsh experimental-upgrade` seed the first turn with a skill Status: implemented @@ -10,7 +10,7 @@ Two recurring flows begin with the user manually invoking one skill and answerin ## Decision -`dsh migrate` and `dsh upgrade` boot the ordinary TUI as a fresh session whose first turn auto-invokes a bundled skill (`dsh-migrate`, `dsh-upgrade`), exactly as if the user typed `/skill:` and pressed Enter. +`dsh migrate` and `dsh experimental-upgrade` boot the ordinary TUI as a fresh session whose first turn auto-invokes a bundled skill (`dsh-migrate`, `dsh-upgrade`), exactly as if the user typed `/skill:` and pressed Enter. The seed reuses the existing TUI skill path, not a new one. `createTuiChat` already has `invokeSkill(name, instructions)` — the code a typed `/skill:` runs, including the "Unknown skill" notice. The launcher passes the skill name to the TUI through a new boot-context slot `INITIAL_SKILL_KEY` (`tuiInitialSkill`), mirroring `CONFIGURED_AGENT_IDENTITIES_KEY`/`TUI_GOODBYE_MESSAGE_KEY`: `ctx.provide` is the only channel from launcher argv into a Loader-mounted plugin. The TUI's `apply()` reads the slot and folds it into `config.initialSkill`; after `ui.start()` succeeds, `createTuiChat` fires `invokeSkill(config.initialSkill, '')` once when set. @@ -26,7 +26,7 @@ The `dsh-migrate` skill is bundled under `skills/` (shipped through `DSH_BUNDLED `packages/ui/tui/tests/tui.spec.ts` gains two fake-terminal cases in the existing skill describe block: `config.initialSkill` set delivers the rendered skill body as the first turn with no user input, and an unknown initial skill reports a notice without sending. `runSkillSession` itself is composition inside the module's `v8 ignore` block, like `runTui`/`runMeta`. -No keyless PTY snapshot: per the maintainer's scope call for this change, unit coverage plus interactive verification suffices, and the seed rides the already-snapshotted `/skill:` render path. Both commands were verified interactively in tmux from a scratch cwd: `dsh migrate` loaded `dsh-migrate` and asked which source agent; `dsh upgrade` loaded `dsh-upgrade`, which pulled in `dsh-customize` and began checkout discovery. +No keyless PTY snapshot: per the maintainer's scope call for this change, unit coverage plus interactive verification suffices, and the seed rides the already-snapshotted `/skill:` render path. Both commands were verified interactively in tmux from a scratch cwd: `dsh migrate` loaded `dsh-migrate` and asked which source agent; `dsh experimental-upgrade` loaded `dsh-upgrade`, which pulled in `dsh-customize` and began checkout discovery. ## Alternatives considered diff --git a/.agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md b/.agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md index e48420ed77..90c47d6417 100644 --- a/.agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md +++ b/.agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md @@ -1,4 +1,4 @@ -# Agent Note：`dsh migrate`/`dsh upgrade` 以 skill 播种首轮 +# Agent Note：`dsh migrate`/`dsh experimental-upgrade` 以 skill 播种首轮 Status: implemented @@ -10,7 +10,7 @@ Status: implemented ## 决策 -`dsh migrate` 与 `dsh upgrade` 以全新会话启动普通 TUI，其首轮自动调用一个内置 skill（`dsh-migrate`、`dsh-upgrade`），效果等同于用户键入 `/skill:` 并回车。 +`dsh migrate` 与 `dsh experimental-upgrade` 以全新会话启动普通 TUI，其首轮自动调用一个内置 skill（`dsh-migrate`、`dsh-upgrade`），效果等同于用户键入 `/skill:` 并回车。 播种复用现有的 TUI skill 路径，而非新增一条。`createTuiChat` 已有 `invokeSkill(name, instructions)`——即键入 `/skill:` 所走的代码，包含“未知 skill”通知。启动器通过一个新的启动上下文槽 `INITIAL_SKILL_KEY`（`tuiInitialSkill`）把 skill 名称传给 TUI，与 `CONFIGURED_AGENT_IDENTITIES_KEY`/`TUI_GOODBYE_MESSAGE_KEY` 一致：`ctx.provide` 是从启动器 argv 进入 Loader 挂载插件的唯一通道。TUI 的 `apply()` 读取该槽并折叠进 `config.initialSkill`；`ui.start()` 成功后，`createTuiChat` 在其被设置时调用一次 `invokeSkill(config.initialSkill, '')`。 @@ -26,7 +26,7 @@ Status: implemented `packages/ui/tui/tests/tui.spec.ts` 在既有 skill describe 块中新增两个伪终端用例：设置 `config.initialSkill` 时无需用户输入即把渲染后的 skill 正文作为首轮投递；未知的初始 skill 以通知形式报告且不发送。`runSkillSession` 本身是模块 `v8 ignore` 块内的组装，与 `runTui`/`runMeta` 相同。 -无 keyless PTY 快照：依据维护者对本次改动的范围裁定，单元覆盖加交互式验证已足够，且播种走的是已有快照的 `/skill:` 渲染路径。两个命令均已在 tmux 中从临时 cwd 交互式验证：`dsh migrate` 加载 `dsh-migrate` 并询问源 agent；`dsh upgrade` 加载 `dsh-upgrade`，后者引入 `dsh-customize` 并开始 checkout 发现。 +无 keyless PTY 快照：依据维护者对本次改动的范围裁定，单元覆盖加交互式验证已足够，且播种走的是已有快照的 `/skill:` 渲染路径。两个命令均已在 tmux 中从临时 cwd 交互式验证：`dsh migrate` 加载 `dsh-migrate` 并询问源 agent；`dsh experimental-upgrade` 加载 `dsh-upgrade`，后者引入 `dsh-customize` 并开始 checkout 发现。 ## 考虑过的替代方案 diff --git a/.agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.i18n.yaml index 1a7c941216..9f62d0d4ea 100644 --- a/.agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.i18n.yaml @@ -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-28-dsh-meta-source-workspace.md -2026-07-28-dsh-meta-source-workspace.md: d65e0e6ff092b63931dd58c52fa76fb76a071dff -2026-07-28-dsh-meta-source-workspace.zh.md: 72a0c65e6eeda7d63dccc2306a3d7625cdb54362 +2026-07-28-dsh-meta-source-workspace.md: be414ddbf63dd95791f9ca956b2f345b1fc8c685 +2026-07-28-dsh-meta-source-workspace.zh.md: 86fc135db290766cb6fc2abefb194120416bfd9d diff --git a/.agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.md b/.agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.md index d65e0e6ff0..be414ddbf6 100644 --- a/.agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.md +++ b/.agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.md @@ -1,4 +1,4 @@ -# Agent Note: `dsh meta` boots the TUI over the harness checkout +# Agent Note: `dsh experimental-meta` boots the TUI over the harness checkout Status: implemented @@ -10,40 +10,32 @@ English | [中文](2026-07-28-dsh-meta-source-workspace.zh.md) ## Decision -`dsh meta` boots the ordinary TUI with the harness checkout as the workspace, from any directory. +`dsh experimental-meta` boots the ordinary TUI with the harness checkout as the workspace, from any directory. The target is `SOURCE_ROOT` in `apps/cli/src/tui.ts` — `fileURLToPath(new URL('../../..', import.meta.url))`, three hops up from `apps/cli/{src,lib}` — the same constant the `harness:source` prompt section already names, so the workspace and the path advertised to the model cannot drift. It follows the launcher's real path, so a PATH symlink through `current` resolves to whichever staging worktree is active. -The mechanism is one `process.chdir(workspace)` inside `runTui`, guarded by a new optional third parameter that only `runMeta` passes. The cwd *is* the workspace seam in the shipped tree: `examples/tui-agent/cordis.yml` derives the session cwd (`!!js process.cwd()`), the `./.sessions` persistence root, and the HMR watch root (`root: ['.']`) from it, so one chdir moves all three together and meta sessions land in the checkout's gitignored `.sessions/`. It runs after both `.env` layers are loaded — the bin's invoking-directory load and the personal one — so the ambient > project > personal precedence is untouched. `DEFAULT_CONFIG` and `SOURCE_ROOT` are absolute and TUI mode passes no snapshot mode, so config resolution is chdir-independent. +The mechanism is one `process.chdir(workspace)` inside `runTui`, guarded by an optional third parameter that only the `experimental-meta` dispatch passes. The cwd *is* the workspace seam in the shipped tree: `examples/tui-agent/cordis.yml` derives the session cwd (`!!js process.cwd()`), the `./.sessions` persistence root, and the HMR watch root (`root: ['.']`) from it, so one chdir moves all three together and meta sessions land in the checkout's gitignored `.sessions/`. It runs after both `.env` layers are loaded — the bin's invoking-directory load and the personal one — so the ambient > project > personal precedence is untouched. `DEFAULT_CONFIG` and `SOURCE_ROOT` are absolute and TUI mode passes no snapshot mode, so config resolution is chdir-independent. -`meta` accepts only `--resume `. `--config` would boot a foreign tree against the harness workspace, which is the `--config` case rather than this one; `-p` is not interactive. Both fail loud, as does an empty `--resume=` — matching the default surface, where a swallowed empty id would silently start a fresh session. - -**`meta` does not redeclare `--resume`.** Commander parses an option a subcommand shares with its parent into `program.opts()` and leaves the subcommand's own options object empty, so redeclaring it silently dropped the id (found by probing the adapter, not by review). The action reads `program.opts()`, which also accepts the flag on either side of the subcommand; `--help` still lists it among the parent's options. +`experimental-meta` always starts a fresh session and accepts no options. `--config` would boot a foreign tree against the harness workspace, which is the default surface's `--config` case rather than this command; `-p` is not interactive, and resume re-enters the persisted session's own workspace through `dsh --resume `. Any leaked default-surface option fails loud. ## Testing -`apps/cli/tests/args.spec.ts` extends its two existing cases rather than adding a file: routing for `meta`, `meta --resume `, and `--resume meta` (pinning the shared-option behavior above), and exit-1 for `meta --resume=`, `meta --config`, and `meta -p`. `runMeta` itself is composition inside the module's existing `v8 ignore` block, like `runTui`. +`apps/cli/tests/args.spec.ts` pins routing for `experimental-meta`, rejection of every leaked default-surface option, and rejection of the former `meta` name. The dispatch itself is composition inside `bin.ts`'s existing `v8 ignore` block. -There is no keyless PTY smoke for this mode. The smoke harness gives each run a temp cwd, but `dsh meta` deliberately chdirs to the real checkout, so a smoke would write `.sessions/` into the live tree mid-test. Covering it properly needs an injectable target directory — a test-only seam this note declines to add for a one-line chdir. +There is no keyless PTY smoke for this mode. The smoke harness gives each run a temp cwd, but `dsh experimental-meta` deliberately chdirs to the real checkout, so a smoke would write `.sessions/` into the live tree mid-test. Covering it properly needs an injectable target directory — a test-only seam this note declines to add for a one-line chdir. The mode was verified interactively instead. Launched from `$HOME`, a `pwd` tool call reports the checkout, git resolves to its branch, the session log lands under the checkout's `.sessions/` (leaving `~/.sessions` untouched and the tree free of unignored residue), and plain `dsh` from another directory still uses the invoking one. -`dsh meta --resume ` once started a *fresh* session instead of resuming — a pre-existing defect on the default surface, not one this mode introduced. [Launcher-owned resume identity](../architecture/2026-07-28-launcher-owned-resume-identity.md) found the cause and fixed it: a personal overlay had replaced the whole `tui-agent` config block, overwriting the shipped `resumeSessionId` intake with a read of an unset environment variable, so a valid id was silently ignored. Session identity is now a launcher-owned context slot that no config key can displace, and `meta` routes through it. - ## Alternatives considered **Thread an explicit workspace through `boot` and the config tree.** Avoids mutating process-wide state, but the shipped config reads the cwd in three places (`!!js process.cwd()`, `persistenceRoot`, HMR `root`), so each would need its own new plumbing and config key to stay consistent. `chdir` before boot expresses "this is the workspace" once, at the seam that already means it. -**A `--meta` flag on the default surface.** Rejected: the default surface is option-only so that subcommands do not collide with a positional, and a flag that silently relocates the workspace reads as a modifier of the current directory rather than a different target. `meta` alongside `web` matches the existing shape. +**An `--experimental-meta` flag on the default surface.** Rejected: the default surface is option-only so that subcommands do not collide with a positional, and a flag that silently relocates the workspace reads as a modifier of the current directory rather than a different target. `experimental-meta` alongside `web` matches the existing shape. **Resolve `~/.dsh/source/current` instead of the launcher's own path.** Rejected: it would diverge from the `harness:source` prompt path whenever a non-installed checkout's `bin/dsh` is invoked directly, telling the model one source root while working in another. -**Make the printed resume hint mode-aware.** Deferred here as a known cost, then delivered by [launcher-owned resume identity](../architecture/2026-07-28-launcher-owned-resume-identity.md): the exit line became a launcher-provided context slot, so meta mode prints `dsh meta --resume ` and a copied hint works from any directory. It previously came from static config as `dsh --resume {session}` and only worked when re-run from the checkout. - ## Consequences -Starting a session on dsh's own source is `dsh meta` from anywhere, and the workspace is guaranteed to be the same checkout the model is told about. Meta sessions are isolated in the checkout's `.sessions/`, so `dsh meta --resume` sees only other meta sessions — intended, since a session's logged cwd belongs to its workspace. - -The resume hint was this mode's original cost and is now resolved. [Launcher-owned resume identity](../architecture/2026-07-28-launcher-owned-resume-identity.md) made both the printed line and the in-place `/resume` handoff reproduce the mode as `dsh meta --resume ` from one shared argv helper, so a copied hint works from any directory and the handoff no longer depends implicitly on `execve` preserving the process cwd. +Starting a session on dsh's own source is `dsh experimental-meta` from anywhere, and the workspace is guaranteed to be the same checkout the model is told about. The command always starts fresh; an ordinary `dsh --resume ` later restores the session and enters its persisted workspace. `runTui` gains an optional third parameter, so the workspace override is visible at the one function that owns TUI composition rather than hidden in a second copy of it. diff --git a/.agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.zh.md b/.agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.zh.md index 72a0c65e6e..86fc135db2 100644 --- a/.agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.zh.md +++ b/.agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.zh.md @@ -1,4 +1,4 @@ -# Agent Note：`dsh meta` 以 harness 检出为 workspace 启动 TUI +# Agent Note：`dsh experimental-meta` 以 harness 检出为 workspace 启动 TUI Status: implemented @@ -10,40 +10,32 @@ Status: implemented ## Decision -`dsh meta` 在任意目录下都以 harness 检出为 workspace 启动普通 TUI。 +`dsh experimental-meta` 在任意目录下都以 harness 检出为 workspace 启动普通 TUI。 目标是 `apps/cli/src/tui.ts` 中的 `SOURCE_ROOT`——`fileURLToPath(new URL('../../..', import.meta.url))`，从 `apps/cli/{src,lib}` 向上三级——与 `harness:source` 提示词段所用的常量完全相同，因此 workspace 与告知模型的路径不可能发生偏离。它跟随启动器的真实路径，所以经由 `current` 的 PATH 符号链接会解析到当前生效的那个 staging 工作树。 -机制是 `runTui` 内的一次 `process.chdir(workspace)`，由一个新的可选第三参数把守，只有 `runMeta` 会传入。在已交付的配置树中，cwd *就是* workspace 的接缝：`examples/tui-agent/cordis.yml` 由它派生出会话 cwd（`!!js process.cwd()`）、`./.sessions` 持久化根目录以及 HMR 监视根目录（`root: ['.']`），因此一次 chdir 会让三者一并移动，meta 会话则落在检出目录中被 gitignore 的 `.sessions/` 内。它在两层 `.env` 都加载之后执行——bin 对调用目录的加载与个人层加载——因此“环境中已有的值 > 项目 > 个人”的优先级不受影响。`DEFAULT_CONFIG` 与 `SOURCE_ROOT` 都是绝对路径，且 TUI 模式不传 snapshot mode，所以配置解析与 chdir 无关。 +机制是 `runTui` 内的一次 `process.chdir(workspace)`，由一个可选第三参数把守，只有 `experimental-meta` 分派会传入。在已交付的配置树中，cwd *就是* workspace 的接缝：`examples/tui-agent/cordis.yml` 由它派生出会话 cwd（`!!js process.cwd()`）、`./.sessions` 持久化根目录以及 HMR 监视根目录（`root: ['.']`），因此一次 chdir 会让三者一并移动，meta 会话则落在检出目录中被 gitignore 的 `.sessions/` 内。它在两层 `.env` 都加载之后执行——bin 对调用目录的加载与个人层加载——因此“环境中已有的值 > 项目 > 个人”的优先级不受影响。`DEFAULT_CONFIG` 与 `SOURCE_ROOT` 都是绝对路径，且 TUI 模式不传 snapshot mode，所以配置解析与 chdir 无关。 -`meta` 只接受 `--resume `。`--config` 会以 harness workspace 启动其他配置树，那属于 `--config` 的场景而非本场景；`-p` 并非交互式。两者都会明确报错，空的 `--resume=` 亦然——与默认界面一致，在那里被吞掉的空 id 会静默开启一个新会话。 - -**`meta` 不重新声明 `--resume`。** 对于子命令与父命令共享的选项，Commander 会将其解析进 `program.opts()`，而把子命令自身的 options 对象留空；因此重新声明会静默丢弃该 id（这是通过实测适配器发现的，而非评审发现）。action 读取 `program.opts()`，这同时也允许该标志出现在子命令的任意一侧；`--help` 仍会在父命令的选项中列出它。 +`experimental-meta` 始终启动新会话，且不接受任何选项。`--config` 会针对 harness workspace 启动其他配置树，那是默认界面的 `--config` 场景，而不是该命令的场景；`-p` 并非交互式，恢复则通过 `dsh --resume ` 重新进入已持久化会话自身的 workspace。任何泄漏的默认界面选项都会明确报错。 ## Testing -`apps/cli/tests/args.spec.ts` 扩展其已有的两个用例而非新增文件：`meta`、`meta --resume ` 与 `--resume meta` 的路由（钉住上述共享选项行为），以及 `meta --resume=`、`meta --config`、`meta -p` 的退出码 1。`runMeta` 自身与 `runTui` 一样，属于该模块既有 `v8 ignore` 块内的组合代码。 +`apps/cli/tests/args.spec.ts` 钉住 `experimental-meta` 的路由、对每个泄漏的默认界面选项的拒绝，以及对旧名称 `meta` 的拒绝。该分派本身是 `bin.ts` 既有 `v8 ignore` 块内的组合代码。 -该 mode 没有 keyless PTY 冒烟测试。冒烟框架会为每次运行提供临时 cwd，但 `dsh meta` 刻意 chdir 到真实检出目录，因此冒烟测试会在测试中途把 `.sessions/` 写入实际工作树。要正确覆盖它需要一个可注入的目标目录——为了一行 chdir 而引入的测试专用 seam，本 note 不予采纳。 +该 mode 没有 keyless PTY 冒烟测试。冒烟框架会为每次运行提供临时 cwd，但 `dsh experimental-meta` 刻意 chdir 到真实检出目录，因此冒烟测试会在测试中途把 `.sessions/` 写入实际工作树。要正确覆盖它需要一个可注入的目标目录——为了一行 chdir 而引入的测试专用 seam，本 note 不予采纳。 取而代之的是交互式验证。从 `$HOME` 启动后，`pwd` 工具调用报告的是该检出目录，git 解析到其分支，会话日志落在该检出的 `.sessions/` 下（`~/.sessions` 未被触及，工作树也没有未被忽略的残留），并且从其他目录运行的普通 `dsh` 仍使用调用目录。 -`dsh meta --resume <有效 id>` 曾经开启一个*新*会话而非恢复——这是默认界面上既已存在的缺陷，并非本 mode 引入。[由启动器持有的会话身份与退出行](../architecture/2026-07-28-launcher-owned-resume-identity.md) 查明了原因并将其修复：一个个人 overlay 替换了整个 `tui-agent` 配置块，用对一个未设置的环境变量的读取覆盖了已交付的 `resumeSessionId` 入口，因此有效的 id 会被静默忽略。会话标识如今是一个启动器拥有的上下文槽位，没有任何配置键能取代它，而 `meta` 经由它进行路由。 - ## Alternatives considered **通过 `boot` 与配置树显式传递 workspace。** 这可避免修改进程级状态，但已交付的配置在三处读取 cwd（`!!js process.cwd()`、`persistenceRoot`、HMR `root`），每一处都需要各自新增管线与配置键才能保持一致。启动前 chdir 只在本就表达该含义的接缝上表达一次“这就是 workspace”。 -**在默认界面上加一个 `--meta` 标志。** 拒绝：默认界面是纯选项形式，以免子命令与位置参数冲突；而一个会静默改变 workspace 的标志读起来像是对当前目录的修饰，而非另一个目标。`meta` 与 `web` 并列符合既有形态。 +**在默认界面上加一个 `--experimental-meta` 标志。** 拒绝：默认界面是纯选项形式，以免子命令与位置参数冲突；而一个会静默改变 workspace 的标志读起来像是对当前目录的修饰，而非另一个目标。`experimental-meta` 与 `web` 并列符合既有形态。 **解析 `~/.dsh/source/current` 而非启动器自身路径。** 拒绝：当直接调用某个非安装检出的 `bin/dsh` 时，它会与 `harness:source` 提示词路径产生偏离——告知模型一个源码根目录，却在另一个目录中工作。 -**让打印的恢复提示随 mode 变化。** 在此作为已知代价推迟，随后由 [由启动器持有的会话身份与退出行](../architecture/2026-07-28-launcher-owned-resume-identity.md) 交付：退出行变成了一个启动器提供的上下文槽位，因此 meta 模式打印 `dsh meta --resume `，被复制的提示在任意目录下都有效。它此前来自静态配置，固定为 `dsh --resume {session}`，且只有在检出目录中重新运行才有效。 - ## Consequences -在 dsh 自身源码上开启会话变成了在任意位置执行 `dsh meta`，且该 workspace 必然就是告知模型的那个检出目录。meta 会话被隔离在检出目录的 `.sessions/` 内，因此 `dsh meta --resume` 只能看到其他 meta 会话——这是预期行为，因为会话记录的 cwd 属于它的 workspace。 - -恢复提示曾是本 mode 的原初代价，如今已解决。[由启动器持有的会话身份与退出行](../architecture/2026-07-28-launcher-owned-resume-identity.md) 让打印的行与原地 `/resume` 移交都从同一个共享的 argv 辅助函数将该 mode 复现为 `dsh meta --resume `，因此被复制的提示在任意目录下都有效，且移交不再隐式依赖于 `execve` 保留进程 cwd。 +在 dsh 自身源码上开启会话变成了在任意位置执行 `dsh experimental-meta`，且该 workspace 必然就是告知模型的那个检出目录。该命令始终启动新会话；之后，普通的 `dsh --resume ` 会恢复该会话并进入其已持久化的 workspace。 `runTui` 新增一个可选第三参数，因此 workspace 覆盖是在拥有 TUI 组合逻辑的那唯一一个函数上可见的，而不是隐藏在它的第二份副本中。 diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml index f2b2b5b22e..c72f343373 100644 --- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml @@ -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-28-skill-invocation-policy.md -2026-07-28-skill-invocation-policy.md: f74b0bcfddb1699c48279b4d8b153cabf764b140 -2026-07-28-skill-invocation-policy.zh.md: 1a7117a382be224c5371964dd4ad3e916d4e0917 +2026-07-28-skill-invocation-policy.md: e639db39c0e971ea6988ef6e9801ab71f8d1337f +2026-07-28-skill-invocation-policy.zh.md: 7e68f2cf28fbaa734dff477441fc8ab73e7367b7 diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md index f74b0bcfdd..e639db39c0 100644 --- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md +++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md @@ -18,7 +18,7 @@ The local parser also exposed an internal camel-case spelling as frontmatter. Su The local provider accepts the exact kebab-case frontmatter keys `disable-model-invocation` and `user-invocable`. It accepts YAML booleans plus case-insensitive `true`/`false`, `yes`/`no`, `on`/`off`, and `1`/`0`, matching the practical boolean forms accepted by Claude skills. It maps `disable-model-invocation` to the inverse positive field and fills both positive fields from their defaults even when neither key is present. A camel-case external spelling or non-boolean invocation value drops the entire skill from discovery with a targeted warning; this pre-release repository does not keep an on-disk compatibility alias. Invocation data fails closed because ignoring it would default to permission and could expose the skill on a disabled surface, while wrong-typed optional `whenToUse` and `metadata` values are omitted because they do not decide invocation. -The model-facing `dsh-tool-skill` catalog and loader enforce `isModelInvocable`. The TUI `/skill:` autocomplete and exact loader enforce the user field locally, so a user-only skill is visible and loadable there even when it is absent from model discovery, without turning the optional skill peer into a runtime import. The launcher-seeded initial skill used by guided `dsh migrate` and `dsh upgrade` sessions follows this same TUI path and must remain user-invocable. The browser `skill.list` RPC serves a user-selected reference that still asks the model to load the skill, so it exposes the intersection of model- and user-invocable skills; no direct browser skill-loading RPC is added. +The model-facing `dsh-tool-skill` catalog and loader enforce `isModelInvocable`. The TUI `/skill:` autocomplete and exact loader enforce the user field locally, so a user-only skill is visible and loadable there even when it is absent from model discovery, without turning the optional skill peer into a runtime import. The launcher-seeded initial skill used by guided `dsh migrate` and `dsh experimental-upgrade` sessions follows this same TUI path and must remain user-invocable. The browser `skill.list` RPC serves a user-selected reference that still asks the model to load the skill, so it exposes the intersection of model- and user-invocable skills; no direct browser skill-loading RPC is added. These rules permit all four combinations: diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md index 1a7117a382..7e68f2cf28 100644 --- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md +++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md @@ -18,7 +18,7 @@ skill 注册表最初将发现操作视为模型目录：`ctx.skills.list()` 会 本地提供方只接受拼写完全一致的 kebab-case frontmatter 键 `disable-model-invocation` 和 `user-invocable`。它接受 YAML 布尔值，以及不区分大小写的 `true`/`false`、`yes`/`no`、`on`/`off` 和 `1`/`0`，与 Claude skills 实际支持的布尔写法一致。它将 `disable-model-invocation` 映射为相反的正向字段，即使两个键都不存在，也会根据默认值填充两个正向字段。若使用外部驼峰式拼写或提供非布尔调用值，发现流程会丢弃整个 skill，并给出有针对性的警告；本仓库尚处于发布前阶段，因此不为磁盘格式保留兼容别名。调用数据校验遵循失败时默认拒绝原则，因为忽略这类数据会默认授予权限，可能使 skill 暴露在已禁用的接口上；与之不同，类型错误的可选 `whenToUse` 和 `metadata` 值会被省略，因为它们不参与调用判定。 -面向模型的 `dsh-tool-skill` 目录和 loader 执行 `isModelInvocable`。TUI 的 `/skill:` 自动补全与精确名称 loader 在本地执行用户字段，因此仅允许用户调用的 skill 即使不出现在模型发现结果中，仍会在此处显示并可加载，同时不会将可选的 skill peer 变成运行时导入。由 launcher 预置、供引导式 `dsh migrate` 和 `dsh upgrade` 会话使用的初始 skill 沿用同一条 TUI 路径，因此必须保持允许用户调用。浏览器的 `skill.list` RPC 提供的是由用户选择、但仍要求模型加载的引用，因此只公开同时允许模型和用户调用的 skill；本次改动不新增让浏览器直接加载 skill 的 RPC。 +面向模型的 `dsh-tool-skill` 目录和 loader 执行 `isModelInvocable`。TUI 的 `/skill:` 自动补全与精确名称 loader 在本地执行用户字段，因此仅允许用户调用的 skill 即使不出现在模型发现结果中，仍会在此处显示并可加载，同时不会将可选的 skill peer 变成运行时导入。由 launcher 预置、供引导式 `dsh migrate` 和 `dsh experimental-upgrade` 会话使用的初始 skill 沿用同一条 TUI 路径，因此必须保持允许用户调用。浏览器的 `skill.list` RPC 提供的是由用户选择、但仍要求模型加载的引用，因此只公开同时允许模型和用户调用的 skill；本次改动不新增让浏览器直接加载 skill 的 RPC。 这些规则允许以下四种组合： diff --git a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.i18n.yaml index d9b4a04671..5fcb6367ea 100644 --- a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.i18n.yaml @@ -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-29-addressable-queue-operations.md -2026-07-29-addressable-queue-operations.md: 7a08b889c958e583dc430d33a1855fe3725f3d48 -2026-07-29-addressable-queue-operations.zh.md: 701b028c7494fd7cb608d05a5d170c9075b155d7 +2026-07-29-addressable-queue-operations.md: 57527730d0f43a3a6c7801806fb9cc136daa5f14 +2026-07-29-addressable-queue-operations.zh.md: 65617e492c16e41d19ba296c7d117f8a2771a67d diff --git a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md index 7a08b889c9..57527730d0 100644 --- a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md +++ b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md @@ -18,7 +18,7 @@ The Web queue rendered pending messages but could not edit or delete one row. `M **Queue addresses require a live Agent.** `session.updateQueue` queries only the mounted Agent registry and never resumes a cold session: an `InboxItemId` is process-local and cannot name work after restart or disposal. A missing Agent and a driver-claimed occurrence both return `queue-item-not-found`. -**Web actions address Queue only.** The Host excludes pending steering from `session/queue`; steering retains its existing durable transcript path after consumption. QueueDock hides while empty, renders one pending occurrence directly, and defaults two or more occurrences to a collapsed `" 条排队消息"` header that expands or collapses the complete list. The header exposes `aria-expanded` and `aria-controls`; the expanded list scrolls within a 180px height bound. An active edit or mutation keeps its rows visible, and emptying the queue restores the collapsed default for the next queue. Visible rows expose edit and delete, but no send-now control. The UI derives queue row and mutation types from the runtime `SessionFace` contract rather than importing the connection plugin, so plugin cooperation continues through services and snapshots. Edit is available only when all content blocks are text; the editor cannot silently drop non-text blocks. An editing row exposes only save and cancel, with Enter and Escape as their keyboard equivalents. Delete removes the exact occurrence. +**Web actions address Queue only.** The Host excludes pending steering from `session/queue`; steering retains its existing durable transcript path after consumption. QueueDock hides while empty, renders one pending occurrence directly, and defaults two or more occurrences to a collapsed `" 条排队消息"` header that expands or collapses the complete list. The header exposes `aria-expanded` and `aria-controls`; the expanded list scrolls within a 180px height bound. An active edit or mutation keeps its rows visible, and emptying the queue restores the collapsed default for the next queue. Visible rows expose edit and delete, but no send-now control. The UI derives queue row and mutation types from the runtime `SessionFace` contract rather than importing the connection plugin, so plugin cooperation continues through services and snapshots. Edit is available only when all content blocks are text; the editor cannot silently drop non-text blocks. An editing row exposes only save and cancel, with Enter and Escape as their keyboard equivalents. Delete removes the exact occurrence. The Web stop action preserves pending Queue work; AgentLoop claims the next waking occurrence only after the interrupted turn reaches quiescence, and its dequeue event retires that row without a browser resend. ## Alternatives considered @@ -34,10 +34,10 @@ The Web queue rendered pending messages but could not edit or delete one row. `M ## Verification -AgentLoop contract tests hold prompt admission while editing and removing exact queued occurrences, reject mutations of steering occurrences, and verify the resulting independent turn and terminal lifecycle events. Host schema and proxy tests cover queued-only authoritative snapshots, synchronous re-entrant mutation order, reconnect, cold-Agent rejection, typed not-found errors, and the RPC transport. Client runtime and QueueDock tests cover non-optimistic projection, single-row presentation, default multi-row collapse, interaction-forced visibility, reset after emptying, expansion, text-only editing, save and cancel affordances, removal, retirement races, and disabled mixed-content editing. Keyless browser scenarios capture the default collapsed header before expanding the queue and driving its exposed edit and delete actions through the built Web composition and real HTTP/SSE wire. +AgentLoop contract tests hold prompt admission while editing and removing exact queued occurrences, reject mutations of steering occurrences, and verify the resulting independent turn and terminal lifecycle events. Host schema and proxy tests cover queued-only authoritative snapshots, synchronous re-entrant mutation order, reconnect, cold-Agent rejection, typed not-found errors, and the RPC transport. Client runtime and QueueDock tests cover non-optimistic projection, single-row presentation, default multi-row collapse, interaction-forced visibility, reset after emptying, expansion, text-only editing, save and cancel affordances, removal, retirement races, and disabled mixed-content editing. A keyless browser scenario captures the default collapsed header, drives edit and delete through the built Web composition and real HTTP/SSE wire, then stops consecutive active turns to prove the preserved FIFO advances without clearing its tail. ## Consequences -Queued work gains precise row operations without becoming durable session history. Occurrence identity is a live process-local capability and disappears at claim, cancellation, disposal, or restart; reconnect recovers only queued items still held by the live Agent. Editing excludes mixed content until an editor can preserve every block, while pending steering remains outside this operation surface. +Queued work gains precise row operations without becoming durable session history. Occurrence identity is a live process-local capability and disappears at claim, broad cancellation, disposal, or restart; the Web stop action preserves it until a later claim, while reconnect recovers only queued items still held by the live Agent. Editing excludes mixed content until an editor can preserve every block, while pending steering remains outside this operation surface. The protocol now carries full queue snapshots on each change. Queues are expected to remain short, so deterministic recovery and multi-client convergence are preferred over an incremental mutation protocol. diff --git a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.zh.md b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.zh.md index 701b028c74..65617e492c 100644 --- a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.zh.md +++ b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.zh.md @@ -18,7 +18,7 @@ Web 队列能够渲染待处理消息，但无法编辑或删除其中某一行 **Queue 寻址要求 Agent 存活。** `session.updateQueue` 只查询已挂载的 Agent 注册表，绝不恢复冷会话：`InboxItemId` 属于进程本地标识，无法在重启或资源释放后继续指向工作。Agent 缺失和单次入队项已被驱动器认领这两种情况都返回 `queue-item-not-found`。 -**Web 操作只面向 Queue。** Host 从 `session/queue` 中排除待处理 steering；steering 消费后仍沿用既有的持久 transcript（文本记录）路径。QueueDock 在队列为空时隐藏，只有一个待处理项时直接渲染该行，存在两个或更多待处理项时则默认收起为可展开或收起完整列表的 `" 条排队消息"` 表头。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。可见行暴露编辑和删除操作，不提供立即发送控件。UI 从运行时 `SessionFace` 契约派生队列行与变更类型，而不是导入连接插件，因此插件仍通过服务和快照协作。仅当所有内容块都是文本时才提供编辑功能；编辑器不能静默丢弃非文本块。编辑中的行只展示保存和取消操作，对应的键盘操作分别是 Enter 和 Escape。删除会移除对应的精确入队项。 +**Web 操作只面向 Queue。** Host 从 `session/queue` 中排除待处理 steering；steering 消费后仍沿用既有的持久 transcript（文本记录）路径。QueueDock 在队列为空时隐藏，只有一个待处理项时直接渲染该行，存在两个或更多待处理项时则默认收起为可展开或收起完整列表的 `" 条排队消息"` 表头。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。可见行暴露编辑和删除操作，不提供立即发送控件。UI 从运行时 `SessionFace` 契约派生队列行与变更类型，而不是导入连接插件，因此插件仍通过服务和快照协作。仅当所有内容块都是文本时才提供编辑功能；编辑器不能静默丢弃非文本块。编辑中的行只展示保存和取消操作，对应的键盘操作分别是 Enter 和 Escape。删除会移除对应的精确入队项。Web 停止操作会保留待处理 Queue 工作；只有在被中断轮次达到完全停稳后，AgentLoop 才认领下一个可唤醒入队项，其出队事件会退役该行，无需浏览器重发。 ## 考虑过的替代方案 @@ -34,10 +34,10 @@ Web 队列能够渲染待处理消息，但无法编辑或删除其中某一行 ## 验证 -AgentLoop 契约测试会在编辑和移除精确 queued 入队项时阻塞提示词接纳，拒绝对 steering 入队项的变更，并验证所得独立轮次及终态生命周期事件。Host schema 与代理测试覆盖仅含 queued 项的权威快照、同步可重入变更顺序、重连、拒绝冷 Agent、类型化 not-found 错误和 RPC 传输。客户端运行时和 QueueDock 测试覆盖非乐观投影、单行呈现、多行默认收起、交互期间强制保持可见、清空后重置、展开、仅文本编辑、保存与取消入口、移除、退役竞态，以及禁用混合内容编辑。无密钥浏览器场景会先捕获默认收起的表头，再展开队列，并通过构建后的 Web 组合和真实 HTTP／SSE 协议操作其公开的编辑和删除。 +AgentLoop 契约测试会在编辑和移除精确 queued 入队项时阻塞提示词接纳，拒绝对 steering 入队项的变更，并验证所得独立轮次及终态生命周期事件。Host schema 与代理测试覆盖仅含 queued 项的权威快照、同步可重入变更顺序、重连、拒绝冷 Agent、类型化 not-found 错误和 RPC 传输。客户端运行时和 QueueDock 测试覆盖非乐观投影、单行呈现、多行默认收起、交互期间强制保持可见、清空后重置、展开、仅文本编辑、保存与取消入口、移除、退役竞态，以及禁用混合内容编辑。一个无密钥浏览器场景会捕获默认收起的表头，通过构建后的 Web 组合和真实 HTTP／SSE 协议执行编辑和删除，随后连续停止活动轮次，证明保留的 FIFO 会继续推进且不清空队尾。 ## 后果 -queued 工作获得精确的行操作，但不会因此成为持久会话历史。单次入队标识是进程本地的实时寻址凭据，会在认领、取消、dispose 或重启时消失；重连只能恢复仍由活跃 Agent 持有的 queued 项。编辑会排除混合内容，直至编辑器能够保留每个块；待处理 steering 则不属于此操作接口。 +queued 工作获得精确的行操作，但不会因此成为持久会话历史。单次入队标识是进程本地的实时寻址凭据，会在认领、广义取消、dispose 或重启时消失；Web 停止操作会将其保留到后续认领，而重连只能恢复仍由活跃 Agent 持有的 queued 项。编辑会排除混合内容，直至编辑器能够保留每个块；待处理 steering 则不属于此操作接口。 现在，协议会在每次变更时携带完整队列快照。队列预期保持较短，因此系统优先选择确定性恢复和多客户端收敛，而非增量变更协议。 diff --git a/.agents/notes/implemented/feature/2026-07-30-compaction-progress-visibility.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-compaction-progress-visibility.i18n.yaml new file mode 100644 index 0000000000..c922eb5a91 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-compaction-progress-visibility.i18n.yaml @@ -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-07-30-compaction-progress-visibility.md +2026-07-30-compaction-progress-visibility.md: b4d95d4bc645924b96eab6a36ee7b8f36b76a2c6 +2026-07-30-compaction-progress-visibility.zh.md: e444fbdfbf1c865a5bb3b6675a5ff318c5cef9e7 diff --git a/.agents/notes/implemented/feature/2026-07-30-compaction-progress-visibility.md b/.agents/notes/implemented/feature/2026-07-30-compaction-progress-visibility.md new file mode 100644 index 0000000000..b4d95d4bc6 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-compaction-progress-visibility.md @@ -0,0 +1,49 @@ +# Agent Note: Live standalone compaction progress in the terminal + +Status: implemented + +English | [中文](2026-07-30-compaction-progress-visibility.zh.md) + +## Problem + +A standalone manual compaction runs between turns while the agent remains idle. The TUI's turn-phase indicator therefore kept its plain `>` caret throughout the slow summary operation, and a failed attempt produced no transcript row because no replacement checkpoint landed. The liveness presentation needs to reuse the existing status indicator without introducing a second animated status location. + +The durable log can retain an unmatched `compact/start` after a process dies. That orphan is useful recovery evidence, but it is not proof that work is running in the current process; replaying it as progress would leave resumed sessions with a permanent phantom indicator. + +## Decision + +The TUI treats the live standalone `compact/start { turn: null }` to matching `compact/end` bracket as the source of in-flight compaction presentation. A module-local `compacting` cell records the render-clock start and owns one animation timer. A fixed row above the prompt renders `Context being compacted ` from that clock, the existing one-cell running status indicator renders `⊙` through the same fade and throb path as turn-phase glyphs, and the terminal progress bit remains active until the bracket closes. + +`runningPhaseGlyph` owns the choice among turn-phase glyphs, `⊙`, and the idle caret. Turn-phase glyphs take precedence because numbered compaction brackets are enclosed by a running turn whose phase already lights the indicator. The fixed row is outside the transcript and owns neither a spinner nor another timer; it collapses when empty. The compaction cell does not change the idle editor border, hint, or steering badge, so prompts remain visibly accepted while standalone compaction reserves turn admission. + +The cell is live-only. Mount and transcript replay never scan history for an unmatched start; only a `session/event` notification observed by the mounted TUI can open it. Turn-status transitions preserve the cell, while terminal teardown clears its timer and progress bit. + +On `compact/end`, the TUI clears the cell before starting the ordinary glyph fade-out. An end carrying `error` adds `Compaction failed: ` as a warning. Successful completion remains represented by the landed replacement's transcript marker, and duration remains derivable from the matching durable start and end timestamps without another settled row. + +This decision partially supersedes only the progress-related deferred clauses in the [terminal transcript decision](../bug-fix/2026-07-29-human-transcript-append-origin.md) and [browser transcript decision](../bug-fix/2026-07-30-web-transcript-log-ordered-projection.md): progress does not require marker scale or a replacement-rendering refactor. Both notes remain active and continue to own append-origin transcript projection and landed checkpoint markers. The [queued manual compaction decision](2026-07-30-queued-manual-compaction.md) remains the owner of bracket ordering, locking, and stale-orphan classification. + +## Alternatives considered + +**Add `progressLabel` to `CommandDefinition` and a second TUI status controller, as explored in PR #669.** Rejected because command metadata is not the compaction lifecycle authority, automatic compaction does not originate from a human command, and two status controllers can disagree about the same indicator. + +**Add `compacting` to `TurnPhase`, as explored in PR #669.** Rejected because standalone compaction deliberately has no turn, while numbered compaction already has a visible running-turn phase. + +**Add a fifth `TimingBucket`.** Rejected because timing buckets partition an open model step and feed its transcript footer. Standalone compaction has no step transition, and a new bucket would add a meaningless compaction column to every step total. + +**Share one timer among running, fading, and compaction states.** Rejected because fade-out owns a self-terminating timer, while live compaction has an independent open/close lifetime. Sharing would restructure the reviewed animation state machine without removing an actual concurrent timer. + +**Scan the log for an unmatched `compact/start`.** Rejected because a stale orphan from an earlier process lifecycle is expected durable history. Only the live notification proves current work. + +**Use a generic command-running indicator.** Rejected for this behavior because the compaction bracket is the more precise source and also covers non-command paths. A future generic command indicator belongs to the `command/run` / `command/done` lifecycle. + +**Add an animated compaction row to the transcript.** Rejected because it creates a second status animation point for the same lifecycle. The existing one-cell indicator owns liveness, while the landed marker and failure warning own settled transcript presentation. + +**Print a success notice with duration.** Rejected because the landed replacement already supplies the completion marker. The bracket timestamps preserve duration for a future presentation that justifies another transcript row. + +## Consequences + +Manual compaction has a named elapsed-time display above the prompt while the agent is idle, failure has a direct warning, and a resumed orphan never looks active. The prompt indicator remains one terminal cell wide, while the row and indicator reuse the existing status animation, semantic palette, and terminal-progress lifecycle. + +The live cell and timer are additional process-local state, cleared on both bracket close and TUI teardown. This is intentionally not reconstructible presentation state: durable history supplies the successful marker and timing facts, while current-process observation alone supplies liveness. + +The package-level TUI tests pin standalone start, elapsed-time refresh, single-indicator presentation, numbered-start exclusion, fade-out, failure warning, idle-status preservation, running-turn precedence, orphaned resume, and timer disposal. The assembled `queued-manual-compact` terminal scenario observes `Context being compacted 1.0s` and `dsh ⊙` while the real summary boundary is held. diff --git a/.agents/notes/implemented/feature/2026-07-30-compaction-progress-visibility.zh.md b/.agents/notes/implemented/feature/2026-07-30-compaction-progress-visibility.zh.md new file mode 100644 index 0000000000..e444fbdfbf --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-compaction-progress-visibility.zh.md @@ -0,0 +1,49 @@ +# Agent Note: 终端中的实时独立压缩进度 + +Status: implemented + +[English](2026-07-30-compaction-progress-visibility.md) | 中文 + +## 问题 + +独立手动压缩（compaction）在轮次之间运行，此时 agent（智能体）保持空闲。因此，在缓慢的摘要操作期间，TUI 的轮次阶段指示器始终显示普通的 `>` 光标；尝试失败时，由于没有替换检查点落地，也不会产生 transcript（文本记录）行。运行状态显示需要复用现有的状态指示器，不能再设置第二处带动画的状态显示。 + +进程终止后，持久日志中可能保留未匹配的 `compact/start`。该未匹配标记是有用的恢复证据，但无法证明当前进程中有工作正在运行；若将其回放为进度，恢复后的会话便会永久显示虚假的进度指示。 + +## 决策 + +TUI 将实时独立的 `compact/start { turn: null }` 与匹配的 `compact/end` 组成的标记对，作为显示进行中压缩状态的真源。模块局部的 `compacting` 状态记录渲染时钟的起始时间，并独占一个动画定时器。提示词上方的固定行根据该时钟渲染 `Context being compacted `，现有的单格运行状态指示器通过与轮次阶段字形相同的明暗渐变和呼吸律动路径渲染 `⊙`，终端进度标志位会保持活跃，直至标记对闭合。 + +`runningPhaseGlyph` 负责在轮次阶段字形、`⊙` 和空闲光标之间作出选择。轮次阶段字形的优先级更高，因为带编号的压缩标记对处于运行中的轮次内，该轮次的阶段已经激活指示器。该固定行位于 transcript 之外，不带 spinner，也不另设定时器；内容为空时会折叠。压缩状态不会改变空闲编辑器边框、提示或 steering（中途引导）徽标，因此，在独立压缩预留轮次准入期间，界面仍会明确显示提示词已获接纳。 + +该状态只反映实时事件。挂载和 transcript 回放绝不会扫描历史以查找未匹配的 start；只有已挂载的 TUI 观察到 `session/event` 通知，才能开启它。轮次状态转换会保留该状态，而终端清理会清除其定时器和进度标志位。 + +收到 `compact/end` 时，TUI 会先清除状态，再启动普通字形的淡出。携带 `error` 的结束事件会以警告形式添加 `Compaction failed: `。成功完成仍由已落地替换项的 transcript 标记呈现；无需再添加已结算的行，也可从匹配且已持久记录的开始与结束时间戳推导持续时间。 + +本决策仅部分取代[终端 transcript 决策](../bug-fix/2026-07-29-human-transcript-append-origin.md)和[浏览器 transcript 决策](../bug-fix/2026-07-30-web-transcript-log-ordered-projection.md)中与进度相关的延期条款：进度显示不要求标记携带规模信息，也不要求重构替换项渲染。两份记录均保持活动状态，并继续负责基于追加来源的 transcript 投影和已落地检查点标记。[排队式手动压缩决策](2026-07-30-queued-manual-compaction.md)继续负责标记对顺序、锁定机制和陈旧未匹配标记分类。 + +## 曾考虑的替代方案 + +**按照 PR（Pull Request）#669 中探索的方案，为 `CommandDefinition` 添加 `progressLabel` 和第二个 TUI 状态控制器。** 不予采用：命令元数据并非压缩生命周期的权威依据，自动压缩并非由人工命令发起，两个状态控制器也可能对同一个指示器给出不一致状态。 + +**按照 PR #669 中探索的方案，将 `compacting` 添加到 `TurnPhase`。** 不予采用：独立压缩按设计没有轮次，而带编号的压缩已经具有可见的运行轮次阶段。 + +**添加第五个 `TimingBucket`。** 不予采用：计时分桶用于划分一个开放模型步骤内的时间，并为其 transcript 页脚提供数据。独立压缩没有步骤转换，新分桶会在每个步骤总计中加入一个没有意义的压缩列。 + +**让运行、淡出和压缩状态共享一个定时器。** 不予采用：淡出过程独占一个会自行终止的定时器，而实时压缩有独立的开启与闭合生命周期。共享定时器会重构已经评审的动画状态机，却不能消除实际存在的并发定时器。 + +**扫描日志，查找未匹配的 `compact/start`。** 不予采用：来自先前进程生命周期的陈旧未匹配标记是预期的持久历史。只有实时通知才能证明当前进程正在执行工作。 + +**使用通用的命令运行指示器。** 本行为不采用该方案，因为压缩标记对是更精确的真源，并且还覆盖非命令路径。未来若实现通用命令指示器，应归属于 `command/run` 和 `command/done` 生命周期。 + +**在 transcript 中添加动画压缩行。** 不予采用：这会为同一个生命周期设置第二处状态动画显示。现有的单格指示器负责显示运行状态，而已落地标记和失败警告负责已结算的 transcript 呈现。 + +**打印包含持续时间的成功通知。** 不予采用：已落地的替换项已经提供完成标记。标记对的时间戳保留了持续时间，可供未来能够证明新增 transcript 行合理的展示方式使用。 + +## 后果 + +手动压缩在 agent 空闲时会在提示词上方显示带名称的已用时间，失败会直接产生警告，恢复会话时的陈旧未匹配标记绝不会显示为活动状态。提示符指示器保持一个终端字符单元宽，状态行和指示器则复用现有的状态动画、语义调色板和终端进度生命周期。 + +实时状态及其定时器是额外的进程局部状态，在标记对闭合和 TUI 清理这两种情况下都会清除。按设计，这种显示状态不可重建：持久历史提供成功标记与计时事实，只有当前进程的观察才能提供运行中状态。 + +包（package）级 TUI 测试固定了以下行为：独立开始事件、已用时间刷新、单指示器呈现、排除带编号的开始事件、淡出、失败警告、保留空闲状态、运行轮次优先级、存在未匹配标记时的恢复，以及定时器释放。组装后的 `queued-manual-compact` 终端场景会在真实摘要边界保持开放期间观察到 `Context being compacted 1.0s` 和 `dsh ⊙`。 diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml new file mode 100644 index 0000000000..33740e2b31 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml @@ -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-07-30-queued-manual-compaction.md +2026-07-30-queued-manual-compaction.md: 05676ef824bc62ddbdbd8895a325570e91e4bafd +2026-07-30-queued-manual-compaction.zh.md: b2e40a42451570887a194c215df07e98aa1bd864 diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md new file mode 100644 index 0000000000..05676ef824 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md @@ -0,0 +1,110 @@ +# Agent Note: Queued manual compaction with one durable lock + +Status: implemented + +English | [中文](2026-07-30-queued-manual-compaction.zh.md) + +## Problem + +Automatic compaction protects the context window, but an interactive user also needs a deterministic way to condense accumulated history before pressure policy fires. Sending `/compact` as prompt text would spend a model turn and let the conversation model reinterpret a direct control action. Implementing it inside one UI would duplicate command discovery, lifecycle logging, cancellation, and backend policy. + +The human command arrives between turns and must summarize asynchronously. A prompt accepted during that wait must keep its ordinary identity, FIFO position, and wakeup behavior, but it must not derive a request from history that compaction is about to replace. A status check is insufficient: a waking send schedules the driver's claim as a microtask, leaving a same-tick interval where status still reads idle even though the prompt already has right of way. + +Compaction also needs one mutual-exclusion fact shared by manual, pressure, overflow, and explicit-range entry points. A process-local flag alone cannot explain a crash-recovered log, while a summarize-first transaction leaves no durable evidence during the expensive interval. Conversely, treating marker pairs as exclusive containers would forbid valid idle injection even though injection is explicitly non-waking and immediate between turns. + +This note extends the [compaction capability seam](2026-06-18-compaction-capability-seam.md), the [session end-seed boundary](../architecture/2026-07-30-session-end-seed-log-boundary.md), and the [removal of synthetic log-only turns](../simplification/2026-07-28-remove-synthetic-log-only-turns.md). The supersession audit found partial overlap only: each remains active and owns its broader decision. + +## Decision + +### `/compact` is a command over a backend-independent seam + +`@deepseek-ai/dsh-command-compact` registers one argument-free human command through `ctx.commands`. It calls the third abstract `CompactService` operation, `compactNow(agent, signal)`, and maps the closed `ManualCompactionError` taxonomy (`busy | changed | summary | commit | persistence`) to direct UI results. `command/run` and `command/done` preserve the command lifecycle without entering model history or consuming a model-loop turn. + +The command plugin tracks each real handler promise independently of the command executor's abort-aware wait. Its composite lifecycle effect unregisters `/compact` before asynchronously draining handlers that already started, so root teardown reaches quiescence only after backend close and flush work settles. + +The seam's `ManualCompactAgentContext` adds only `reserveTurnAdmission()` to the session and routing facts compaction already needs. Retention, balancing, summarization, marker ordering, replacement, and durability remain backend responsibilities. + +### Idle turn admission is synchronously reservable + +`Agent.reserveTurnAdmission(): (() => void) | undefined` claims the boundary before the next ordinary turn. It succeeds only when the driver is idle, no reservation exists, and no accepted waking item already owns the next turn, including a wake whose claim is still a pending microtask. + +The reservation does not create a second queue. Later sends keep their `InboxItemId`, placement, FIFO order, and wakeup facts. `acceptsNextStep` remains false, so waking next-step input becomes an ordinary queued follow-up rather than steering. Release is idempotent and re-arms the existing driver path. `inject()` is not withheld. + +`whenIdle()` treats a reservation as unfinished activity, including when it holds a waking item. Lifecycle teardown still drains the driver's own activity promise rather than awaiting an external operation, so disposal can cancel and unwind without depending on the reservation holder. + +### One parameterized transaction owns every bracket + +`dsh-compact-basic` has one region transaction parameterized by bracket owner (`number | null`), stability rule (whole surface or selected span), and an optional flush. It performs one ordering: + +1. validate the selected positional range and inspect the durable tail; +2. reject a live unmatched compaction marker; +3. append `compact/start` synchronously; +4. prepare and await summarization; +5. revalidate the required stability; +6. append `compact/summary` and the replacement `user/message`; +7. make exactly one `compact/end` attempt; +8. flush when the manual caller requested durability. + +Automatic and explicit-region work use the numeric owner recovered from the open turn and require whole-surface stability. Manual work reserves admission first, selects a useful range before the transaction, and writes nothing when selection returns `null`. Its bracket uses `turn: null`, requires only selected-span stability, and flushes every successfully closed attempt before releasing admission in `finally`. + +`compact/start` is therefore the only compaction lock. There is no `WeakSet`, wrapper mutex, locked/unlocked method split, or redundant activity check around the transaction. + +### Bracket-first deliberately differs from the surveyed implementations + +Codex models manual compaction as a `CompactTask` occupying its active-turn slot while automatic compaction runs inline. Pi uses the existence of a compaction abort controller as its mutex and appends compaction only after success. Claude Code shares one compaction routine between automatic and manual paths but constructs its boundary after summary streaming. + +DSH deliberately records `compact/start` before calling the summarizer. A slow or crashed attempt is observable, automatic and manual paths share the same durable lock, and a later writer cannot mistake an in-flight summary for an unlocked session. This is a conscious divergence from summarize-first behavior, not an accidental event-order difference. + +### Markers are time points, not an event container + +`compact/start` and `compact/end` mean lock acquisition and release. They do not claim exclusive ownership of every event between their seqs. An idle `inject()` may append a `user/message` while a manual summary is pending, so that unrelated event can sit inside the marker interval. + +Manual stability checks only the selected span: it must remain present, contiguous, ordered, equally priced, and balanced. Append-only context outside it does not stale the summary. Positional replacement places the checkpoint at the old span's surface position and leaves injected context after it in derived model history, even though the injection's log seq precedes the later summary and replacement events. + +Failed `changed` or `summary` attempts leave the conversation surface unchanged, but the log is not unchanged: it contains `compact/start` and `compact/end { error }`. User-facing text states that distinction. + +### End-seed distinguishes live and stale orphans + +Tail scanning finds the current turn, unmatched compaction start, and newest `session/end-seed` independently. An unmatched start after the newest end-seed is live and blocks every compaction entry point. An unmatched start before a later end-seed belongs to an earlier session lifecycle and is stale, so it does not wedge the resumed or forked session. + +The compaction invariant uses the same transition logic during seed replay: `session/end-seed` clears an open historical trace. The boundary need not publish live from the constructor for this case; replay is the load-bearing path. + +The client request projection closes an unmatched compaction request as interrupted at the `session/end-seed` time and clears its active index. A later `compact/start` therefore creates an independent request instead of leaving or overwriting a permanently running orphan. + +Once a transaction has appended its start, every later failure makes one closing attempt. A failed close leaves the unmatched start deliberately visible and blocking, and no flush is attempted. A closed manual attempt is flushed even when it reports an expected failure. Cancellation retains exact-reason precedence after required close and flush cleanup. + +### Reference implementation boundaries + +[PR #835](https://github.com/deepseek-harness/deepseek-harness/pull/835) was used as a reference implementation for the command, reservation, tests, and snapshot shape, but was not merged. Its process-local `WeakSet` lock and locked/unlocked method splits were considered and not adopted because the durable bracket is the single reachable lock. + +That reference also carried client-side replacement-anchor machinery to preserve transcript placement. The log-ordered transcript projection already consumes compaction from event order and does not consult mutable surface positions, so those anchors were considered and not adopted. + +## Alternatives considered + +**Check `agent.status` without reserving admission.** Rejected because an accepted waking send can still be waiting on its claim microtask while status reads idle. + +**Queue the command itself.** Rejected because `/compact` is direct control, not model input, and a prompt already accepted first must retain right of way rather than being reordered around a second command queue. + +**Summarize before appending `compact/start`.** Rejected because the expensive in-flight operation would be invisible and would not participate in the lock shared by automatic compaction. + +**Use both a durable marker and a process-local mutex.** Rejected because two authorities can disagree after replay and require wrapper branches for states the bracket already expresses. + +**Hold injection with waking prompts.** Rejected because idle injection is non-waking durable context by contract; delaying it would make plugin ordering depend on a UI command. + +**Require the marker interval to contain only compaction events.** Rejected because markers represent lock time points. Provenance names the selected and shadowed seqs exactly; exclusivity would add no correctness and would reject valid injection. + +**Treat every unmatched marker as permanently busy.** Rejected because a crash-recovered or forked session would remain wedged. `session/end-seed` is the explicit lifecycle evidence that distinguishes stale history from a live process-local attempt. + +## Verification + +Agent-loop tests cover same-tick right of way, preserved IDs and FIFO lifecycle, waking and quiet queued work, idempotent release, `whenIdle()`, cancellation, and teardown. Compact tests cover standalone and numbered invariant ownership, end-seed replay, live versus stale orphans, re-entrant listeners, selected-span drift, commit and close failures, flush ordering, exact cancellation causes, raw output and usage preservation, and automatic/manual mutual exclusion. + +The command package pins registration, Loader composition, argument rejection, exact success/failure text, cancellation, absence from model history, and disposal waiting across separate close and flush boundaries after an abort stops the executor from awaiting the handler. The client runtime projection test pins end-seed interruption followed by an independent completed attempt. The `queued-manual-compact` terminal snapshot drives real keystrokes through the assembled TUI: `/help` discovers the command, a held summary admits a queued prompt and immediate injection, `turn: null` markers and the flush precede the queued prompt turn, command lifecycle stays log-only, and the derived order is checkpoint → injection → queued prompt. + +## Consequences + +Interactive users can compact useful history without spending a conversation-model turn. A prompt accepted before the command wins; one submitted during the command waits with its original queue identity. Manual compaction consumes session seqs but no turn number. + +The log exposes slow, failed, crashed, and successful attempts through the same bracket. A stale pre-boundary orphan no longer wedges a new lifecycle, while a current unmatched start remains a hard busy signal. Marker intervals may contain unrelated events, so consumers use provenance and relative ordering rather than assuming a contiguous compaction-only slice. + +The shared transaction keeps one ordering and one lock across every entry point. Failure reporting is precise about whether only the log changed, the surface may have partially changed, or the in-memory commit could not be persisted. diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md new file mode 100644 index 0000000000..b2e40a4245 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md @@ -0,0 +1,110 @@ +# Agent Note: 使用单一持久锁实现排队手动压缩 + +Status: implemented + +[English](2026-07-30-queued-manual-compaction.md) | 中文 + +## 问题 + +自动压缩（compaction）可以保护上下文窗口，但交互用户还需要一种确定性方法，在压力策略触发前压缩累积的历史。把 `/compact` 作为提示词文本发送会消耗一个模型轮次，还会让会话模型重新解释一项直接控制操作。在某个 UI 内实现该功能，则会重复命令发现、生命周期日志记录、取消与后端策略。 + +面向用户的命令在轮次之间到达，并且必须异步生成摘要。在等待期间获接纳的提示词必须保留普通身份、FIFO 位置与唤醒行为，但不得从即将被压缩替换的历史派生请求。仅检查状态并不足够：唤醒发送会把驱动器的认领安排为 microtask，因此在同一 tick 内存在一段间隔，此时状态仍显示 idle，但提示词已经拥有优先权。 + +手动、压力、溢出和显式范围入口点还需要共享同一项互斥事实。仅使用进程本地标志无法解释一份崩溃恢复后的日志，而先摘要再记录的事务在开销较大的等待期间不会留下持久证据。反过来，把标记对视为排他容器又会禁止有效的空闲注入，尽管注入按定义不会唤醒，并且会在轮次之间立即执行。 + +本 Agent Note 扩展[压缩能力 seam](2026-06-18-compaction-capability-seam.md)、[会话 end-seed 边界](../architecture/2026-07-30-session-end-seed-log-boundary.md)和[移除纯日志事件的合成轮次](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)。取代关系审计只发现部分重叠：三者均保持活动状态，并拥有各自更广泛的决策。 + +## 决策 + +### `/compact` 是基于后端无关 seam 的命令 + +`@deepseek-ai/dsh-command-compact` 通过 `ctx.commands` 注册一个无参数、面向用户的命令。它调用第三个抽象 `CompactService` 操作 `compactNow(agent, signal)`，并把封闭的 `ManualCompactionError` 分类体系（`busy | changed | summary | commit | persistence`）映射为直接 UI 结果。`command/run` 和 `command/done` 保留命令生命周期，同时不进入模型历史，也不消耗模型循环轮次。 + +命令插件会独立跟踪每个实际处理器 promise，不依赖命令执行器的中止感知等待。其复合生命周期 effect 先注销 `/compact`，再异步等待所有已开始的处理器结算，因此根级 teardown 只有在后端的闭合与 flush 工作结算后才会完全停稳。 + +该 seam 的 `ManualCompactAgentContext` 只在压缩已需使用的会话与路由事实之上增加 `reserveTurnAdmission()`。保留、平衡、摘要、标记排序、替换与持久性仍由后端负责。 + +### 可以同步预留空闲轮次接纳 + +`Agent.reserveTurnAdmission(): (() => void) | undefined` 会在下一个普通轮次之前认领边界。仅当驱动器空闲、没有既存预留，而且尚无已获接纳的唤醒项拥有下一轮次时，它才会成功；仍在等待 microtask 认领的唤醒项也包括在内。 + +该预留不会创建第二个队列。之后发送的项保留其 `InboxItemId`、位置、FIFO 顺序与唤醒信息。`acceptsNextStep` 保持 false，因此唤醒的 next-step 输入会成为普通的排队 follow-up，而不是 steering（中途引导）。释放操作可幂等调用，并重新启用既有驱动器路径。`inject()` 不受阻塞。 + +`whenIdle()` 会把预留视为尚未完成的活动，包括预留持有唤醒项的情况。生命周期 teardown 仍会排空驱动器自身的 activity promise，而不会等待外部操作，因此 dispose（资源释放）可以执行取消并完成退出清理，无需依赖预留持有方。 + +### 一个参数化事务拥有每一对标记 + +`dsh-compact-basic` 只有一个区域事务，由标记归属值（`number | null`）、稳定性规则（整个 surface 或所选 span）与可选 flush 参数化。它按同一顺序执行： + +1. 验证所选位置范围，并检查持久日志尾部； +2. 拒绝活动的未匹配压缩标记； +3. 同步追加 `compact/start`； +4. 准备并等待摘要； +5. 重新验证所需稳定性； +6. 追加 `compact/summary` 与替换用的 `user/message`； +7. 恰好尝试一次 `compact/end`； +8. 当手动调用方要求持久性时执行 flush。 + +自动和显式区域工作使用从开放轮次恢复的数字归属值，并要求整个 surface 保持稳定。手动工作会先预留接纳，在进入事务前选择有效范围；选择结果为 `null` 时不写入任何内容。其标记对使用 `turn: null`，只要求所选 span 保持稳定，并在 `finally` 中释放接纳预留前 flush 每次成功闭合的尝试。 + +因此，`compact/start` 是唯一的压缩锁。不存在 `WeakSet`、包装层 mutex、locked／unlocked 方法拆分，也不存在事务外部重复的活动状态检查。 + +### 先记录标记有意不同于调研过的实现 + +Codex 将手动压缩建模为占用其活动轮次槽位的 `CompactTask`，自动压缩则以内联方式运行。Pi 使用压缩 abort controller 是否存在作为 mutex，并仅在成功后追加压缩。Claude Code 的自动和手动路径共享同一个压缩例程，但会在摘要流结束后才构造边界。 + +DSH 有意在调用摘要器前记录 `compact/start`。缓慢或崩溃的尝试因此可观察，自动与手动路径共享同一个持久锁，之后的写入方也不会把正在生成的摘要误判为未锁定会话。这是对先摘要行为的主动偏离，而不是偶然的事件顺序差异。 + +### 标记是时间点，而不是事件容器 + +`compact/start` 和 `compact/end` 表示获取与释放锁。它们不声称排他拥有二者 seq 之间的每个事件。手动摘要等待期间，空闲的 `inject()` 可以追加 `user/message`，因此该不相关事件可能位于标记区间内。 + +手动稳定性只检查所选 span：它必须仍然存在、连续、有序、计价相同且保持平衡。其外部的仅追加上下文不会使摘要陈旧。位置替换会把检查点放在旧 span 的 surface 位置，并使注入上下文在派生模型历史中位于其后，即使注入的日志 seq 早于后续摘要和替换事件。 + +失败的 `changed` 或 `summary` 尝试会保持会话 surface 不变，但日志并非没有变化：其中会包含 `compact/start` 和 `compact/end { error }`。面向用户的文本会明确说明这一区别。 + +### End-seed 区分活动与陈旧的未匹配标记 + +尾部扫描会分别查找当前轮次、未匹配的 compaction start 与最新 `session/end-seed`。位于最新 end-seed 之后的未匹配 start 是活动锁，会阻塞每个压缩入口点。位于较新 end-seed 之前的未匹配 start 属于更早的会话生命周期，已经陈旧，因此不会卡住恢复或 fork 后的会话。 + +压缩不变量在 seed 回放期间使用同一项转换逻辑：`session/end-seed` 会清除开放的历史追踪状态。此场景不要求构造函数实时发布该边界；回放才是承重路径。 + +客户端请求投影会在 `session/end-seed` 时刻将未匹配的压缩请求以中断状态结束，并清除其活动索引。因此，后续 `compact/start` 会创建一个独立请求，而不是让该遗留的未匹配请求永久保持运行状态或将其覆盖。 + +事务追加 start 后，每次后续失败都会进行一次闭合尝试。闭合失败会有意留下可见且具有阻塞作用的未匹配 start，并且不尝试 flush。已闭合的手动尝试即使报告预期失败也会 flush。完成必需的闭合与 flush 清理后，取消仍保留原始原因优先级。 + +### 参考实现边界 + +[PR #835](https://github.com/deepseek-harness/deepseek-harness/pull/835) 用作命令、预留、测试与快照结构的参考实现，但未被合并。它的进程本地 `WeakSet` 锁与 locked／unlocked 方法拆分经过评估后未被采用，因为持久标记对是唯一可达的锁。 + +该参考实现还包含客户端侧替换锚点机制，用于保留 transcript（文本记录）位置。按日志顺序排列的 transcript 投影已经从事件顺序消费压缩，并且不会查询可变 surface 位置，因此这些锚点经过评估后未被采用。 + +## 曾考虑的替代方案 + +**仅检查 `agent.status`，不预留接纳。** 不予采用，因为已获接纳的唤醒发送可能仍在等待其认领 microtask，而状态仍显示 idle。 + +**把命令本身加入队列。** 不予采用，因为 `/compact` 是直接控制而非模型输入；先获接纳的提示词必须保留优先权，不能围绕第二个命令队列重新排序。 + +**在追加 `compact/start` 前生成摘要。** 不予采用，因为开销较大的进行中操作将不可见，也不会参与自动压缩共享的锁。 + +**同时使用持久标记与进程本地 mutex。** 不予采用，因为两项权威在回放后可能产生分歧，还会要求用包装层分支处理标记对已经表达的状态。 + +**与唤醒提示词一起阻塞注入。** 不予采用，因为按契约，空闲注入是不会唤醒的持久上下文；延迟注入会使插件排序依赖某个 UI 命令。 + +**要求标记区间只包含压缩事件。** 不予采用，因为标记表示锁的时间点。溯源信息会精确指明所选 seq 与被遮蔽 seq；排他性不会增加正确性，只会拒绝有效注入。 + +**把每个未匹配标记都永久视为 busy。** 不予采用，因为崩溃恢复或 fork 后的会话会永久卡住。`session/end-seed` 是区分陈旧历史与当前进程活动尝试的显式生命周期证据。 + +## 验证 + +Agent loop 测试覆盖同一 tick 内的优先权、保留 ID 与 FIFO 生命周期、会唤醒和静默的排队工作、幂等释放、`whenIdle()`、取消与 teardown。压缩测试覆盖独立与数字形式的不变量 owner、end-seed 回放、活动与陈旧未匹配标记、listener 重入、所选 span 漂移、commit 与闭合失败、flush 顺序、原始取消原因、raw output 与 usage 保留，以及自动／手动互斥。 + +命令包固定注册行为、Loader 组合、参数拒绝、精确的成功／失败文本、取消、不进入模型历史的保证，以及处置操作在中止使执行器停止等待处理器后，仍会跨越相互独立的闭合与 flush 边界等待该处理器结算。客户端运行时投影测试固定 end-seed 中断，以及随后一次独立尝试的完成。`queued-manual-compact` 终端快照通过已组装 TUI 驱动真实按键：`/help` 可发现该命令；被暂停的摘要会接纳一个排队提示词和即时注入；`turn: null` 标记与 flush 先于排队提示词轮次；命令生命周期保持纯日志；派生顺序固定为检查点 → 注入 → 排队提示词。 + +## 后果 + +交互用户无需消耗会话模型轮次即可压缩有效历史。在命令前获接纳的提示词胜出；命令期间提交的提示词会以原有队列身份等待。手动压缩会消耗会话 seq，但不消耗轮次编号。 + +日志通过同一对标记暴露缓慢、失败、崩溃与成功的尝试。边界前的陈旧未匹配标记不会再卡住新的生命周期，而当前未匹配 start 仍是严格的 busy 信号。标记区间可以包含不相关事件，因此消费方使用溯源信息与相对顺序，而不假定存在连续且仅含压缩事件的切片。 + +共享事务让每个入口点保持同一种顺序并使用同一把锁。失败报告会精确区分只有日志发生变化、surface 可能部分改变，以及内存 commit 无法持久化这三种情况。 diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.i18n.yaml new file mode 100644 index 0000000000..5a414af614 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.i18n.yaml @@ -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-07-30-versioned-tui-first-run-welcome.md +2026-07-30-versioned-tui-first-run-welcome.md: 5270c239f0bccbf58e68364e195ff2175355a816 +2026-07-30-versioned-tui-first-run-welcome.zh.md: cd132fde5ff0601cef6cd3cd433fdd15dc05f7f0 diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.md b/.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.md new file mode 100644 index 0000000000..5270c239f0 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.md @@ -0,0 +1,43 @@ +# Agent Note: Versioned TUI first-run welcome + +Status: implemented + +English | [中文](2026-07-30-versioned-tui-first-run-welcome.zh.md) + +## Problem + +The shipped `dsh` terminal starts directly in the editor and gives first-time internal testers no durable orientation about the product's maturity or feedback channel. The existing one-line `welcome` banner subtitle cannot carry the supplied notice without crowding the normal session header, and putting onboarding in the session log would create a user turn or model-visible context that is unrelated to the user's work. + +The notice also needs a recognizable DeepSeek composition without copying another product's startup art or maintaining a hand-drawn approximation that drifts from the official mark. + +## Decision + +The official `dsh` launcher owns one versioned acknowledgement marker under the resolved `DSH_HOME`. It checks the immutable marker before boot, then mounts an effect-owned consumer of `ctx.tui.openOverlay()` only after the real TUI service is available. Enter is the sole acknowledgement action: the plugin creates and synchronizes the fixed per-version marker before closing. Escape and unrecognized input leave the overlay open; Ctrl+C and Ctrl+D use the normal exit path without acknowledging. Disposal waits for an acknowledgement already started by Enter, while disposal or process exit before Enter writes nothing. The version is part of the marker filename, so incrementing the centrally owned notice version presents materially revised copy once without migrating or rewriting an aggregate settings document. + +The marker is launcher state rather than session persistence because eligibility spans sessions and workspaces but is scoped to one Harness home. Each Enter syncs a random same-directory file before atomically replacing the fixed marker; concurrent launches publish the same immutable fact, so same-value last-writer-wins replacement has no lost-update shape and needs no lock or dependency on the settings stack. The notice never appends a session event, injects model context, or creates a user turn; resume therefore presents it only when the same Harness home has not acknowledged that version and never replays it from the session log. + +The supplied official `24x24` DeepSeek SVG is committed as the visual source. Static full, compact, and minimal terminal rasters sample that exact path at decreasing square resolutions; they do not redraw the contour. Unicode `▀`/`▄`/`█` cells preserve two vertical source pixels per terminal cell, while an explicitly ASCII-only locale uses the bit-equivalent `'`/`_`/`#` fallback. ANSI styling stays outside both the SVG and editable copy: `ctx.tui` supplies a semantic `brand` role, using the official `#4D6BFE` ink when truecolor is available, standard ANSI blue otherwise, and plain text when color is disabled. The normal startup banner retains its existing gradient. + +The overlay is centered and consumes the available terminal width, while its height follows actual content and treats 90% of the viewport only as an upper bound. Wide terminals place the full icon beside the title and prose; medium and narrow terminals stack the compact or minimal icon above them; low height removes the icon before reducing prose space. The prose scrolls while the title and only action remain fixed. Every locale uses the same centrally owned Chinese copy, and the quotation is promoted to its own visual paragraph without changing that string. Closing through Enter returns modal ownership to the existing FIFO manager, which restores the editor and leaves the normal startup banner, transcript, and focus behavior intact. + +## Verification + +Focused unit coverage pins the supplied SVG and Chinese copy hashes, version bumps, exclusive concurrent acknowledgement, malformed markers, persistence retry, Escape behavior, ASCII fallback, width-tier selection, bounded rendering, and low-height scrolling. Real Loader/PTY cases cover 60, 80, 120, and 160 columns plus a low-height viewport, emit semantic terminal snapshots, prove first launch then second-launch suppression under one `DSH_HOME`, and prove a resumed session appends no notice-derived user message or turn; ordinary terminal-exit lifecycle events remain unchanged. + +## Alternatives considered + +**Reuse the TUI `welcome` subtitle.** It is one transient header line whose normal job is to identify an untitled session. The required prose and action would either be clipped or permanently crowd ordinary launches. + +**Copy Claude Code's startup art or composition.** Its strong hierarchy is useful product evidence, but its graphic, layout, and brand treatment belong to another product. The official DeepSeek SVG provides a direct brand source, and the terminal composition is derived independently around this notice's copy and responsive constraints. + +**Hand-draw an original whale.** A freehand silhouette can be recognizable yet still disagree with the official mark's body, internal negative space, fin, and tail. Exact-path raster sampling keeps the terminal limitation explicit and makes every tier traceable to one source asset. + +**Store a boolean in session events or a shared settings document.** Session state has the wrong lifetime and would pollute replay or model-visible history. An aggregate document would require cross-process read-modify-write locking for one immutable fact; an atomically replaced version marker has no lost-update shape. + +**Allow Escape or a later-reminder action.** Either would make dismissal indistinguishable from acknowledgement or introduce reminder policy that the notice does not need. Normal process exit remains the abort path and leaves the version unacknowledged. + +## Consequences + +Each Harness home receives the notice once per copy version, only after a successful Enter acknowledgement. Maintainers can edit the all-locale Chinese wording and version in one small owner file, and can update the official SVG and derived static rasters in their separate visual owner without chasing snapshots for full prose copies. + +The terminal cannot display SVG vectors directly, so its faithful representation is resolution-bounded. Smaller tiers preserve the sampled silhouette but necessarily lose fine detail; low-height terminals prefer readable prose and an always-reachable action over brand art. The marker format is intentionally one-file-per-version during the pre-release period; old markers are harmless and no compatibility reader is required. diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.zh.md b/.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.zh.md new file mode 100644 index 0000000000..cd132fde5f --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.zh.md @@ -0,0 +1,43 @@ +# Agent Note: 版本化 TUI 首次运行欢迎页 + +Status: implemented + +[English](2026-07-30-versioned-tui-first-run-welcome.md) | 中文 + +## 问题 + +已交付的 `dsh` 终端会直接进入编辑器，没有为首次使用的内部测试者提供持久的产品成熟度说明或反馈渠道指引。现有单行 `welcome` banner 副标题无法容纳指定通知，否则会挤占正常的会话 header；如果把 onboarding 写入会话日志，还会创建一个与用户工作无关的用户轮次或模型可见上下文。 + +该通知还需要形成具有辨识度的 DeepSeek 视觉构图，同时不能复制其他产品的启动图形，也不能维护一份会偏离官方标志的手绘近似图。 + +## 决策 + +官方 `dsh` 启动器在解析后的 `DSH_HOME` 下持有一个版本化确认标记。它会在启动前检查该不可变标记，并仅在真实 TUI 服务可用后，挂载一个由 effect 持有的 `ctx.tui.openOverlay()` 消费方。Enter 是唯一确认操作：插件先创建并同步固定的逐版本标记，再关闭浮层。Escape 和无法识别的输入会让浮层保持打开；Ctrl+C 与 Ctrl+D 通过普通退出路径离开且不确认。资源释放会等待已经由 Enter 启动的确认任务；在按 Enter 前进行资源释放或退出进程不会写入任何内容。版本号属于标记文件名的一部分，因此只需递增集中持有的通知版本，即可让有实质修改的文案重新展示一次，无需迁移或改写聚合设置文档。 + +该标记属于启动器状态，而非会话持久化，因为展示资格跨越会话与 workspace，但作用域仅限一个 Harness 主目录。每次 Enter 都会先同步一个同目录随机文件，再以原子方式替换固定标记；并发启动发布的是同一个不可变事实，因此同值的最后写入者胜出不会丢失更新，也无需加锁或依赖设置栈。该通知绝不追加会话事件、注入模型上下文或创建用户轮次；因此，恢复会话只会在同一个 Harness 主目录尚未确认该版本时展示通知，也绝不会从会话日志中回放通知。 + +指定的官方 `24x24` DeepSeek SVG 作为视觉真源提交。静态的完整、紧凑和最小终端栅格图以逐级降低的方形分辨率对该精确路径取样，不会重新绘制轮廓。Unicode `▀`/`▄`/`█` 单元格让每个终端单元格保留两个垂直方向的源像素；明确仅支持 ASCII 的 locale 则使用位级等价的 `'`/`_`/`#` 回退。ANSI 样式与 SVG 和可编辑文案完全分离：`ctx.tui` 提供语义化 `brand` 角色，在真彩色可用时使用官方 `#4D6BFE` 色值，否则使用标准 ANSI 蓝色；禁用颜色时则使用纯文本。普通启动 banner 保留现有渐变。 + +浮层居中显示，并使用可用的终端宽度；高度则跟随实际内容，仅将 viewport 的 90% 作为上限。宽终端将完整图标置于标题与正文旁边；中等和窄终端把紧凑或最小图标堆叠在正文上方；高度不足时，先移除图标，再减少正文空间。正文可以滚动，而标题和唯一操作保持固定。所有 locale 共用同一份集中持有的中文文案，引用内容会提升为独立的视觉段落，但不会改变该字符串。通过 Enter 关闭浮层后，模态所有权会交还给现有 FIFO 管理器；该管理器恢复编辑器，同时保持正常的启动 banner、transcript（文本记录）和焦点行为不变。 + +## 验证 + +聚焦单元测试固定指定 SVG 与中文文案的 hash、版本递增、并发独占确认、格式错误的标记、持久化重试、Escape 行为、ASCII 回退、宽度分级选择、有界渲染和低高度滚动。真实 Loader/PTY 用例覆盖 60、80、120、160 列以及一个低高度 viewport，产出语义终端快照，证明同一个 `DSH_HOME` 下首次启动后再次启动会抑制展示，并证明恢复会话不会追加任何由通知衍生的用户消息或轮次；普通终端退出的生命周期事件保持不变。 + +## 曾考虑的替代方案 + +**复用 TUI 的 `welcome` 副标题。** 它是一行瞬态 header，正常职责是标识无标题会话。所需正文和操作要么会被裁剪，要么会永久挤占普通启动界面。 + +**复制 Claude Code 的启动图形或构图。** 其清晰的视觉层级是有用的产品证据，但图形、布局和品牌处理属于另一个产品。官方 DeepSeek SVG 提供直接的品牌来源，而终端构图围绕本通知的文案与响应式约束独立推导。 + +**手绘原创鲸鱼。** 自由绘制的轮廓可以具有辨识度，却仍可能与官方标志的身体、内部负空间、鳍和尾部不一致。对精确路径进行栅格取样，可以明确呈现终端限制，并让每个分级都能追溯到同一个源资产。 + +**在会话事件或共享设置文档中存储布尔值。** 会话状态的生命周期不正确，还会污染回放或模型可见历史。聚合文档为记录一个不可变事实，需要承担跨进程读取、修改、写入锁；以原子方式替换的版本标记不存在更新丢失问题。 + +**允许 Escape 或稍后提醒操作。** 两者都会让取消与确认无法区分，或引入本通知并不需要的提醒策略。正常退出进程仍是中止路径，并会让该版本保持未确认状态。 + +## 后果 + +每个 Harness 主目录在每个文案版本中都会收到一次通知，且仅在用户成功按 Enter 确认后停止展示。维护者可以在一个小型 owner 文件中编辑所有 locale 共用的中文文案和版本，也可以在独立的视觉 owner 中更新官方 SVG 与衍生静态栅格图，无需到各个快照中查找完整正文副本。 + +终端无法直接显示 SVG 矢量图，因此其忠实呈现受分辨率限制。较小分级会保留取样后的轮廓，但必然损失精细细节；低高度终端优先保障正文可读和操作始终可达，而非展示品牌图形。在预发布阶段，标记格式有意采用每个版本一个文件；旧标记无害，也无需兼容性读取器。 diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml new file mode 100644 index 0000000000..83e965b391 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml @@ -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-07-31-even-out-shipped-tool-rosters.md +2026-07-31-even-out-shipped-tool-rosters.md: 316e5045e559e2da162c53d64989ccecfd18b857 +2026-07-31-even-out-shipped-tool-rosters.zh.md: ed39212dc4877f4df1dc1c6e84142b61a866c548 diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md new file mode 100644 index 0000000000..316e5045e5 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md @@ -0,0 +1,69 @@ +# Agent Note: Even out the shipped tool rosters + +Status: implemented + +English | [中文](2026-07-31-even-out-shipped-tool-rosters.zh.md) + +## Problem + +The two shipped `dsh` surfaces offered different tools for no recorded reason. Session checkpoints, tool-result pruning, the goal tools, and Ralph were in `tui.cordis.yml`; `tool-todo` and, later, web search were in `web.cordis.yml`. Neither surface offered session search, a string-replacement editor, or a repeat-tool guard, though all three exist as packages and none is surface-specific. + +The result was a user-visible difference nobody had decided: the same model, asked the same thing, could set a goal on the terminal but not in the browser, and could search the web in the browser but not on the terminal. + +## Decision + +The rows that are not surface-specific move into [`base.cordis.yml`](../../../../apps/cli/config/base.cordis.yml), and three more join them: `tool-session-query`, `tool-str-replace-editor`, and `repeat-tool-guard`. Web search moves there too; its [deployment decision](2026-07-31-web-default-search.md) owns the security boundary while the shared base owns its surface-neutral mount. Both surfaces now assemble the same roster: twenty-five tools on every host, plus `glob` and `grep` when ripgrep is available. + +Two rows stay surface-specific. `tmux-context` is TUI-only because a browser surface has no terminal multiplexer to describe. `session-reference` is TUI-only because it drives the shared session-query index from the launcher's process-local path, and the browser sidebar reconciles that index on its own first search. + +**This change adds only.** No row is removed from either surface and no existing row's configuration is edited: the executors, the sandbox composition, the access defaults, `tools.mode`, and the workflow tool are exactly what they were. A reader comparing the two catalogs before and after should find additions and nothing else. + +### What stays unmounted, and why + +Three capabilities stay out on the evidence their own packages record, and are listed here so "we forgot" and "we decided against" stay distinguishable. + +**`dsh-tool-cordis`** lets the model write JavaScript and mount it as a temporary plugin. Its README states the limit: "The sandbox is containment for honest code, not a security boundary — host-realm helpers on the sandbox global are reachable, so mount code can reach Node" ([Known limitations](../../../../packages/cordis/tool-cordis/README.md)). The `node:vm` realm lives inside the harness process while `dsh-sandbox-local` confines only the argv it spawns, so on the Web surface both the sandbox and the approval seam are bypassed rather than enforced. + +**`dsh-web-fetch-local`** stays unmounted and `dsh-tool-web` keeps `fetch: false`. SSRF protection is deferred in the implementation ([`policy.ts`](../../../../packages/web/web-fetch-local/src/policy.ts) validates protocol, credentials, and length only) and the package says so: "this provider is an SSRF primitive and **must not be enabled** in a deployment that can reach sensitive internal network targets" ([README](../../../../packages/web/web-fetch-local/README.md)). The model chooses the target, which includes the harness's own gateway on loopback, private ranges, and cloud metadata endpoints. + +Withholding it narrows the surface without removing the reach: `bash` is mounted, so `curl` gets the same page, as a live run confirmed. What the absence buys is the removal of an argument-shaped request primitive that needs no shell — and with it the accidental path where a summarization request quietly reaches loopback. A deployment that must contain outbound traffic needs a network-level control. + +**The LSP trio** stays out for an operational reason rather than a security one: `command` resolves from `PATH` at plugin load, so a missing language server fails the whole boot rather than one tool. It becomes mountable once absence degrades to a skipped registration. + +### MCP is a dependency, not a row + +`@deepseek-ai/dsh-mcp-client` becomes a runtime dependency of the CLI without a row in any shipped config. The plugin mounts exactly one server per instance and `command` is required, so a default would have to name a third-party server and spawn it as a child process on every launch — outside `ctx.bash`, and therefore outside the sandbox policy the Web surface composes. + +The layer that would make MCP a default is the one this repository does not have yet: a bridge that reads a user's server list and mounts one client per entry, the same shape [`dsh-hooks-claude`](../../../../packages/hooks/hooks-claude/README.md) already has for a Claude Code `hooks.json`. Shipping the dependency means an installed `dsh` can mount servers from `$DSH_HOME/config.yaml` today; the CLI README carries the YAML. + +## Testing + +[`apps/cli/tests/shipped-composition.e2e.ts`](../../../../apps/cli/tests/shipped-composition.e2e.ts) boots the shipped tree through the real Loader in a pseudo-terminal and reads the tool names out of the `request/header` the session log persisted, so the assertion is the catalog the model was actually sent. Its `--config` overlay, [`composition-keyless-tail.cordis.yml`](../../../../apps/cli/tests/fixtures/composition-keyless-tail.cordis.yml), is test isolation only: a network-free adapter and workspace-local session artifacts. + +That tail also inserts [`composition-settled.ts`](../../../../apps/cli/tests/fixtures/composition-settled.ts), which announces settled Loader activation on the terminal stream. The TUI renders as soon as its own fiber starts, so a prompt typed at the banner can reach the loop while tool rows and persistence are still activating and assemble a partial catalog; gating the smoke's first prompt on that marker is what makes the assertion deterministic. + +The same smoke pins the TUI's unchanged execution posture from the same artifact: `tool-bash` emits its `sandbox_permissions` escalation pair only when the mounted executor has wider modes to escalate to, so asserting its **absence** fails if a later change quietly sandboxes this surface. + +[`apps/web/tests/shipped-composition.e2e.ts`](../../../../apps/web/tests/shipped-composition.e2e.ts) covers the Web surface in the built lane, asserting its catalog, that its access default is untouched, and that `workspace-write`'s writable roots include the temp directories — a trap that makes sandbox tests lie when the workspace sits under `/tmp` ([`roots.ts`](../../../../packages/sandbox/sandbox/src/roots.ts)). + +`glob` and `grep` are asserted as an all-or-nothing pair rather than fixed members: `dsh-tool-fs-search` probes `command -v rg` at load and registers neither tool without ripgrep, which is a host dependency. + +Beyond the committed tests, both surfaces were driven against a real key from the built `apps/cli/lib/bin.js` under plain Node. Every mounted tool executed successfully, including `ralph` and `web_search`; the model never reached `cordis_*` or `mcp_*`, fell back to `grep` when asked for LSP navigation, and used a background `bash` task when asked for a persistent terminal. + +## Alternatives considered + +**Duplicate the shared rows into both overlays instead of promoting them.** Rejected on the one-home rule: three of the new rows would exist twice with no reason for the copies to diverge, and the next roster change would have to remember both. + +**Sandbox the TUI in the same change.** Rejected as a separate decision that does not belong in a roster change: the TUI mounts unrestricted executors, and replacing them alters what an existing surface does rather than what it offers. That decision needs its own evidence — not least because the TUI has no `approval/request` answerer, so an escalation there fails closed instead of prompting. + +**Enable Code Mode.** Its trust posture is bash-equivalent by design and its tool calls pass the same `tools/pre-execute` gate as bash, so it is not the same call as the model-code tools above. Rejected here anyway: `both` changes every model-visible request on both surfaces, and `code` replaces the wire rather than adding to it — either is a presentation decision, not a roster one. + +**Mount an MCP server by default.** Rejected because a shipped default would have to name one, and any choice spawns a third-party child process on every user's machine outside the sandbox. The dependency ships instead. + +## Consequences + +The same model gets the same tools on both surfaces, and the difference that existed for no recorded reason is gone. The tests assert the twenty-five unconditional names exactly and require the ripgrep-dependent pair to be either present together or absent together on both sides, so a later change that alters only one surface fails a check instead of shipping quietly. + +`apps/cli` gains five workspace dependencies: four the shipped tree now mounts, plus `dsh-mcp-client`, which it does not mount and which exists so an installed `dsh` can. + +Nothing about execution changed. The TUI still runs the model's commands through unrestricted executors with no approval seam, and the Web surface still defaults to `danger-full-access`. Both are pinned by assertions in this change, which makes them visible rather than fixed — the sandbox decision is still open. diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md new file mode 100644 index 0000000000..ed39212dc4 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md @@ -0,0 +1,69 @@ +# Agent Note: 拉平交付的工具清单 + +Status: implemented + +[English](2026-07-31-even-out-shipped-tool-rosters.md) | 中文 + +## 问题 + +两个交付的 `dsh` surface 提供着不同的工具,而没有任何记录说明为什么。会话检查点、工具结果裁剪、goal 工具和 Ralph 在 `tui.cordis.yml`;`tool-todo` 以及后来的 web 搜索在 `web.cordis.yml`。两个 surface 都没有会话搜索、字符串替换编辑器和重复工具守卫,尽管这三者都已成包存在,且没有一个是 surface 专属的。 + +结果是一处没人做过决定的用户可见差异:同一个模型、同一个请求,在终端上能定目标而在浏览器里不能,在浏览器里能搜网页而在终端上不能。 + +## 决策 + +那些并非 surface 专属的行移入 [`base.cordis.yml`](../../../../apps/cli/config/base.cordis.yml),另有三行加入:`tool-session-query`、`tool-str-replace-editor` 和 `repeat-tool-guard`。Web 搜索也一并移入；其[部署决策](2026-07-31-web-default-search.md)负责安全边界，共享 base 则负责与 surface 无关的挂载。两个 surface 现在组装同一份清单：每台宿主上都有二十五个工具，ripgrep 可用时再加上 `glob` 和 `grep`。 + +有两行仍是 surface 专属。`tmux-context` 只在 TUI,因为浏览器 surface 没有终端复用器可描述。`session-reference` 只在 TUI,因为它以 launcher 的进程本地路径驱动共享的 session-query 索引,而浏览器侧边栏会在自己的首次搜索里重建该索引。 + +**本次改动只做加法。** 两个 surface 都没有任何一行被移除,也没有任何既有行的配置被编辑:执行器、沙箱组合、访问默认值、`tools.mode` 以及 workflow 工具,全都保持原样。对比改动前后的两份目录,读者应当只看到新增,别无其他。 + +### 什么保持不挂,以及为什么 + +有三项能力基于其自身包所记录的证据保持在外,列在这里是为了让「我们忘了」和「我们决定不要」保持可区分。 + +**`dsh-tool-cordis`** 让模型写一段 JavaScript 并挂成临时插件。它的 README 写明了这个界限:「The sandbox is containment for honest code, not a security boundary — host-realm helpers on the sandbox global are reachable, so mount code can reach Node」([Known limitations](../../../../packages/cordis/tool-cordis/README.md))。`node:vm` 的 realm 就在 harness 进程内,而 `dsh-sandbox-local` 只约束它 spawn 出去的 argv,因此在 Web surface 上,沙箱与批准接缝是被绕过而非被执行。 + +**`dsh-web-fetch-local`** 保持不挂,`dsh-tool-web` 保持 `fetch: false`。SSRF 防护在实现中是 deferred 状态([`policy.ts`](../../../../packages/web/web-fetch-local/src/policy.ts) 只校验协议、凭据与长度),包里也直说了:「this provider is an SSRF primitive and **must not be enabled** in a deployment that can reach sensitive internal network targets」([README](../../../../packages/web/web-fetch-local/README.md))。目标由模型选择,其中包括 harness 自己跑在环回地址上的网关、内网段和云元数据端点。 + +弃用它收窄的是接触面而非可达性:`bash` 是挂着的,`curl` 照样能拿到同一个页面——一次真实运行确认了这点。这个缺席买到的是去掉一个无需 shell、以参数成形的请求原语,以及随之而来的那条意外路径:一次「帮我总结这个页面」悄悄打到环回地址。真要收住出站流量的部署需要的是网络层管控。 + +**LSP 三件套**留在外面是运维原因而非安全原因:`command` 在插件加载时从 `PATH` 解析,因此缺少语言服务器会让整次启动失败,而不只是失去一个工具。等到「缺失」退化为「跳过注册」之后,它就可以挂了。 + +### MCP 是依赖,不是配置行 + +`@deepseek-ai/dsh-mcp-client` 成为本 CLI 的运行时依赖,但在任何交付配置里都没有对应的行。该插件每个实例只挂载一台服务器,且 `command` 是必填,因此一个默认值必须点名一台第三方服务器,并在每次启动时把它作为子进程 spawn——不经 `ctx.bash`,因而也在 Web surface 所组合的沙箱策略之外。 + +真正能让 MCP 成为默认的那一层,恰恰是本仓库尚未拥有的:一个读取用户服务器清单、按条目逐台挂载客户端的桥接,形态与 [`dsh-hooks-claude`](../../../../packages/hooks/hooks-claude/README.md) 读取 Claude Code 的 `hooks.json` 完全相同。交付这个依赖意味着已安装的 `dsh` 今天就能从 `$DSH_HOME/config.yaml` 挂载服务器;CLI README 里给了那段 YAML。 + +## 测试 + +[`apps/cli/tests/shipped-composition.e2e.ts`](../../../../apps/cli/tests/shipped-composition.e2e.ts) 在伪终端中通过真实 Loader 启动交付树,并从会话日志持久化的 `request/header` 中读出工具名,因此断言的正是模型实际收到的目录。它传入的 `--config` overlay [`composition-keyless-tail.cordis.yml`](../../../../apps/cli/tests/fixtures/composition-keyless-tail.cordis.yml) 只做测试隔离:一个无网络适配器,以及落在工作区内的会话产物。 + +该尾部还插入了 [`composition-settled.ts`](../../../../apps/cli/tests/fixtures/composition-settled.ts),它在终端字节流上宣告 Loader 激活已 settle。TUI 在自己的 fiber 一启动就渲染,因此在 banner 处敲下的提示词可能在工具行与持久化仍在激活时就抵达循环,从而组装出不完整的目录;把冒烟的首个提示词 gate 在该标记上,正是断言得以确定的原因。 + +同一份冒烟还从同一份产物上钉住 TUI 未改变的执行姿态:`tool-bash` 只在挂载的执行器确实有更宽模式可升级时才发出 `sandbox_permissions` 升级参数对,因此断言它的**缺席**会在日后有人悄悄给这个 surface 加上沙箱时失败。 + +[`apps/web/tests/shipped-composition.e2e.ts`](../../../../apps/web/tests/shipped-composition.e2e.ts) 在构建产物 lane 中覆盖 Web surface,断言它的工具目录、它的访问默认值未被触碰,以及 `workspace-write` 的可写根包含临时目录——一个会让沙箱测试说谎的陷阱,当工作区落在 `/tmp` 下时([`roots.ts`](../../../../packages/sandbox/sandbox/src/roots.ts))。 + +`glob` 与 `grep` 被作为全有或全无的一对断言,而不是固定成员:`dsh-tool-fs-search` 在加载时探测 `command -v rg`,没有 ripgrep 就两个工具都不注册,这是宿主依赖。 + +除入库测试外,两个 surface 都以 plain Node 从构建产物 `apps/cli/lib/bin.js` 出发、用真实密钥驱动过。每一个已挂载的工具都执行成功,包括 `ralph` 与 `web_search`;模型从未触达 `cordis_*` 或 `mcp_*`,被要求做 LSP 跳转时退化到 `grep`,被要求开持久终端时用了后台 `bash` 任务。 + +## 曾考虑的替代方案 + +**把共享的行复制进两份 overlay,而不是提升到 base。** 基于「一处归属」原则否决:新增行里有三行会存在两份,而这些副本没有任何理由发生分歧,下一次改工具清单还得记着改两处。 + +**在同一次改动里给 TUI 加沙箱。** 不予采纳，因为这是一个不属于工具清单改动的独立决定：TUI 挂的是不受限执行器，替换它们会改变一个既有 surface 做什么，而非它提供什么。这个决定需要自己的证据——尤其因为 TUI 没有 `approval/request` 的应答方，升级请求在那里会 fail-closed，而不是弹出提示。 + +**开启 Code Mode。** 它的信任立场按设计与 bash 同级,工具调用要过与 bash 相同的 `tools/pre-execute` 闸门,所以它与上面那些模型写码工具不是同一个判断。在这里仍被否决:`both` 会改变两个 surface 上每一个模型可见请求,而 `code` 是把线路替换而非加一个——两者都是呈现方式的决定,不是工具清单的决定。 + +**默认挂一台 MCP 服务器。** 否决,因为交付默认值必须点名一台,而任何选择都会在每个用户的机器上、在沙箱之外 spawn 一个第三方子进程。改为交付依赖。 + +## 后果 + +同一个模型在两个 surface 上拿到同样的工具,那处没有记录理由的差异消失了。测试会精确断言二十五个无条件提供的名称，并要求依赖 ripgrep 的一对工具在两侧要么同时存在、要么同时缺席，因此日后只改一个 surface 都会让检查失败而不是悄悄发出去。 + +`apps/cli` 增加五个 workspace 依赖:四个是交付树现在挂载的,外加 `dsh-mcp-client`——它并不被挂载,存在的意义是让已安装的 `dsh` 能挂。 + +执行相关的一切都没有变。TUI 仍以不受限执行器运行模型的命令且没有批准接缝,Web surface 仍默认 `danger-full-access`。两者都由本次改动中的断言钉住,这让它们变得可见而非被修复——沙箱那个决定仍然悬着。 diff --git a/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml index f06c290bb3..6b244f3d12 100644 --- a/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml @@ -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-31-web-default-search.md -2026-07-31-web-default-search.md: ddc047a963212cb228da67c6c33128877cacf92c -2026-07-31-web-default-search.zh.md: 05c30b625953ccd54c127a97b646ad7db75f693b +2026-07-31-web-default-search.md: d9616c27410bb5be9b385a9aaa56c22f6054eeb1 +2026-07-31-web-default-search.zh.md: 27cd330427669a78c03b939c737b37f79fd7965a diff --git a/.agents/notes/implemented/feature/2026-07-31-web-default-search.md b/.agents/notes/implemented/feature/2026-07-31-web-default-search.md index ddc047a963..d9616c2741 100644 --- a/.agents/notes/implemented/feature/2026-07-31-web-default-search.md +++ b/.agents/notes/implemented/feature/2026-07-31-web-default-search.md @@ -1,4 +1,4 @@ -# Agent Note: Default Web search in the Web/headless composition +# Agent Note: Default Web search in shipped compositions Status: implemented @@ -10,7 +10,7 @@ The harness had a complete Web capability family—provider registry, DeepSeek/E ## Decision -`apps/cli/config/web.cordis.yml` explicitly mounts `dsh-web` with `searchProvider: deepseek-official`, `dsh-web-search-deepseek`, and `dsh-tool-web` with `fetch: false`. It does not mount `dsh-web-fetch-local` or select a fetch provider. The shared overlay makes only `web_search` a default for browser and headless sessions; the TUI composition remains unchanged. The explicit search provider id keeps selection independent of registration order and leaves personal or `--config` overlays able to replace or disable the rows. +`apps/cli/config/base.cordis.yml` explicitly mounts `dsh-web` with `searchProvider: deepseek-official`, `dsh-web-search-deepseek`, and `dsh-tool-web` with `fetch: false`. It does not mount `dsh-web-fetch-local` or select a fetch provider. The shared base makes only `web_search` a default for TUI, browser, and headless sessions. The explicit search provider id keeps selection independent of registration order and leaves personal or `--config` overlays able to replace or disable the rows. DeepSeek search uses the same `DEEPSEEK_API_KEY` credential reference as the official conversation adapter. The provider resolves that reference inside every search through the optional `ctx.credentials` service; only a composition without the seam falls back to the launching process environment, and a non-empty literal `apiKey` remains the programmatic last resort. A stored or rotated Web Models key therefore reaches the next search without restarting or retaining the value on the provider. Because `WebSearchProvider.available()` is synchronous, it treats an installed resolver as locally usable and missing dynamic credentials fail the operation with the provider-specific `WEB_PROVIDER_CREDENTIAL_MISSING` code while the stable tool schema stays registered. @@ -26,10 +26,10 @@ The default mount does not create a Web-specific permission policy. `web_search` **Freeze `process.env.DEEPSEEK_API_KEY` at provider load.** Rejected because the Web Models page writes through `ctx.credentials`; the product's documented first-run path must make the next operation work without a restart. -**Mount Web tools in `base.cordis.yml`.** Rejected because that would also change the TUI deployment. The browser and headless entries already share `web.cordis.yml`; they gain the capability together while TUI remains an explicit later decision. +**Keep Web tools in `web.cordis.yml`.** Rejected because it preserves an unexplained tool-roster difference between TUI and Web/headless. The rows are not surface-specific, so `base.cordis.yml` is their one home; the [tool-roster decision](2026-07-31-even-out-shipped-tool-rosters.md) records the shared composition. **Enable search and fetch together.** Rejected because default `web_fetch` would allow model-selected anonymous outbound HTTP(S) retrieval to arbitrary URLs. Search covers discovery; deployments that accept broader retrieval can opt into `dsh-web-fetch-local` and set `dsh-tool-web`'s `fetch` option to `true` in their overlay. ## Consequences -Web/headless model requests carry only the `web_search` schema and search-only prompt guidance in native mode; Code Mode exposes the same search capability beneath `run_code`. The prompt tells the model to use returned snippets and never advertises the disabled `web_fetch` tool. Search adds a complete auxiliary model call and may use the native server tool multiple times; its exact secret-free request remains reconstructable from the initiating session log. The default offers search-result snippets and source metadata but no arbitrary page retrieval; deployments that need full-page fetch must opt in. The Web snapshot lane boots the shipped tree, drives a replayed `web_search` call through the real DeepSeek provider against a local Messages fixture, asserts the durable auxiliary request and structured result, and pins the settled browser presentation. The real-composition smoke test pins the absence of `web_fetch`; provider tests pin missing, stored, and rotated credential behavior plus literal and ambient compatibility. +Native model requests on every shipped surface carry only the `web_search` schema and search-only prompt guidance; Web/headless Code Mode exposes the same search capability beneath `run_code`. The prompt tells the model to use returned snippets and never advertises the disabled `web_fetch` tool. Search adds a complete auxiliary model call and may use the native server tool multiple times; its exact secret-free request remains reconstructable from the initiating session log. The default offers search-result snippets and source metadata but no arbitrary page retrieval; deployments that need full-page fetch must opt in. The Web snapshot lane boots the shipped tree, drives a replayed `web_search` call through the real DeepSeek provider against a local Messages fixture, asserts the durable auxiliary request and structured result, and pins the settled browser presentation. The TUI/Web composition smokes pin the shared `web_search` roster and absence of `web_fetch`; provider tests pin missing, stored, and rotated credential behavior plus literal and ambient compatibility. diff --git a/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md index 05c30b6259..27cd330427 100644 --- a/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md +++ b/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md @@ -1,4 +1,4 @@ -# Agent Note: Web／无头组合中的默认 Web 搜索 +# Agent Note: 已交付组合中的默认 Web 搜索 Status: implemented @@ -10,7 +10,7 @@ Status: implemented ## 决策 -`apps/cli/config/web.cordis.yml` 明确挂载 `dsh-web`，配置 `searchProvider: deepseek-official`，同时挂载 `dsh-web-search-deepseek`，并以 `fetch: false` 挂载 `dsh-tool-web`。它不挂载 `dsh-web-fetch-local`，也不选择抓取提供方。共享覆盖层只将 `web_search` 设为浏览器与无头会话的默认工具；TUI 组合保持不变。显式搜索提供方 id 使选择不受注册顺序影响，同时个人覆盖层或 `--config` 覆盖层仍可替换或禁用这些配置项。 +`apps/cli/config/base.cordis.yml` 明确挂载 `dsh-web`，配置 `searchProvider: deepseek-official`，同时挂载 `dsh-web-search-deepseek`，并以 `fetch: false` 挂载 `dsh-tool-web`。它不挂载 `dsh-web-fetch-local`，也不选择抓取提供方。共享 base 只将 `web_search` 设为 TUI、浏览器与无头会话的默认工具。显式搜索提供方 id 使选择不受注册顺序影响，同时个人覆盖层或 `--config` 覆盖层仍可替换或禁用这些配置项。 DeepSeek 搜索使用与官方会话适配器相同的 `DEEPSEEK_API_KEY` 凭据引用。提供方在每次搜索内部通过可选的 `ctx.credentials` 服务解析该引用；只有未挂载该 seam 的组合才会回退到启动进程的环境变量，非空的 `apiKey` 字面值仍作为程序化配置的最后兜底。因此，由 Web 的 Models 页存储或轮换的密钥无需重启即可用于下一次搜索，提供方也无需保留该值。由于 `WebSearchProvider.available()` 是同步方法，它会将已安装解析器视为本地可用；若动态凭据缺失，操作会以提供方专属错误码 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败，而稳定的工具 schema 仍保持注册。 @@ -26,10 +26,10 @@ DeepSeek 搜索使用与官方会话适配器相同的 `DEEPSEEK_API_KEY` 凭据 **在提供方加载时固定读取 `process.env.DEEPSEEK_API_KEY`。** 不予采纳：Web Models 页面通过 `ctx.credentials` 写入密钥；产品文档规定的首次运行路径必须保证下一次操作无需重启即可生效。 -**在 `base.cordis.yml` 中挂载 Web 工具。** 不予采纳：这也会改变 TUI 部署。浏览器与无头入口已经共享 `web.cordis.yml`；两者会一同获得该能力，是否为 TUI 启用则仍留作后续显式决策。 +**将 Web 工具保留在 `web.cordis.yml` 中。** 不予采纳：这会保留 TUI 与 Web／无头界面之间无法解释的工具清单差异。这些配置行并非界面特有，因此其唯一归属是 `base.cordis.yml`；[工具清单决策](2026-07-31-even-out-shipped-tool-rosters.md)记录了这一共享组合。 **同时启用搜索和抓取。** 不予采纳：默认启用 `web_fetch` 会允许模型自行选择任意 URL，执行匿名出站 HTTP(S) 抓取。搜索负责发现信息；接受更广泛抓取范围的部署可以在覆盖层中选择启用 `dsh-web-fetch-local`，并将 `dsh-tool-web` 的 `fetch` 选项设为 `true`。 ## 后果 -Web／无头模型请求在原生模式下只会携带 `web_search` schema，以及仅用于搜索的提示词指引；Code Mode 通过 `run_code` 公开相同的搜索能力。该提示词要求模型使用返回的 snippet，且绝不会向模型提及已禁用的 `web_fetch` 工具。搜索会增加一次完整的辅助模型调用，并可能多次使用原生服务器工具；发起会话的日志仍可精确重建其不含密钥的请求。默认配置会提供搜索结果 snippet 与来源元数据，但不支持任意页面抓取；需要抓取完整页面的部署必须自行选择启用抓取。Web 快照通道会启动已交付配置树，使用本地 Messages fixture（测试前置数据），经由真实 DeepSeek 提供方驱动一次回放的 `web_search` 调用，断言持久化的辅助请求与结构化结果，并固定最终浏览器呈现。真实组合冒烟测试固定了不提供 `web_fetch` 这一事实；提供方测试固定缺失、已存储及已轮换凭据的行为，以及字面值与环境变量的兼容性。 +每个已交付界面的原生模型请求都只会携带 `web_search` schema，以及仅用于搜索的提示词指引；Web／无头 Code Mode 通过 `run_code` 公开相同的搜索能力。该提示词要求模型使用返回的 snippet，且绝不会向模型提及已禁用的 `web_fetch` 工具。搜索会增加一次完整的辅助模型调用，并可能多次使用原生服务器工具；发起会话的日志仍可精确重建其不含密钥的请求。默认配置会提供搜索结果 snippet 与来源元数据，但不支持任意页面抓取；需要抓取完整页面的部署必须自行选择启用抓取。Web 快照通道会启动已交付配置树，使用本地 Messages fixture（测试前置数据），经由真实 DeepSeek 提供方驱动一次回放的 `web_search` 调用，断言持久化的辅助请求与结构化结果，并固定最终浏览器呈现。TUI/Web 组合冒烟测试固定了共享的 `web_search` 清单及不提供 `web_fetch` 这一事实；提供方测试固定缺失、已存储及已轮换凭据的行为，以及字面值与环境变量的兼容性。 diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml index f6cc14538d..86f2224878 100644 --- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml @@ -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 -2026-06-20-public-agent-stop-surface.md: e22c4389df18f3c9ca96763fc097eabefcc5b761 -2026-06-20-public-agent-stop-surface.zh.md: e2647b498a8c906579b4fd2b50f94d1c326fe784 +# pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md +2026-06-20-public-agent-stop-surface.md: 7e8f6f691c999fd78c9b4133eaeac40f2d1c1ba9 +2026-06-20-public-agent-stop-surface.zh.md: 041d666eb817450add2d7a1746f7f5b81223568a diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md index e22c4389df..7e8f6f691c 100644 --- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md +++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md @@ -8,15 +8,15 @@ English | [中文](2026-06-20-public-agent-stop-surface.zh.md) ## Problem -The public `Agent` handle exposed two overlapping ways to stop in-flight work: step-only `abort()` and queue-aware `cancel()`. The former preserved queued input while the latter clears queued and steering work and aborts the active turn. In production, ACP uses `cancel()` for `session/cancel`, while lifecycle owners tear down agents through `AgentHandle.dispose()`. No production caller needs a bare step-only abort. +The public `Agent` handle exposed two overlapping ways to stop in-flight work: step-only `abort()` and queue-aware `cancel()`. The former preserved queued input while the latter originally only exposed its broad default, which clears queued and steering work while aborting the active turn. `cancel(cause, { keepInbox: true })` now covers the production Web stop policy without exposing the private turn holder; ACP retains broad cancellation, while lifecycle owners tear down agents through `AgentHandle.dispose()`. No production caller needs a bare step-only abort. -The behavioral distinction is real, but no shipping code needs the narrower operation. AgentLoop instead owns one private cancellation holder for the whole turn. `cancel(cause?)` carries a typed `user` or `parent` cause, defaults to `user`, and drops pending input; disposal remains a separate lifecycle interruption. The complete ownership and propagation contract lives in the [explicit turn cancellation RFC](../architecture/2026-07-16-explicit-turn-cancellation.md). +The behavioral distinction is real, but no shipping code needs a separate narrower verb. AgentLoop owns one private cancellation holder for the whole turn. `cancel(cause, options?)` carries an explicit typed `user` or `parent` cause; its broad default drops pending input, while `keepInbox` preserves pending work for later turns. Disposal remains a separate lifecycle interruption. The complete ownership and propagation contract lives in the [explicit turn cancellation RFC](../architecture/2026-07-16-explicit-turn-cancellation.md). -The extra surface area made the loop carry a public verb that is mostly a teardown internal: `abort()` had to be documented as distinct from queue-aware cancellation even though a UI cancellation almost always wants the broader operation. +The extra surface area made the loop carry a public verb that was mostly a teardown internal. An options-bearing `cancel()` expresses caller policy without exposing a second holder-shaped operation. ## Decision -`cancel()` is the only public *stop* primitive on `Agent`. Lifecycle owners use `AgentHandle.dispose()` to stop and unregister an agent; non-owners use `cancel()` to abandon current and queued work. The implementation keeps a private turn cancellation holder, but it is not part of the plugin-facing `Agent` contract. +`cancel()` is the only public *stop* primitive on `Agent`. Lifecycle owners use `AgentHandle.dispose()` to stop and unregister an agent; non-owners use broad `cancel()` to abandon current and queued work or `keepInbox` to abort the active turn while retaining pending work. The implementation keeps a private turn cancellation holder, but it is not part of the plugin-facing `Agent` contract. The [Web stop decision](../bug-fix/2026-07-31-web-stop-preserves-queue.md) is the production `keepInbox` consumer. `whenIdle()` is **retained** as the public quiescence-observation primitive (resolve once the agent settles out of `running`, resolve immediately when already idle, await the loop exit when disposed). It is not a stop verb; it is how a non-owner observes the stop *completing* without disposing the agent. Its live consumers are ACP and agent tests that await settlement through this public seam (`packages/acp/acp/tests`, `packages/core/agent-loop/tests`); the production ACP bridge owns its agents and tears them down through `AgentHandle.dispose()`, so `packages/acp/acp/src` itself has no `whenIdle()` call. @@ -28,11 +28,11 @@ Public `abort()` is absent, and the disposer remains async and waits for the loo ## Verification -`Agent` exposes no public `abort()` while `cancel()`, `whenIdle()`, and `steer()` remain; ACP cancellation calls `cancel()`; teardown awaits quiescence through handle disposal, with `whenIdle()` resolving on quiescence for non-owner observers; and the suites cover cancellation and disposal as the two supported stop paths. +`Agent` exposes no public `abort()` while `cancel()`, `whenIdle()`, and `steer()` remain; ACP cancellation calls broad `cancel()`, Web stop calls `cancel(..., { keepInbox: true })`, and teardown awaits quiescence through handle disposal. `whenIdle()` resolves on quiescence for non-owner observers, and the suites cover cancellation and disposal as the two supported stop paths. ## Consequences -A future plugin cannot abort only the current model/tool step while preserving queued prompts through the public interface. If that use case becomes real, it should return with a named consumer and a narrower contract. Today it is latent generality that keeps a private loop mechanic public. +A plugin can abort the active turn while preserving queued prompts through `keepInbox`, but it cannot abort only one model/tool step while leaving that turn running. A step-only use case would need a named consumer and a narrower contract; exposing the private loop mechanic remains unjustified. ## Related diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md index e2647b498a..041d666eb8 100644 --- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md +++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md @@ -8,15 +8,15 @@ Status: implemented ## 问题 -公共 `Agent` handle 暴露了两种相互重叠的在途工作停止方式：仅针对步骤的 `abort()` 和感知队列的 `cancel()`。前者保留已排队输入，后者则清除已排队和 steering（中途引导）工作，并中止活动轮次。在生产中，ACP（Agent Client Protocol）对 `session/cancel` 使用 `cancel()`，生命周期拥有者则通过 `AgentHandle.dispose()` 拆除 agent（智能体）。没有生产调用方需要一个裸的、仅针对步骤的 abort。 +公共 `Agent` handle 暴露了两种相互重叠的在途工作停止方式：仅针对步骤的 `abort()` 和感知队列的 `cancel()`。前者保留已排队输入，后者原本只暴露广义默认行为，该行为会清除已排队和 steering（中途引导）工作，同时中止活动轮次。`cancel(cause, { keepInbox: true })` 现在无需暴露私有轮次 holder 即可覆盖生产环境的 Web 停止策略；ACP 保留广义取消，生命周期拥有者则通过 `AgentHandle.dispose()` 拆除 agent（智能体）。没有生产调用方需要一个裸的、仅针对步骤的 abort。 -行为差异确实存在，但已发布代码不需要较窄的操作。AgentLoop 改为为整个轮次拥有一个私有取消 holder。`cancel(cause?)` 携带类型化的 `user` 或 `parent` 原因，默认为 `user`，并丢弃待处理输入；释放仍是单独的生命周期中断。完整的归属与传播契约位于[显式轮次取消 Agent Note（agent 决策记录）](../architecture/2026-07-16-explicit-turn-cancellation.md)。 +行为差异确实存在，但已发布代码不需要独立的更窄动词。AgentLoop 为整个轮次拥有一个私有取消 holder。`cancel(cause, options?)` 携带显式且类型化的 `user` 或 `parent` 原因；其广义默认行为丢弃待处理输入，`keepInbox` 则为后续轮次保留待处理工作。资源释放仍是单独的生命周期中断。完整的归属与传播契约位于[显式轮次取消 Agent Note（agent 决策记录）](../architecture/2026-07-16-explicit-turn-cancellation.md)。 -多余的公开接口使得循环不得不承载一个本质上属于内部拆卸的公开动词：`abort()` 必须被文档描述为有别于队列感知的取消，尽管 UI 取消几乎总是需要更广泛的操作。 +多余的公开接口使循环承载了一个本质上属于内部拆卸的公开动词。带选项的 `cancel()` 可以表达调用方策略，而无需暴露第二个 holder 形态的操作。 ## 决策 -`cancel()` 是 `Agent` 上唯一的公共*停止*原语。生命周期拥有者使用 `AgentHandle.dispose()` 停止并注销 agent；非拥有者使用 `cancel()` 放弃当前和已排队工作。实现保留一个私有轮次取消 holder，但它不属于面向插件的 `Agent` 契约。 +`cancel()` 是 `Agent` 上唯一的公共*停止*原语。生命周期拥有者使用 `AgentHandle.dispose()` 停止并注销 agent；非拥有者使用广义 `cancel()` 放弃当前和已排队工作，或使用 `keepInbox` 中止活动轮次并保留待处理工作。实现保留一个私有轮次取消 holder，但它不属于面向插件的 `Agent` 契约。[Web 停止决策](../bug-fix/2026-07-31-web-stop-preserves-queue.md)是生产环境中的 `keepInbox` 消费方。 `whenIdle()` **保留**为公开的完全停稳观测原语（agent 从 `running` 状态稳定后 resolve，已处于 idle 时立即 resolve，dispose 后等待循环退出）。它不是停止动词；它是非所有者在不 dispose agent 的前提下观测停止*完成*的方式。它的活跃消费方是 ACP 和通过此公开 seam 等待结算的 agent 测试（`packages/acp/acp/tests`、`packages/core/agent-loop/tests`）；生产环境的 ACP 桥接层拥有其 agent 并通过 `AgentHandle.dispose()` 销毁它们，因此 `packages/acp/acp/src` 本身没有 `whenIdle()` 调用。 @@ -28,11 +28,11 @@ Status: implemented ## 验证 -`Agent` 不再暴露公开的 `abort()`，而 `cancel()`、`whenIdle()` 和 `steer()` 保留；ACP 取消调用 `cancel()`；拆卸通过 handle disposal 等待完全停稳，`whenIdle()` 在完全停稳时为非所有者观测者 resolve；测试套件覆盖取消和 disposal 作为两条受支持的停止路径。 +`Agent` 不再暴露公开的 `abort()`，而 `cancel()`、`whenIdle()` 和 `steer()` 保留；ACP 取消调用广义 `cancel()`，Web 停止调用 `cancel(..., { keepInbox: true })`，拆卸则通过 handle disposal 等待完全停稳。`whenIdle()` 在完全停稳时为非所有者观测者 resolve；测试套件覆盖取消和资源释放这两条受支持的停止路径。 ## 后果 -未来的插件无法通过公开接口仅中止当前模型/工具步骤而保留队列中的提示词。如果该用例变为现实需求，它应当带着一个具名消费方和更窄的契约回归。目前它是将私有循环机制保持公开的潜在泛化。 +插件可以通过 `keepInbox` 在保留已排队提示词的同时中止活动轮次，但不能只中止某一个模型／工具步骤而让该轮次继续运行。仅步骤用例需要具名消费方和更窄契约；暴露私有循环机制仍缺乏正当理由。 ## 相关 diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml index 9031dc8eb0..75e8ca8d37 100644 --- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml @@ -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/simplification/2026-07-28-remove-synthetic-log-only-turns.md -2026-07-28-remove-synthetic-log-only-turns.md: af4da00f4fe1d7aebff845cd55053bb5b807c979 -2026-07-28-remove-synthetic-log-only-turns.zh.md: 9d72781d6b7cf396a830790d108f4ff25adc816a +2026-07-28-remove-synthetic-log-only-turns.md: fc76667924ec839301aad993efd996112c9a6b09 +2026-07-28-remove-synthetic-log-only-turns.zh.md: 7520c33e2219c5fe7ab7d8da6312247e42cc69b0 diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md index af4da00f4f..fc76667924 100644 --- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md +++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md @@ -18,11 +18,11 @@ The generic seam also duplicated domain policy. Its marker map said which plugin Core session invariants continue to enforce core-owned execution relations: turn and step numbering, enclosure of steering, assistant, tool, todo, and request-header events, and same-step tool call/result pairing. Core permits merge-extensible events between turns because only their declaring plugin knows whether they are execution-scoped or standalone. Plugin invariant companions remain responsible for their own event relations. -The title service appends `session/title` directly after its existing service, revision, cancellation, and live-session checks. The bundled model helper appends its literal `session/title-llm-request` record before dispatch. Persistence observes both through the eager `session/event` path and drains them at ordinary checkpoints and lifecycle teardown; neither append forces a flush merely because it is between turns. A fallback, auxiliary request record, or accepted provider title may therefore appear after `turn/end` and before the next `turn/start`. +The title service appends `session/title` directly after its existing service, revision, cancellation, and live-session checks. The bundled model helper appends its literal `session/title-llm-request` record before dispatch. Persistence observes both through the eager `session/event` path and drains them at ordinary checkpoints and lifecycle teardown; neither append forces a flush merely because it is between turns. A fallback, auxiliary request record, or accepted provider title may therefore appear after `turn/end` and before the next `turn/start`. Manual compaction uses the same between-turn capability for a `compact/* { turn: null }` bracket, but explicitly flushes the closed attempt because `/compact` promises durability before releasing queued prompt admission. A session fork may end at any stable event position outside an open turn, not only at `turn/end`. This preserves standalone title and context records in a default fork while still rejecting a prefix cut through active execution. -The historical [universal turn-enclosure decision](../../archived/architecture/2026-06-15-turn-enclosure-invariant.md) remains useful only as the reason the synthetic mechanism was introduced. The [context-injection decision](../architecture/2026-07-24-separate-context-injection-from-turn-execution.md) established the current meaning: one turn represents one model-loop execution. +The historical [universal turn-enclosure decision](../../archived/architecture/2026-06-15-turn-enclosure-invariant.md) remains useful only as the reason the synthetic mechanism was introduced. The [context-injection decision](../architecture/2026-07-24-separate-context-injection-from-turn-execution.md) established the current meaning: one turn represents one model-loop execution. The [queued manual compaction decision](../feature/2026-07-30-queued-manual-compaction.md) applies that rule to a durable multi-event bracket and owns its marker and admission semantics. ## Alternatives considered @@ -36,8 +36,8 @@ The historical [universal turn-enclosure decision](../../archived/architecture/2 ## Verification -Core invariant tests accept an unknown plugin event between turns while continuing to reject built-in execution events there. Hook, compaction, plan-mode, Code Mode dispatch, and approval invariant companions replay existing logs and reject the same execution-scoped events before commit when no turn is open. Session-title service tests pin one direct fallback event under concurrent refresh, detached-session rejection, and newest-revision acceptance. JSONL and SQLite round trips preserve a title appended after `turn/end` through the persistence lifecycle drain, and fork tests retain a standalone log-only tail while rejecting boundaries inside an open turn. A keyless assembled ACP snapshot delays the model-backed title until after `turn/end` and pins one standalone provider title with no synthetic turn. Generated API and type-equivalence catalogs contain no removed symbol. +Core invariant tests accept an unknown plugin event between turns while continuing to reject built-in execution events there. Hook, plan-mode, Code Mode dispatch, and approval invariant companions reject their execution-scoped events when no turn is open; the compaction companion separately accepts a balanced `turn: null` manual bracket between turns and requires numeric owners to match an open turn. Session-title service tests pin one direct fallback event under concurrent refresh, detached-session rejection, and newest-revision acceptance. JSONL and SQLite round trips preserve a title appended after `turn/end` through the persistence lifecycle drain, and fork tests retain a standalone log-only tail while rejecting boundaries inside an open turn. A keyless assembled ACP snapshot delays the model-backed title until after `turn/end` and pins one standalone provider title with no synthetic turn. Generated API and type-equivalence catalogs contain no removed symbol. ## Consequences -Turn counts and outcomes again describe model-loop executions only. Standalone events consume session seqs, start eager persistence like every other append, and require owners to request an explicit durability barrier only when their operation promises one. Generic plugin mistakes no longer fail under a core default enclosure rule, so each plugin that needs an execution relation must state and test that relation itself. The title capability keeps revision ordering and lifecycle persistence with less core state, no duplicate type seam, and no turn-number collision. +Turn counts and outcomes again describe model-loop executions only. Standalone events and manual compaction brackets consume session seqs without consuming a turn number, start eager persistence like every other append, and require owners to request an explicit durability barrier only when their operation promises one. Generic plugin mistakes no longer fail under a core default enclosure rule, so each plugin that needs an execution relation must state and test that relation itself. The title capability keeps revision ordering and lifecycle persistence with less core state, and manual compaction gains durable control with no synthetic-turn or turn-number collision. diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md index 9d72781d6b..7520c33e22 100644 --- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md +++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md @@ -18,11 +18,11 @@ Status: implemented 核心会话不变量继续强制核心所属的执行关系：轮次与步骤编号、steering、助手、工具、待办和请求头事件的封闭，以及同一步骤内的工具调用／结果配对。核心允许可合并扩展事件位于轮次之间，因为只有声明它们的插件知道这些事件受执行作用域约束，还是可以独立存在。插件的不变量配套组件仍负责其自身的事件关系。 -标题服务会在完成既有的服务状态、修订、取消和实时会话检查后，直接追加 `session/title`。随附模型辅助函数会在发起调用前追加其字面量 `session/title-llm-request` 记录。持久化通过尽快处理的 `session/event` 路径观察两者，并在常规检查点与生命周期 teardown 时排空；二者都不会仅因为位于轮次之间就强制 flush。因此，回退标题、辅助请求记录或已接受的提供方标题可以出现在 `turn/end` 之后、下一个 `turn/start` 之前。 +标题服务会在完成既有的服务状态、修订、取消和实时会话检查后，直接追加 `session/title`。随附模型辅助函数会在发起调用前追加其字面量 `session/title-llm-request` 记录。持久化通过尽快处理的 `session/event` 路径观察两者，并在常规检查点与生命周期 teardown 时排空；二者都不会仅因为位于轮次之间就强制 flush。因此，回退标题、辅助请求记录或已接受的提供方标题可以出现在 `turn/end` 之后、下一个 `turn/start` 之前。手动压缩（compaction）利用同一项轮次间能力记录 `compact/* { turn: null }` 标记对，但会显式 flush 已闭合的尝试，因为 `/compact` 承诺在释放排队提示词接纳预留前完成持久化。 会话 fork 可以结束于开放轮次之外的任意稳定事件位置，而不限于 `turn/end`。这样，默认 fork 会保留独立标题和上下文记录，同时仍拒绝在活跃执行过程中截断前缀。 -历史上的[通用轮次封闭决策](../../archived/architecture/2026-06-15-turn-enclosure-invariant.md)如今只适合用于解释为何曾引入合成机制。[上下文注入决策](../architecture/2026-07-24-separate-context-injection-from-turn-execution.md)确立了当前语义：一个轮次表示一次模型循环执行。 +历史上的[通用轮次封闭决策](../../archived/architecture/2026-06-15-turn-enclosure-invariant.md)如今只适合用于解释为何曾引入合成机制。[上下文注入决策](../architecture/2026-07-24-separate-context-injection-from-turn-execution.md)确立了当前语义：一个轮次表示一次模型循环执行。[排队手动压缩决策](../feature/2026-07-30-queued-manual-compaction.md)将该规则应用于持久多事件标记对，并拥有其标记与接纳语义。 ## 曾考虑的替代方案 @@ -36,8 +36,8 @@ Status: implemented ## 验证 -核心不变量测试会接受轮次之间的未知插件事件，同时继续拒绝位于该处的内置执行事件。钩子、压缩（compaction）、plan-mode、Code Mode 分发和审批的不变量配套组件会回放既有日志，并在没有开放轮次时，于提交前拒绝相同的执行作用域事件。会话标题服务测试会在并发刷新、会话脱离拒绝和最新修订接受场景下，固定一个直接追加的回退事件。JSONL 和 SQLite 往返测试会通过持久化生命周期排空保留追加在 `turn/end` 之后的标题；fork 测试会保留独立纯日志尾部，同时拒绝位于开放轮次内的边界。一个无密钥、经完整组装的 ACP（Agent Client Protocol）快照会将模型生成的标题延迟到 `turn/end` 之后，并固定一个不含合成轮次的独立提供方标题。生成的 API 和类型等价性目录不含任何已移除符号。 +核心不变量测试会接受轮次之间的未知插件事件，同时继续拒绝位于该处的内置执行事件。钩子、plan-mode、Code Mode 分发和审批的不变量配套组件会在没有开放轮次时拒绝其执行作用域事件；压缩配套组件则另外接受轮次之间平衡的 `turn: null` 手动标记对，并要求数字 owner 匹配一个开放轮次。会话标题服务测试会在并发刷新、会话脱离拒绝和最新修订接受场景下，固定一个直接追加的回退事件。JSONL 和 SQLite 往返测试会通过持久化生命周期排空保留追加在 `turn/end` 之后的标题；fork 测试会保留独立纯日志尾部，同时拒绝位于开放轮次内的边界。一个无密钥、经完整组装的 ACP（Agent Client Protocol）快照会将模型生成的标题延迟到 `turn/end` 之后，并固定一个不含合成轮次的独立提供方标题。生成的 API 和类型等价性目录不含任何已移除符号。 ## 后果 -轮次计数和结果重新只描述模型循环执行。独立事件会占用会话 seq，像其他追加一样启动尽快持久化，并且仅当操作承诺持久性时，才要求事件所有方请求显式持久性屏障。通用插件错误不再因核心默认的封闭规则而失败，因此每个需要执行关系的插件都必须自行声明并测试该关系。标题功能保留修订排序和生命周期持久化，同时减少了核心状态，不再重复类型 seam，并消除了轮次编号冲突。 +轮次计数和结果重新只描述模型循环执行。独立事件和手动压缩标记对会占用会话 seq，但不占用轮次编号；它们像其他追加一样启动尽快持久化，并且仅当操作承诺持久性时，才要求事件所有方请求显式持久性屏障。通用插件错误不再因核心默认的封闭规则而失败，因此每个需要执行关系的插件都必须自行声明并测试该关系。标题功能保留修订排序和生命周期持久化，同时减少了核心状态；手动压缩则获得持久控制，不产生合成轮次或轮次编号冲突。 diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml index e4491b6c7b..1c0cc5644d 100644 --- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml @@ -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/simplification/2026-07-31-one-route-to-add-a-workspace.md -2026-07-31-one-route-to-add-a-workspace.md: 0d3f4096b11ec2d0bd1339268bfb8567380d3e1a -2026-07-31-one-route-to-add-a-workspace.zh.md: b9b25b15680cb54ae980e217e6218a91cd1e366a +2026-07-31-one-route-to-add-a-workspace.md: 5d002265b5eb1178bb1dbc7bd17f8b364d9b9856 +2026-07-31-one-route-to-add-a-workspace.zh.md: 0a59d3a505eb921b4ec980abaefedfcad8a3c294 diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md index 0d3f4096b1..5d002265b5 100644 --- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md +++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md @@ -31,7 +31,7 @@ The host's `workspace.create` still accepts `{ name }`, and `dsh web --workspace ## Testing -`connectFreshWorkspace` — the helper every web e2e scenario boots through — stages `/workspace` and adopts it through the dialog's path editor, so the produced session cwd stays identical to what create-by-name produced and scenario goldens stay valid. Staging rather than creating in-dialog keeps the helper idempotent across the repeated connects a scenario may make (a second create of the same folder fails, and the create dialog holds the flow open on that failure). Creating a folder from inside the chooser — the other half of the same route — is covered by `workspace-management.e2e.ts`, which owns the focused coverage: two workspaces added on folders the dialog creates, a deleted title reused on a different directory, and the browser-dialog aria golden. +`connectFreshWorkspace` — the helper every web e2e scenario boots through — stages `/workspace` and adopts it through the dialog's path editor, so the produced session cwd stays identical to what create-by-name produced and scenario goldens stay valid. Staging rather than creating in-dialog keeps the helper idempotent across the repeated connects a scenario may make (a second create of the same folder fails, and the create dialog holds the flow open on that failure). Creating a folder from inside the chooser — the other half of the same route — is covered by `workspace-management.e2e.ts`, which owns the focused coverage: two workspaces added on folders the dialog creates, distinct same-basename directories adopted independently, a deleted title reused on a different directory, and the browser-dialog aria golden. `smoke-real.e2e.ts` is the one scenario booting the unpatched shipped tree, where the `-auto` row resolves per host; it now pins `-browse` through a `--config` overlay so the developer's display environment cannot decide whether the picker is drivable at all. diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md index b9b25b1568..0a59d3a505 100644 --- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md +++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md @@ -31,7 +31,7 @@ Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` ## Testing -`connectFreshWorkspace`——所有 web e2e 场景启动时都会走的辅助函数——会预先备好 `/workspace`，再经对话框的路径编辑器接纳它，因此产出的会话 cwd 与按名称创建时完全一致，场景 golden 保持有效。选择预先备好而不是在对话框内新建，是为了让该辅助函数在一个场景可能发生的多次连接之间保持幂等（第二次创建同名文件夹会失败，而创建对话框会在失败时把流程停在原地）。在选择器内新建文件夹——同一条路径的另一半——由 `workspace-management.e2e.ts` 覆盖，它承担针对性覆盖：在对话框自己创建的文件夹上添加两个 workspace、在另一个目录上复用已删除的标题、以及浏览对话框的 aria golden。 +`connectFreshWorkspace`——所有 web e2e 场景启动时都会走的辅助函数——会预先备好 `/workspace`，再经对话框的路径编辑器接纳它，因此产出的会话 cwd 与按名称创建时完全一致，场景 golden 保持有效。选择预先备好而不是在对话框内新建，是为了让该辅助函数在一个场景可能发生的多次连接之间保持幂等（第二次创建同名文件夹会失败，而创建对话框会在失败时把流程停在原地）。在选择器内新建文件夹——同一条路径的另一半——由 `workspace-management.e2e.ts` 覆盖，它承担针对性覆盖：在对话框自己创建的文件夹上添加两个 workspace、接纳 basename 相同的不同目录并保持彼此独立、在另一个目录上复用已删除的标题、以及浏览对话框的 aria golden。 `smoke-real.e2e.ts` 是唯一启动未打补丁的出厂配置树的场景，其中 `-auto` 行会按宿主机解析；它现在通过 `--config` overlay 钉死 `-browse`，使开发机的显示环境无法决定选择器是否可被驱动。 diff --git a/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.i18n.yaml new file mode 100644 index 0000000000..2059841653 --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.i18n.yaml @@ -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/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md +2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md: 6f397668106a6c74f327fc799327752c54824d8c +2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md: f127bd57006747465a1ece87406f5f97086b6a34 diff --git a/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md b/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md new file mode 100644 index 0000000000..6f39766810 --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md @@ -0,0 +1,38 @@ +# Agent Note: Web UI drops steer entry and interjection chrome + +Status: implemented + +English | [中文](2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md) + +## Problem + +Mid-turn steering is a host/agent-loop capability (`mode:'steer'`, durable `steering/message`). The Web product already locked the composer while a turn runs and never shipped a queue/steer menu, yet the client still threaded `'queue' | 'steer'` through the input machine, `conversation.send`, and locale keys, and rendered consumed steering as a badged 「插话」/「Interjection」 bubble. That left a half-built UI surface: an unused submit mode, a product label for a gesture users cannot perform, and e2e goldens that pinned chrome the product does not own. + +## Decision + +Keep host and runtime steering intact. Remove only the Web UI entry and chrome: + +- `InputMachine` / `SessionInput` / `InputActions.submit` / hub `defaultSink` are queue-only; they always call `session.prompt(..., 'queue')`. +- `ConversationService.send(text)` drops its mode argument and always queues. +- `MessageItem`'s `steering` arm still folds durable `steering/message` content into a plain right-aligned bubble (no badge, no user IconActions) so external/host steers stay visible on replay. +- Delete `message.steering` locale strings and the unused badge CSS. +- The web steering e2e still POSTs `mode:'steer'` over `/api/session.prompt` and asserts durable + model-visible obedience; it no longer expects interjection chrome. Update [web input machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) fact lines to match. + +## Alternatives considered + +**Delete host steering entirely.** Out of scope; the user asked only for Web UI display and entry. Agent-loop drain, session events, and the wire mode remain load-bearing for ACP/TUI/automation. + +**Hide `steering/message` from the transcript.** Would lie on replay when an external client steers; rejected in favor of a plain bubble. + +**Keep the mode parameter but only ever pass `'queue'`.** Leaves dead API surface and tests that invent `'steer'` paths the composer cannot reach. + +## Consequences + +- Web users cannot steer from the composer or `ctx.conversation.send`; stop/cancel and Queue remain the only mid-turn controls. +- Host-wire and non-Web clients can still steer; the Web client shows those messages without labeling them as interjections. +- Reintroducing a dedicated steer UI would need a new product decision; do not revive the mode union or badge without one. + +## Testing + +- `packages/client/ui-conversation` unit/jsdom coverage: input machine enter/sink, ConversationService routing, MessageItem steering arm (no 「插话」), InputBar submit. +- `apps/web/tests/steering.e2e.ts` keyless replay plus updated `settled.expected.md` (steer text without badge). diff --git a/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md b/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md new file mode 100644 index 0000000000..f127bd5700 --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md @@ -0,0 +1,38 @@ +# Agent Note: Web UI 去掉 steer 入口与插话 chrome + +Status: implemented + +[English](2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md) | 中文 + +## 问题 + +中途 steering 是 host／agent-loop 能力（`mode:'steer'`、持久 `steering/message`）。Web 产品已在 turn 运行中锁定 composer，且从未交付排队／steer 菜单，但客户端仍把 `'queue' | 'steer'` 穿进 input machine、`conversation.send` 与 locale 键，并把已消费的 steering 渲染成带「插话」／「Interjection」徽章的气泡。这留下半成品 UI：用不到的提交 mode、用户做不到的手势却有产品文案，以及把产品并不拥有的 chrome 钉死在 e2e golden 上。 + +## 决策 + +保留 host 与 runtime 的 steering。只去掉 Web UI 入口与 chrome： + +- `InputMachine`／`SessionInput`／`InputActions.submit`／hub `defaultSink` 仅 queue；始终调用 `session.prompt(..., 'queue')`。 +- `ConversationService.send(text)` 去掉 mode 参数，始终排队。 +- `MessageItem` 的 `steering` 分支仍把持久 `steering/message` 内容折成右对齐普通气泡（无徽章、无用户 IconActions），以便外部／host steer 在回放时仍可见。 +- 删除 `message.steering` locale 字符串与未使用的徽章 CSS。 +- web steering e2e 仍通过 `/api/session.prompt` POST `mode:'steer'`，并断言持久化与模型可见服从；不再期望插话 chrome。同步更新 [web input machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) 中的事实行。 + +## 曾考虑的替代方案 + +**整段删除 host steering。** 超出范围；用户只要求清 Web UI 展示与入口。agent-loop 排空、session 事件与线缆 mode 对 ACP／TUI／自动化仍是承重能力。 + +**在 transcript 中隐藏 `steering/message`。** 外部客户端 steer 时回放会撒谎；改为普通气泡。 + +**保留 mode 参数但永远只传 `'queue'`。** 留下死 API 面与只会虚构 composer 到不了的 `'steer'` 路径的测试。 + +## 后果 + +- Web 用户无法从 composer 或 `ctx.conversation.send` steer；中途控制只剩停止／取消与 Queue。 +- Host 线缆与非 Web 客户端仍可 steer；Web 客户端展示这些消息时不再标成插话。 +- 若要重新引入专用 steer UI，需要新的产品决策；没有决策就不要复活 mode 联合类型或徽章。 + +## 测试 + +- `packages/client/ui-conversation` unit／jsdom 覆盖：input machine enter／sink、ConversationService 路由、MessageItem steering 分支（无「插话」）、InputBar submit。 +- `apps/web/tests/steering.e2e.ts` 无密钥回放，以及更新后的 `settled.expected.md`（有 steer 正文、无徽章）。 diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml index 91d77fb803..b219e6245f 100644 --- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml @@ -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/testing/2026-07-24-web-gui-browser-e2e-lane.md -2026-07-24-web-gui-browser-e2e-lane.md: cdb7de52c50733d6650202ee2117916319940738 -2026-07-24-web-gui-browser-e2e-lane.zh.md: b850acf026502d054a9d8b2168f0b4f47f58f39b +2026-07-24-web-gui-browser-e2e-lane.md: f05fc7268cfb613d0af8240bbb65cb154252a620 +2026-07-24-web-gui-browser-e2e-lane.zh.md: 3fd3805053a570a32e63601d7b039db41365309c diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md index cdb7de52c5..f05fc7268c 100644 --- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md +++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md @@ -76,13 +76,12 @@ Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot ## Testing -`pnpm run test:web` builds and runs the lane keylessly; `test:web:built` runs it against existing build artifacts. `DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/` records a prompting scenario against the live model, and `DSH_SNAPSHOT=refresh pnpm run test:web` rewrites aria goldens keylessly. CI explicitly selects replay mode. The scaffold hermeticity scenario populates distinct entries in all three ambient skill roots and requires none to enter the assembled catalog. `dsh-llm-replay` unit coverage pins pacing, cancellation, consumption diagnostics, sidecar validation, indexed replacement, and the single append position. +`pnpm run test:web` builds and runs the lane keylessly; `test:web:built` runs it against existing build artifacts. `DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/` records a prompting scenario against the live model, and `DSH_SNAPSHOT=refresh pnpm run test:web` rewrites aria goldens keylessly. CI explicitly selects replay mode. The live-interactions AUTH scenario pins a non-retryable terminal failure as an inline Chat status carrying the display-safe message and code, verifies that provider-echoed credential fragments stay absent from both Chat and Trajectory, and covers composer recovery plus the `turn/end` error. The scaffold hermeticity scenario populates distinct entries in all three ambient skill roots and requires none to enter the assembled catalog. `dsh-llm-replay` unit coverage pins pacing, cancellation, consumption diagnostics, sidecar validation, indexed replacement, and the single append position. ## Deferred - **Web header-class pin**: web fixtures tokenize `{{system}}`/`{{tools}}` everywhere and no scenario pins the web composition's prompt/tool schemas (`TODO(web-header-pin)` — the scaffold `recordFixture` JSDoc marks it). Following the TUI scrub-everywhere precedent; revisit when the web assembly's header diverges from the repl composition it mirrors. - **Follow-up-prompt-after-resume scenario**: the history/live stitch path over the real wire; add as its own scenario when that code changes or regresses. -- **Web error surface**: the client consumes no `agent/error` frames and a pre-chunk failure freezes no partial, so a non-retryable provider failure renders no error copy — the user sees the send simply stop. The AUTH scenario pins the current contract (no crash, composer recovers, turn logged `error`) and `FIXME(web-error-surface)` marks where visible error text gets asserted once the UI grows an error rendering. - **Composer steering gesture**: the input locks while running (stop-or-wait), so the steering scenario steers over the wire from the page; `TODO(web-steer-composer)` upgrades the drive step to a real composer gesture when the product grows one. - **Drag session reorder**: `workspace.insertSessionBefore` has no browser scenario; it needs two sessions materialized in one workspace plus synthesized HTML5 drag events. Add it when that surface changes or regresses. The inert session Rename/Fork/Delete and workspace Delete menu rows get scenarios when they gain behavior. diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md index b850acf026..3fd3805053 100644 --- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md +++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md @@ -76,13 +76,12 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu ## Testing -`pnpm run test:web` 构建并无密钥运行该车道；`test:web:built` 基于现有构建产物运行。`DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/` 对真实模型录制一个发起提示的场景，`DSH_SNAPSHOT=refresh pnpm run test:web` 则无密钥重写 aria 预期输出。CI 显式选择回放模式。scaffold 环境隔离场景会在全部 3 个环境 skill 根目录中分别填入不同条目，并要求这些条目都不得进入组装后的目录。`dsh-llm-replay` 单元覆盖率钉住节奏控制、取消、消费诊断、sidecar 校验、按索引替换与唯一的追加位置。 +`pnpm run test:web` 构建并无密钥运行该车道；`test:web:built` 基于现有构建产物运行。`DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/` 对真实模型录制一个发起提示的场景，`DSH_SNAPSHOT=refresh pnpm run test:web` 则无密钥重写 aria 预期输出。CI 显式选择回放模式。live-interactions AUTH 场景会把不可重试的终态失败钉为 Chat 内联状态，其中携带适合展示的消息与错误码，并验证提供方回显的凭据片段不会出现在 Chat 或 Trajectory 中；该场景同时覆盖输入框恢复与 `turn/end` 错误。scaffold 环境隔离场景会在全部 3 个环境 skill 根目录中分别填入不同条目，并要求这些条目都不得进入组装后的目录。`dsh-llm-replay` 单元覆盖率钉住节奏控制、取消、消费诊断、sidecar 校验、按索引替换与唯一的追加位置。 ## 暂缓 - **Web 头类别钉住**：web fixture 处处 token 化 `{{system}}`/`{{tools}}`，没有场景钉住 web 组合的提示词/工具 schema（`TODO(web-header-pin)`——scaffold 的 `recordFixture` JSDoc 有标记）。沿用 TUI 处处脱敏先例；当 web 组装的请求头与其镜像的 repl 组合进一步分叉时重审。 - **恢复后追问场景**：真实 wire 上的历史/实时缝合路径；当该代码变更或回归时作为独立场景补充。 -- **Web 错误表面**：客户端不消费任何 `agent/error` 帧，分片前的失败也没有可冻结的部分输出，因此不可重试的提供方失败不渲染任何错误文案——用户看到的只是发送就此停住。AUTH 场景钉住当前契约（不崩溃、输入框恢复可用、轮次记录为 `error`），`FIXME(web-error-surface)` 标记了待 UI 长出错误渲染后断言可见错误文本的位置。 - **输入框 steering 手势**：输入在运行期间锁定（只能停止或等待），因此 steering 场景从页面走 wire 做 steer；`TODO(web-steer-composer)` 待产品长出真实的输入框手势后，把驱动步骤升级为该手势。 - **拖拽会话重排**：`workspace.insertSessionBefore` 尚无浏览器场景；它需要在同一个工作区里物化两个会话，并合成 HTML5 拖拽事件。当该表面变更或回归时再补充。无行为的会话 Rename/Fork/Delete 和工作区 Delete 菜单行待获得行为后再补充场景。 diff --git a/README.i18n.yaml b/README.i18n.yaml index b492ed9c37..75f61c7f43 100644 --- a/README.i18n.yaml +++ b/README.i18n.yaml @@ -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 README.md -README.md: b447c9634189353854e8be9d0bf597a8b0c7e371 -README.zh.md: f8bbbc36bc670403c0b9a40977f32f598e77ee46 +README.md: fb956dce51838438fb508db7ea9ebdf9e0b3a50b +README.zh.md: aa80b744465d7d253a54fffeead7262a1fdf69eb diff --git a/README.md b/README.md index b447c96341..fb956dce51 100644 --- a/README.md +++ b/README.md @@ -16,10 +16,12 @@ It uses an architecture where **everything is a plugin**. ## Install -Install `dsh` with one command: +Clone the repository, then run the installer: ```sh -curl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh +git clone +cd deepseek-harness +scripts/install.sh ``` The installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, and prompts for a DeepSeek API key. diff --git a/README.zh.md b/README.zh.md index f8bbbc36bc..aa80b74446 100644 --- a/README.zh.md +++ b/README.zh.md @@ -16,10 +16,12 @@ DeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 ## 安装 -使用一条命令安装 `dsh`： +克隆仓库，然后运行安装器： ```sh -curl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh +git clone +cd deepseek-harness +scripts/install.sh ``` 安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥。 diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml index e7a4161df1..8fa53f8051 100644 --- a/apps/cli/README.i18n.yaml +++ b/apps/cli/README.i18n.yaml @@ -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 apps/cli/README.md -README.md: aee08225febe34bb10ee1001c798db9d7daa8905 -README.zh.md: 8f38fd342a0433ca5f7645f896b81aa5392033ae +README.md: 7ef24dc6290af5aafe3eb53609b090fcbfb83ce8 +README.zh.md: b19d4979351940e925db3b7a616a5c87689770a1 diff --git a/apps/cli/README.md b/apps/cli/README.md index aee08225fe..7ef24dc629 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -3,19 +3,21 @@ English | [中文](README.zh.md) -Argv is parsed once through a [Commander](https://github.com/tj/commander.js) adapter ([`src/args.ts`](src/args.ts)): one program whose default (no subcommand) is the TUI/headless surface (`--config`, `-p`/`--prompt`, `--resume`, `--dump-config`, `--dump-default-config`), whose `meta` subcommand is the same TUI over this checkout, whose `upgrade` subcommand is an option-less guided-session entry, and whose `web` subcommand is the browser UI. `src/bin.ts` switches on the resolved mode and dynamic-imports only that mode's module. `dsh --help` lists every mode and `dsh web --help` renders the web usage, `dsh --version` prints this app's version, and an unknown option or a mistyped `--resume` fails loud (stderr, exit 1) instead of misrouting. Every subcommand that shares no option with the default surface — `upgrade`, `web`, `meta` — rejects a leaked `--config`/`-p`/`--resume`/dump flag rather than running and dropping it. `dsh web`'s `--host`/`--port` are unvalidated pass-through overrides: the `dsh-host-webserver` schema is the single source of both the default (the shipped Web overlay value when a flag is absent) and validity, and rejects a bad value at boot. `--trusted-host` appends named authorities for the /api browser-trust fence; an all-interfaces bind additionally derives the machine's LAN IP literals itself ([`src/app-cli-entry.ts`](src/app-cli-entry.ts)), so the printed LAN URL works without flags. +Argv is parsed once through a [Commander](https://github.com/tj/commander.js) adapter ([`src/args.ts`](src/args.ts)): one program whose default (no subcommand) is the TUI/headless surface (`--config`, `-p`/`--prompt`, `--resume`, `--dump-config`, `--dump-default-config`), whose `experimental-meta` subcommand is the same TUI over this checkout, whose `experimental-upgrade` subcommand is an option-less guided-session entry, and whose `web` subcommand is the browser UI. `src/bin.ts` switches on the resolved mode and dynamic-imports only that mode's module. `dsh --help` lists every mode and `dsh web --help` renders the web usage, `dsh --version` prints this app's version, and an unknown option or a mistyped `--resume` fails loud (stderr, exit 1) instead of misrouting. Every subcommand that shares no option with the default surface — `experimental-upgrade`, `web`, `experimental-meta` — rejects a leaked `--config`/`-p`/`--resume`/dump flag rather than running and dropping it. `dsh web`'s `--host`/`--port` are unvalidated pass-through overrides: the `dsh-host-webserver` schema is the single source of both the default (the shipped Web overlay value when a flag is absent) and validity, and rejects a bad value at boot. `--trusted-host` appends named authorities for the /api browser-trust fence; an all-interfaces bind additionally derives the machine's LAN IP literals itself ([`src/app-cli-entry.ts`](src/app-cli-entry.ts)), so the printed LAN URL works without flags. The TUI surface: - boots `base.cordis.yml` plus `tui.cordis.yml` through [`dsh-app-boot`](../../packages/ui/app-boot/README.md); `--config ` applies a patch-list overlay instead of the personal overlay, while `--config-replace ` boots that file as the complete tree; - resumes a persisted session with `dsh --resume ` and, when the Node host exposes `process.execve`, supplies the TUI's in-place handoff host: after selector preflight and current-session flush, the host disposes the app and replaces the process with a normalized resume invocation; runtimes without process replacement leave the session running and say so. This CLI owns session identity and the exit line rather than the config: it mints or selects the `main` session id and provides it, plus the exact command that reproduces this invocation, on the boot context ([`MAIN_SESSION_ID_KEY`](../../packages/ui/tui/README.md) and `TUI_GOODBYE_MESSAGE_KEY`). No `cordis.yml` key can drop resume, and a missing or unreadable id fails loud instead of creating a fresh session; -- treats the **invoking directory** as the workspace — sessions, relative paths, and workspace instructions resolve from the cwd (`dsh meta` is the sole exception, below); +- treats the **invoking directory** as the workspace — sessions, relative paths, and workspace instructions resolve from the cwd (`dsh experimental-meta` is the sole exception, below); - tells the agent where its own source lives: after boot it adds a prompt section naming this harness checkout, resolved from the launcher's real path so it holds under a PATH symlink and an arbitrary cwd, so the self-referential `cordis` toolset can read and modify it; - applies the personal overlay from `~/.dsh` (see [app-boot's Personal config](../../packages/ui/app-boot/README.md#personal-config)): `config.yaml` patches the booted tree, while `.env` there is the credential provider's own store (never hoisted into the environment, so keys stay rotatable). Environment precedence is ambient > project `.env`. +- presents the [versioned first-run welcome](../../.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.md) through the mounted TUI overlay service when its immutable marker is absent under `DSH_HOME`; only Enter creates that version's marker, while Escape, disposal, or process exit leaves it eligible. The official DeepSeek icon, responsive terminal rasters, all-locale Chinese copy, and notice version are static local owners; the overlay never writes a session event or model context. +- registers bare `/compact`: while the agent is idle, it summarizes useful older history even below automatic pressure, rejects arguments, and reports success only after the standalone replacement bracket is durable. A prompt submitted during compaction keeps its queue identity and starts after that checkpoint; injected context remains visible. -`dsh meta` is that same TUI with this harness checkout as the workspace, so working on dsh itself needs no `cd`. It chdirs to the checkout root — resolved from the launcher's real path, the same root the source-path prompt section names — after the environment is settled, so precedence is unchanged while the session cwd and HMR watch root move together. Meta always starts a fresh session and accepts no default-surface options; use ordinary `dsh --resume ` to resume a persisted session. +`dsh experimental-meta` is that same TUI with this harness checkout as the workspace, so working on dsh itself needs no `cd`. It chdirs to the checkout root — resolved from the launcher's real path, the same root the source-path prompt section names — after the environment is settled, so precedence is unchanged while the session cwd and HMR watch root move together. Experimental meta always starts a fresh session and accepts no default-surface options; use ordinary `dsh --resume ` to resume a persisted session. -`dsh upgrade` is a guided fresh-session entry over the default TUI surface: it mints a fresh session in the invoking directory and seeds its first turn with the bundled `dsh-upgrade` skill, exactly as if the user typed `/skill:`. The launcher passes the skill name on the boot context ([`INITIAL_SKILL_KEY`](../../packages/ui/tui/README.md)), which the TUI auto-invokes once the chat is live. Both take no options — `--config`, `-p`, and `--resume` fail loud — and seed only on this first launch, so a later `dsh --resume ` of the session is an ordinary TUI session with no re-injection. +`dsh experimental-upgrade` is a guided fresh-session entry over the default TUI surface: it mints a fresh session in the invoking directory and seeds its first turn with the bundled `dsh-upgrade` skill, exactly as if the user typed `/skill:`. The launcher passes the skill name on the boot context ([`INITIAL_SKILL_KEY`](../../packages/ui/tui/README.md)), which the TUI auto-invokes once the chat is live. The command takes no options — `--config`, `-p`, and `--resume` fail loud — and seeds only on this first launch, so a later `dsh --resume ` of the session is an ordinary TUI session with no re-injection. `dsh --dump-config` and `dsh web --dump-config` print the composed config tree — the shipped base, the surface overlay, and the `--config` or personal overlay, exactly the layers that surface would boot — as YAML on stdout and exit without booting; `--dump-default-config` stops at the surface overlay, so diffing the two shows precisely what the user layer changes. Each run of rows is preceded by a `# ==` comment naming the file it comes from and the layers that patched it (e.g. `# == base.cordis.yml, patched by tui.cordis.yml`), so the output shows provenance while staying one loadable document. Composition runs through the include's own patch algorithm and YAML dialect (`applyEntryPatches`/`entryListSchema` from `@cordisjs/plugin-include`), so the dump cannot drift from what boots; `!!js` expressions print verbatim and unevaluated, and a patch whose target row is absent is reported on stderr with its layer, mirroring the Loader's boot-time warning. Launcher-owned boot-context values (session identity, CLI-flag patches) are per-invocation facts outside the config tree and do not appear. The dump flags reject boot-only flags (`-p`, `--resume`, `--config-replace`) rather than silently ignoring them, and `--dump-default-config` takes no `--config`. @@ -23,9 +25,9 @@ The Web and headless surfaces boot `base.cordis.yml` plus `web.cordis.yml`, then The shipped TUI and Web compositions register the native DeepSeek adapter plus pi-ai OpenAI and Anthropic profiles. Credentials and endpoint overrides come from the provider-standard `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`, `OPENAI_API_KEY` / `OPENAI_BASE_URL`, and `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` pairs in the boot's layered environment. -The Web/headless composition also registers only `web_search`. Search uses DeepSeek's Anthropic-compatible Messages endpoint, resolves the same `DEEPSEEK_API_KEY` reference for every call, and accepts the separate `DEEPSEEK_SEARCH_BASE_URL` endpoint override; each search is an auxiliary model request with its own latency and token cost. `web_fetch` remains disabled and the composition mounts no default fetch provider, so deployments that need arbitrary page retrieval must opt in through an overlay. The TUI composition does not mount Web tools by default. The deployment decision and its security boundary live in the [default Web search Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-default-search.md). +Every surface also registers `web_search` and only `web_search`. Search uses DeepSeek's Anthropic-compatible Messages endpoint, resolves the same `DEEPSEEK_API_KEY` reference for every call, and accepts the separate `DEEPSEEK_SEARCH_BASE_URL` endpoint override; each search is an auxiliary model request with its own latency and token cost. `web_fetch` remains disabled and the composition mounts no default fetch provider, so deployments that need arbitrary page retrieval must opt in through an overlay. The deployment decision and its security boundary live in the [default Web search Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-default-search.md). -`DSH_TOOLS_MODE` selects the tool presentation mode for the whole Web/headless process: `native` (the schema default when unset), `code` (the `run_code`-only Code Mode wire), or `both`; any other value fails loud at boot through the `dsh-tools` config schema. It is a TEMPORARY seam — process-wide because Loader composition is static — and is removed once the web UI owns per-session tool-mode selection; the TUI surface ignores it (its config tree pins its own mode). +`DSH_TOOLS_MODE` selects the tool presentation mode for the whole Web/headless process: `native` (the schema default when unset), `code` (the `run_code`-only Code Mode wire), or `both`; any other value fails loud at boot through the `dsh-tools` config schema. It is a TEMPORARY seam — process-wide because Loader composition is static — and is removed once the web UI owns per-session tool-mode selection; the TUI surface ignores it and pins `native`. [`core-web.cordis.yml`](config/core-web.cordis.yml) is an opt-in `dsh web --config` overlay that keeps the shipped Web host, browser, Workspace, persistence, and permission composition while reducing the default native model surface to owner-scoped persistent `bash` and `str_replace_editor`. The PTY backend and editor consume the existing Web sandbox and filesystem providers. An open persistent shell prevents changing that session's permission mode until the shell closes, so a shell created under wider access cannot survive a downgrade. `DSH_TOOLS_MODE` still controls native/Code Mode presentation for the resulting two-tool registry. @@ -37,6 +39,23 @@ pnpm run dsh web --config apps/cli/config/core-web.cordis.yml Every `dsh` surface — TUI, Web, and headless — reports session telemetry by default (the row lives in the shared `base.cordis.yml`): every session-log event streams as OTLP/HTTP log records to `https://harness-telemetry.deepseeksvc.com/v1/logs` on a 10-second batch cadence. `DSH_TELEMETRY_OTLP_URL` points the exporter at a different collector; setting `DSH_TELEMETRY_DISABLED` to ANY non-empty value — including `0` or `false` — disables the row before it loads (a privacy switch prefers off-by-mistake over on-by-mistake). No redaction rule is mounted in this composition yet: exported records are the raw captured copy, including message text, tool arguments and results, and the session's working-directory path. The deployment rulings live in the [web-telemetry-default-mount Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md). +MCP servers are not a shipped default, because a default would have to name one: `@deepseek-ai/dsh-mcp-client` mounts exactly one server per row and spawns it as a child process, outside `ctx.bash` and so outside the sandbox policy. The package is a runtime dependency of this CLI, so an installed `dsh` can mount your own servers from `$DSH_HOME/config.yaml` or a `--config` overlay without a source checkout: + +```yaml +- insert: + - id: mcp-github + name: '@deepseek-ai/dsh-mcp-client' + config: + serverName: github + transport: stdio + command: npx + args: ['-y', '@modelcontextprotocol/server-github'] + env: + GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN +``` + +The model then sees `mcp__github__*`. See the [mcp-client README](../../packages/mcp/mcp-client/README.md) for the Streamable HTTP transport and the full field table. + ## Install (developer machine) Symlink the source-running launcher onto your PATH; it resolves the checkout through its own real path, so code changes apply on the next launch with no build step: diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md index 8f38fd342a..b19d497935 100644 --- a/apps/cli/README.zh.md +++ b/apps/cli/README.zh.md @@ -3,19 +3,21 @@ [English](README.md) | 中文 -Argv 只会通过 [Commander](https://github.com/tj/commander.js) 适配器（[`src/args.ts`](src/args.ts)）解析一次：同一个程序的默认形式（无子命令）是 TUI／无头界面（`--config`、`-p`/`--prompt`、`--resume`、`--dump-config`、`--dump-default-config`），`meta` 子命令是以本 checkout 为 workspace 的同一个 TUI，`upgrade` 子命令是无选项的引导会话入口，`web` 子命令则是浏览器 UI。`src/bin.ts` 按解析后的 mode 分支，仅动态导入该 mode 的模块。`dsh --help` 列出所有 mode，`dsh web --help` 渲染 Web 用法，`dsh --version` 打印此应用的版本；未知选项或拼错的 `--resume` 会明确报错（stderr，退出码 1），而不会被错路由。凡与默认界面不共享任何选项的子命令（`upgrade`、`web`、`meta`）都会拒绝泄漏进来的 `--config`/`-p`/`--resume`/dump 标志，而不会照常运行并丢弃它。`dsh web` 的 `--host`/`--port` 是未验证的直通覆盖：`dsh-host-webserver` schema 是默认值（标志缺失时使用已交付的 Web 覆盖层值）和有效性的唯一真源，并在启动时拒绝错误值。`--trusted-host` 为 /api 浏览器信任栅栏追加具名权威；全接口绑定还会自行推导本机的 LAN IP 字面量（[`src/app-cli-entry.ts`](src/app-cli-entry.ts)），因此打印出的 LAN URL 无需任何标志即可使用。 +Argv 只会通过 [Commander](https://github.com/tj/commander.js) 适配器（[`src/args.ts`](src/args.ts)）解析一次：同一个程序的默认形式（无子命令）是 TUI／无头界面（`--config`、`-p`/`--prompt`、`--resume`、`--dump-config`、`--dump-default-config`），`experimental-meta` 子命令是以本 checkout 为 workspace 的同一个 TUI，`experimental-upgrade` 子命令是无选项的引导会话入口，`web` 子命令则是浏览器 UI。`src/bin.ts` 按解析后的 mode 分支，仅动态导入该 mode 的模块。`dsh --help` 列出所有 mode，`dsh web --help` 渲染 Web 用法，`dsh --version` 打印此应用的版本；未知选项或拼错的 `--resume` 会明确报错（stderr，退出码 1），而不会被错路由。凡与默认界面不共享任何选项的子命令（`experimental-upgrade`、`web`、`experimental-meta`）都会拒绝泄漏进来的 `--config`/`-p`/`--resume`/dump 标志，而不会照常运行并丢弃它。`dsh web` 的 `--host`/`--port` 是未验证的直通覆盖：`dsh-host-webserver` schema 是默认值（标志缺失时使用已交付的 Web 覆盖层值）和有效性的唯一真源，并在启动时拒绝错误值。`--trusted-host` 为 /api 浏览器信任栅栏追加具名权威；全接口绑定还会自行推导本机的 LAN IP 字面量（[`src/app-cli-entry.ts`](src/app-cli-entry.ts)），因此打印出的 LAN URL 无需任何标志即可使用。 TUI 界面： - 通过 [`dsh-app-boot`](../../packages/ui/app-boot/README.md) 启动 `base.cordis.yml` 与 `tui.cordis.yml`；`--config ` 应用一个补丁列表覆盖并替代个人覆盖，而 `--config-replace ` 将指定文件作为完整配置树启动； - 使用 `dsh --resume ` 恢复已持久化会话。当 Node 宿主公开 `process.execve` 时，还会提供 TUI 的原地移交宿主：选择器预检并刷新当前会话后，宿主会释放应用，并以规范化的恢复调用替换进程；不支持进程替换的运行时会让会话继续运行并给出提示。会话身份与退出行由本 CLI 拥有，而非由配置指定：它创建或选定 `main` 会话 id，并把该 id 以及可复现本次调用的确切命令一起提供到启动上下文（[`MAIN_SESSION_ID_KEY`](../../packages/ui/tui/README.md) 与 `TUI_GOODBYE_MESSAGE_KEY`）。任何 `cordis.yml` 键都无法移除恢复能力；缺失或无法读取的 id 会明确报错，而不会创建新会话； -- 将 **调用目录** 视为 workspace：会话、相对路径和 workspace 指令都从 cwd 解析（`dsh meta` 是唯一例外，见下文）； +- 将 **调用目录** 视为 workspace：会话、相对路径和 workspace 指令都从 cwd 解析（`dsh experimental-meta` 是唯一例外，见下文）； - 告知 agent 自身源码所在位置：启动后添加一个命名此 harness checkout 的提示词段。该路径从启动器的真实路径解析，因此在 PATH 符号链接和任意 cwd 下仍然有效，使自指的 `cordis` 工具集可以读取并修改它； - 应用 `~/.dsh` 中的个人覆盖（参见 [app-boot 的个人配置](../../packages/ui/app-boot/README.md#personal-config)）：`config.yaml` 修补已启动的树，而那里的 `.env` 是凭据 provider 自己的存储（绝不会被提升进环境，因此密钥始终可轮换）。环境优先级为环境中已有的值 > 项目 `.env`。 +- 当 `DSH_HOME` 下不存在不可变确认标记时，通过已挂载的 TUI overlay 服务呈现[版本化首次运行欢迎页](../../.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.md)；只有 Enter 会创建该版本的标记，Escape、资源释放或进程退出仍保留展示资格。官方 DeepSeek 图标、响应式终端栅格图、所有 locale 共用的中文文案和通知版本均由静态本地文件持有；overlay 不会写入会话事件或模型上下文。 +- 注册裸 `/compact`：agent 空闲时，即使未达到自动压力，也会摘要有效的较早历史；该命令拒绝参数，并只在独立替换标记对持久化后报告成功。压缩（compaction）期间提交的提示词保留其队列身份，并在该检查点之后启动；注入的上下文仍保持可见。 -`dsh meta` 是以本 harness checkout 为 workspace 的同一个 TUI，因此开发 dsh 自身无需 `cd`。它在环境确定之后才 chdir 到 checkout 根目录（从启动器的真实路径解析，与源码路径提示词段所指的根目录相同），因此环境优先级不变，而会话 cwd 与 HMR 监视根目录会一并移动。Meta 始终创建新会话，不接受默认界面的任何选项；恢复已持久化会话应使用普通的 `dsh --resume `。 +`dsh experimental-meta` 是以本 harness checkout 为 workspace 的同一个 TUI，因此开发 dsh 自身无需 `cd`。它在环境确定之后才 chdir 到 checkout 根目录（从启动器的真实路径解析，与源码路径提示词段所指的根目录相同），因此环境优先级不变，而会话 cwd 与 HMR 监视根目录会一并移动。Experimental meta 始终创建新会话，不接受默认界面的任何选项；恢复已持久化会话应使用普通的 `dsh --resume `。 -`dsh upgrade` 是默认 TUI 界面之上的引导式全新会话入口：它在调用目录中创建一个全新会话，并以内置 `dsh-upgrade` skill 播种其首轮，效果等同于用户手动键入 `/skill:`。启动器将 skill 名称提供到启动上下文（[`INITIAL_SKILL_KEY`](../../packages/ui/tui/README.md)），TUI 在聊天就绪后自动调用它。两者都不接受任何选项——`--config`、`-p`、`--resume` 都会明确报错——且仅在首次启动时播种，因此之后 `dsh --resume ` 恢复该会话时是普通 TUI 会话，不会重复注入。 +`dsh experimental-upgrade` 是默认 TUI 界面之上的引导式全新会话入口：它在调用目录中创建一个全新会话，并以内置 `dsh-upgrade` skill 播种其首轮，效果等同于用户手动键入 `/skill:`。启动器将 skill 名称提供到启动上下文（[`INITIAL_SKILL_KEY`](../../packages/ui/tui/README.md)），TUI 在聊天就绪后自动调用它。该命令不接受任何选项——`--config`、`-p`、`--resume` 都会明确报错——且仅在首次启动时播种，因此之后 `dsh --resume ` 恢复该会话时是普通 TUI 会话，不会重复注入。 `dsh --dump-config` 和 `dsh web --dump-config` 把合成后的配置树——已交付的基础配置、界面覆盖层，以及 `--config` 或个人覆盖层，恰好是该界面启动时组装的那些层——以 YAML 打印到 stdout 后退出，不启动任何东西；`--dump-default-config` 止步于界面覆盖层，因此对两份输出做 diff 就能精确看出用户层改了什么。每段连续的行之前都有一条 `# ==` 注释，标明该段来自哪个文件以及被哪些层修补过（例如 `# == base.cordis.yml, patched by tui.cordis.yml`），因此输出既展示来源，又仍是一份可加载的文档。合成通过 include 自己的补丁算法和 YAML 方言（`@cordisjs/plugin-include` 的 `applyEntryPatches`/`entryListSchema`）完成，因此 dump 不可能与实际启动漂移；`!!js` 表达式原样打印、不求值，目标行不存在的补丁会连同其所在层报到 stderr，与 Loader 启动时的警告一致。由启动器持有的启动上下文值（会话身份、CLI 标志补丁）是每次调用的事实，位于配置树之外，不会出现。dump 标志会拒绝仅用于启动的标志（`-p`、`--resume`、`--config-replace`）而不是静默忽略它们，`--dump-default-config` 不接受 `--config`。 @@ -23,9 +25,9 @@ Web 和无头界面启动 `base.cordis.yml` 与 `web.cordis.yml`，随后应用 已交付的 TUI 和 Web 组合会注册原生 DeepSeek 适配器，以及 pi-ai 的 OpenAI 和 Anthropic 提供方配置。凭据和端点覆盖来自启动分层环境中的提供方标准变量对：`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`、`OPENAI_API_KEY` / `OPENAI_BASE_URL` 和 `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`。 -Web／无头组合还只会注册 `web_search`。搜索使用 DeepSeek 的 Anthropic 兼容 Messages 端点，每次调用都会解析同一个 `DEEPSEEK_API_KEY` 凭据引用，并接受独立的 `DEEPSEEK_SEARCH_BASE_URL` 端点覆盖；每次搜索都是一次辅助模型请求，会产生独立的延迟与 token 成本。`web_fetch` 仍处于禁用状态，组合也未挂载默认抓取提供方；需要任意页面抓取能力的部署必须通过覆盖层选择启用。TUI 组合默认不挂载 Web 工具。部署决策及其安全边界见[默认 Web 搜索 Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-default-search.md)。 +每个界面也都只注册 `web_search` 这一个 Web 工具。搜索使用 DeepSeek 的 Anthropic 兼容 Messages 端点，每次调用都会解析同一个 `DEEPSEEK_API_KEY` 凭据引用，并接受独立的 `DEEPSEEK_SEARCH_BASE_URL` 端点覆盖；每次搜索都是一次辅助模型请求，会产生独立的延迟与 token 成本。`web_fetch` 仍处于禁用状态，组合也未挂载默认抓取提供方；需要任意页面抓取能力的部署必须通过覆盖层选择启用。部署决策及其安全边界见[默认 Web 搜索 Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-default-search.md)。 -`DSH_TOOLS_MODE` 为整个 Web／无头进程选择工具呈现模式：可选值为 `native`（未设置时的 schema 默认值）、`code`（仅含 `run_code` 的 Code Mode 协议接口）或 `both`；任何其他值都会经由 `dsh-tools` 配置 schema 在启动时明确报错。它是一个临时 seam：Loader 组合是静态的，因此该设置作用于整个进程；待 Web UI 负责逐会话工具模式选择后便会移除。TUI 界面会忽略该变量（其配置树固定了自身模式）。 +`DSH_TOOLS_MODE` 为整个 Web／无头进程选择工具呈现模式：`native`（未设置时的 schema 默认值）、`code`（仅含 `run_code` 的 Code Mode 线路）或 `both`；任何其他值都会经由 `dsh-tools` 配置 schema 在启动时明确报错。它是一个临时 seam——Loader 组合是静态的，因此该设置作用于整个进程——待 Web UI 负责逐会话工具模式选择后便会移除；TUI 界面会忽略该变量并固定为 `native`。 [`core-web.cordis.yml`](config/core-web.cordis.yml) 是一个可选启用的 `dsh web --config` 覆盖层：它保留已交付的 Web 宿主、浏览器、Workspace、持久化与权限组合，同时将默认的原生模型界面精简为以所有者为作用域的持久 `bash` 以及 `str_replace_editor`。PTY 后端和编辑器分别消费现有的 Web 沙箱与文件系统提供方。持久 shell 处于打开状态时，会阻止所属会话更改权限模式；因此，在较宽权限下创建的 shell 无法在降权后继续存活。`DSH_TOOLS_MODE` 仍控制由此得到的双工具注册表采用原生／Code Mode 呈现。 @@ -37,6 +39,23 @@ pnpm run dsh web --config apps/cli/config/core-web.cordis.yml 每个 `dsh` 界面——TUI、Web 与无头——都默认上报会话遥测（该行位于共享的 `base.cordis.yml`）：每条会话日志事件以 OTLP/HTTP 日志记录的形式、按 10 秒批处理节奏流向 `https://harness-telemetry.deepseeksvc.com/v1/logs`。`DSH_TELEMETRY_OTLP_URL` 可将 exporter 指向其他 collector；将 `DSH_TELEMETRY_DISABLED` 设为**任意非空值**——包括 `0` 或 `false`——都会在该行加载前将其关停（隐私开关取「宁可误关、不可误开」）。该组合当前未挂载任何脱敏规则：导出记录即原始捕获副本，包含消息正文、工具参数与结果、以及会话工作目录路径。部署口径见 [web-telemetry-default-mount Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md)。 +MCP 服务器不是交付默认值,因为默认值必须点名一台:`@deepseek-ai/dsh-mcp-client` 每一行只挂载一台服务器,并把它作为子进程 spawn,该进程不经 `ctx.bash`,因此也不受沙箱策略约束。该包是本 CLI 的运行时依赖,所以已安装的 `dsh` 无需源码检出即可从 `$DSH_HOME/config.yaml` 或 `--config` 覆盖层挂载你自己的服务器: + +```yaml +- insert: + - id: mcp-github + name: '@deepseek-ai/dsh-mcp-client' + config: + serverName: github + transport: stdio + command: npx + args: ['-y', '@modelcontextprotocol/server-github'] + env: + GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN +``` + +模型随后会看到 `mcp__github__*`。Streamable HTTP 传输与完整字段表见 [mcp-client README](../../packages/mcp/mcp-client/README.md)。 + ## 安装（开发机） 将从源码运行的启动器符号链接到 PATH 上；它通过自身真实路径解析 checkout，因此代码更改会在下次启动时生效，无需构建： diff --git a/apps/cli/assets/deepseek-color.svg b/apps/cli/assets/deepseek-color.svg new file mode 100644 index 0000000000..52eec25cd3 --- /dev/null +++ b/apps/cli/assets/deepseek-color.svg @@ -0,0 +1 @@ +DeepSeek diff --git a/apps/cli/composition.md b/apps/cli/composition.md index 870b926054..b552570a5c 100644 --- a/apps/cli/composition.md +++ b/apps/cli/composition.md @@ -76,6 +76,8 @@ flowchart LR cfg --> plugin_tui_token_meter plugin_tui_compact_basic["compact-basic
@deepseek-ai/dsh-compact-basic"] cfg --> plugin_tui_compact_basic + plugin_tui_command_compact["command-compact
@deepseek-ai/dsh-command-compact"] + cfg --> plugin_tui_command_compact plugin_tui_subagent["subagent
@deepseek-ai/dsh-subagent"] cfg --> plugin_tui_subagent plugin_tui_subagent_spawn["subagent-spawn
@deepseek-ai/dsh-subagent-spawn"] @@ -96,6 +98,28 @@ flowchart LR cfg --> plugin_tui_spill_local plugin_tui_spill_policy["spill-policy
@deepseek-ai/dsh-spill-policy"] cfg --> plugin_tui_spill_policy + plugin_tui_session_checkpoint_policy["session-checkpoint-policy
@deepseek-ai/dsh-session-checkpoint-policy"] + cfg --> plugin_tui_session_checkpoint_policy + plugin_tui_tool_result_prune["tool-result-prune
@deepseek-ai/dsh-compact-tool-result-prune"] + cfg --> plugin_tui_tool_result_prune + plugin_tui_tool_todo["tool-todo
@deepseek-ai/dsh-tool-todo"] + cfg --> plugin_tui_tool_todo + plugin_tui_tool_goal["tool-goal
@deepseek-ai/dsh-tool-goal"] + cfg --> plugin_tui_tool_goal + plugin_tui_tool_ralph["tool-ralph
@deepseek-ai/dsh-tool-ralph"] + cfg --> plugin_tui_tool_ralph + plugin_tui_tool_session_query["tool-session-query
@deepseek-ai/dsh-tool-session-query"] + cfg --> plugin_tui_tool_session_query + plugin_tui_tool_str_replace_editor["tool-str-replace-editor
@deepseek-ai/dsh-tool-str-replace-editor"] + cfg --> plugin_tui_tool_str_replace_editor + plugin_tui_repeat_tool_guard["repeat-tool-guard
@deepseek-ai/dsh-repeat-tool-guard"] + cfg --> plugin_tui_repeat_tool_guard + plugin_tui_web["web
@deepseek-ai/dsh-web"] + cfg --> plugin_tui_web + plugin_tui_web_search_deepseek["web-search-deepseek
@deepseek-ai/dsh-web-search-deepseek"] + cfg --> plugin_tui_web_search_deepseek + plugin_tui_tool_web["tool-web
@deepseek-ai/dsh-tool-web"] + cfg --> plugin_tui_tool_web plugin_tui_tools["tools
@deepseek-ai/dsh-tools"] cfg --> plugin_tui_tools plugin_tui_system_prompt["system-prompt
@deepseek-ai/dsh-system-prompt"] @@ -144,6 +168,7 @@ flowchart LR | `plan-mode` | `@deepseek-ai/dsh-plan-mode` | | `token-meter` | `@deepseek-ai/dsh-token-meter` | | `compact-basic` | `@deepseek-ai/dsh-compact-basic` | +| `command-compact` | `@deepseek-ai/dsh-command-compact` | | `subagent` | `@deepseek-ai/dsh-subagent` | | `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` | | `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` | @@ -154,6 +179,17 @@ flowchart LR | `timeout-policy` | `@deepseek-ai/dsh-timeout-policy` | | `spill-local` | `@deepseek-ai/dsh-spill-local` | | `spill-policy` | `@deepseek-ai/dsh-spill-policy` | +| `session-checkpoint-policy` | `@deepseek-ai/dsh-session-checkpoint-policy` | +| `tool-result-prune` | `@deepseek-ai/dsh-compact-tool-result-prune` | +| `tool-todo` | `@deepseek-ai/dsh-tool-todo` | +| `tool-goal` | `@deepseek-ai/dsh-tool-goal` | +| `tool-ralph` | `@deepseek-ai/dsh-tool-ralph` | +| `tool-session-query` | `@deepseek-ai/dsh-tool-session-query` | +| `tool-str-replace-editor` | `@deepseek-ai/dsh-tool-str-replace-editor` | +| `repeat-tool-guard` | `@deepseek-ai/dsh-repeat-tool-guard` | +| `web` | `@deepseek-ai/dsh-web` | +| `web-search-deepseek` | `@deepseek-ai/dsh-web-search-deepseek` | +| `tool-web` | `@deepseek-ai/dsh-tool-web` | | `tools` | `@deepseek-ai/dsh-tools` | | `system-prompt` | `@deepseek-ai/dsh-system-prompt` | | `agent-loop` | `@deepseek-ai/dsh-agent-loop` | diff --git a/apps/cli/config/base.cordis.yml b/apps/cli/config/base.cordis.yml index 4bde1e4b6a..7e648eedc8 100644 --- a/apps/cli/config/base.cordis.yml +++ b/apps/cli/config/base.cordis.yml @@ -201,6 +201,11 @@ - id: compact-basic name: '@deepseek-ai/dsh-compact-basic' +# Human `/compact`: one useful reduction below the automatic threshold. Backend +# independent, so it follows whichever compaction service this leaf mounts. +- id: command-compact + name: '@deepseek-ai/dsh-command-compact' + - id: subagent name: '@deepseek-ai/dsh-subagent' @@ -245,6 +250,74 @@ config: maxInlineBytes: 50000 +# Durability checkpoints before each model request and top-level dispatch. +- id: session-checkpoint-policy + name: '@deepseek-ai/dsh-session-checkpoint-policy' + +# Compacts oversized tool results before the broader conversation compactor +# runs, preserving the model-visible result within the configured budget. +- id: tool-result-prune + name: '@deepseek-ai/dsh-compact-tool-result-prune' + config: + thresholdChars: 8192 + headChars: 4096 + tailChars: 1024 + +- id: tool-todo + name: '@deepseek-ai/dsh-tool-todo' + +# Persisted same-session goals reach the model and the slash menu here; the +# domain, driver, and `/goal` command are above. +- id: tool-goal + name: '@deepseek-ai/dsh-tool-goal' + +# Fresh-agent Ralph iteration over a build-time-fixed script. +- id: tool-ralph + name: '@deepseek-ai/dsh-tool-ralph' + config: + subagentProvider: spawn + maxRounds: 64 + +- id: tool-session-query + name: '@deepseek-ai/dsh-tool-session-query' + config: + maxSearchResults: 100 + searchTimeoutMs: 30000 + +- id: tool-str-replace-editor + name: '@deepseek-ai/dsh-tool-str-replace-editor' + config: + maxOutputChars: 16000 + +# Consecutive-repeat reminders on the tool chain. +- id: repeat-tool-guard + name: '@deepseek-ai/dsh-repeat-tool-guard' + config: + thresholds: [3, 5, 8] + argumentsPreviewChars: 500 + +# Every surface enables the stable web_search model surface. DeepSeek search +# resolves the same DEEPSEEK_API_KEY credential the Models page manages for +# chat, at each search; its Messages endpoint is separate from the +# chat-completions endpoint, so it takes its own base-URL override. Fetch stays +# disabled and no fetch provider is mounted: that provider defers SSRF +# protection and the model would choose the request target. +- id: web + name: '@deepseek-ai/dsh-web' + config: + searchProvider: deepseek-official + +- id: web-search-deepseek + name: '@deepseek-ai/dsh-web-search-deepseek' + config: + apiKeyEnv: DEEPSEEK_API_KEY + baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL + +- id: tool-web + name: '@deepseek-ai/dsh-tool-web' + config: + fetch: false + # ── rows every surface mounts, whose values each overlay states ────────────── # The tool registry. Presentation mode is a surface choice, so each overlay diff --git a/apps/cli/config/core-web.cordis.yml b/apps/cli/config/core-web.cordis.yml index 347a5bfbe6..ef03b23fca 100644 --- a/apps/cli/config/core-web.cordis.yml +++ b/apps/cli/config/core-web.cordis.yml @@ -37,6 +37,20 @@ - id: tool-todo disabled: true +# These consumers are shared defaults on the ordinary shipped surfaces, but +# this opt-in profile keeps exactly its two named tools. +- id: tool-goal + disabled: true + +- id: tool-ralph + disabled: true + +- id: tool-session-query + disabled: true + +- id: tool-str-replace-editor + disabled: true + # The matching browser controls must not offer host tools that this profile # omits. ui-question's host half owns the ask_user_question registration. - id: ui-plan diff --git a/apps/cli/config/tui.cordis.yml b/apps/cli/config/tui.cordis.yml index 980f9d80ad..d9ce7de680 100644 --- a/apps/cli/config/tui.cordis.yml +++ b/apps/cli/config/tui.cordis.yml @@ -71,29 +71,17 @@ - id: agent-loop-invariant name: '@deepseek-ai/dsh-agent-loop/invariant' - - id: session-checkpoint-policy - name: '@deepseek-ai/dsh-session-checkpoint-policy' - # The derived query index behind `/resume`. The launcher provides a unique # process-local path because this SQLite backend has one writer owner; the # project-local fallback applies when no launcher sets the typed slot. - id: session-reference name: '@deepseek-ai/dsh-session-reference' - # Compacts oversized tool results before the broader conversation compactor - # runs, preserving the model-visible result within the configured budget. - - id: tool-result-prune - name: '@deepseek-ai/dsh-compact-tool-result-prune' - - # Persisted same-session goals reach the model and the slash menu here; the - # domain, driver, and `/goal` command are in the base. - - id: tool-goal - name: '@deepseek-ai/dsh-tool-goal' - - # A separate fixed consumer demonstrates fresh-agent Ralph iteration without - # changing the workflow tool or same-session goal behavior. - - id: tool-ralph - name: '@deepseek-ai/dsh-tool-ralph' + # Terminal-multiplexer context, mounted only where a terminal exists. + - id: tmux-context + name: '@deepseek-ai/dsh-tmux-context' + config: + refreshIntervalMs: 900000 # The keyboard-backed provider behind ask_user_question and the plan-mode # review, and the front door it renders inside. diff --git a/apps/cli/config/web.cordis.yml b/apps/cli/config/web.cordis.yml index 159b2e270c..f0c2e5ea28 100644 --- a/apps/cli/config/web.cordis.yml +++ b/apps/cli/config/web.cordis.yml @@ -80,28 +80,6 @@ - id: fs-local disabled: true -# The Web/headless product enables only the stable web_search model surface. -# DeepSeek search resolves the same DEEPSEEK_API_KEY credential the Models page -# manages for chat, at each search; its Messages endpoint is separate from the -# chat-completions endpoint. Fetch remains disabled and no default fetch -# provider is mounted. -- insert: - - id: web - name: '@deepseek-ai/dsh-web' - config: - searchProvider: deepseek-official - - - id: web-search-deepseek - name: '@deepseek-ai/dsh-web-search-deepseek' - config: - apiKeyEnv: DEEPSEEK_API_KEY - baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL - - - id: tool-web - name: '@deepseek-ai/dsh-tool-web' - config: - fetch: false - # ── web-only host rows, the transport layer, and the browser roster ───────── # `dshClient` rows are the browser roster the modules node half scans into @@ -135,9 +113,6 @@ writeEveryEvents: 200 writeIntervalMs: 5000 - - id: tool-todo - name: '@deepseek-ai/dsh-tool-todo' - # Resolve bind host, SSH launch, and display once at boot, then mount the # matching dual-face directory picker. Mount -native or -browse directly in # an overlay to pin the interaction. diff --git a/apps/cli/package.json b/apps/cli/package.json index 997cea8e5f..2269ceaffb 100644 --- a/apps/cli/package.json +++ b/apps/cli/package.json @@ -9,6 +9,7 @@ }, "files": [ "lib/bin.js", + "assets", "config", "src" ], @@ -47,6 +48,7 @@ "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^", "@deepseek-ai/dsh-client-ui-workspace": "workspace:^", "@deepseek-ai/dsh-code-runtime-worker": "workspace:^", + "@deepseek-ai/dsh-command-compact": "workspace:^", "@deepseek-ai/dsh-command-goal": "workspace:^", "@deepseek-ai/dsh-commands": "workspace:^", "@deepseek-ai/dsh-compact-basic": "workspace:^", @@ -72,6 +74,7 @@ "@deepseek-ai/dsh-paths": "workspace:^", "@deepseek-ai/dsh-permission": "workspace:^", "@deepseek-ai/dsh-plan-mode": "workspace:^", + "@deepseek-ai/dsh-repeat-tool-guard": "workspace:^", "@deepseek-ai/dsh-pty": "workspace:^", "@deepseek-ai/dsh-pty-local": "workspace:^", "@deepseek-ai/dsh-sandbox-local": "workspace:^", @@ -103,6 +106,7 @@ "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tasks-local": "workspace:^", "@deepseek-ai/dsh-timeout-policy": "workspace:^", + "@deepseek-ai/dsh-tmux-context": "workspace:^", "@deepseek-ai/dsh-token-meter": "workspace:^", "@deepseek-ai/dsh-tool-ask-user": "workspace:^", "@deepseek-ai/dsh-tool-bash": "workspace:^", @@ -112,6 +116,7 @@ "@deepseek-ai/dsh-tool-fs-search": "workspace:^", "@deepseek-ai/dsh-tool-goal": "workspace:^", "@deepseek-ai/dsh-tool-ralph": "workspace:^", + "@deepseek-ai/dsh-tool-session-query": "workspace:^", "@deepseek-ai/dsh-tool-skill": "workspace:^", "@deepseek-ai/dsh-tool-str-replace-editor": "workspace:^", "@deepseek-ai/dsh-tool-subagent": "workspace:^", @@ -128,6 +133,7 @@ "@deepseek-ai/dsh-workflow-workerthread": "workspace:^", "@deepseek-ai/dsh-workspace": "workspace:^", "@deepseek-ai/dsh-workspace-context": "workspace:^", + "@earendil-works/pi-tui": "0.80.7", "commander": "^15.0.0", "cordis": "^4.0.0-rc.7", "js-yaml": "^4.2.0" diff --git a/apps/cli/src/args.ts b/apps/cli/src/args.ts index ac74b9468d..2c05e966bc 100644 --- a/apps/cli/src/args.ts +++ b/apps/cli/src/args.ts @@ -2,8 +2,9 @@ * Commander adapter for the `dsh` command-line entry: the one place argv is * parsed and routed to a mode. `bin.ts` switches on the returned discriminant * and dynamic-imports that mode's module. One program: the default (no - * subcommand) is the TUI/headless surface with option-only flags; `meta` and - * `web` are real subcommands. Commander owns `--help`/`--version` and parse + * subcommand) is the TUI/headless surface with option-only flags; + * `experimental-meta` and `web` are real subcommands. Commander owns + * `--help`/`--version` and parse * errors — it prints and exits at the point of failure (a domain failure routes through * `command.error`), so this returns only a resolved mode. * @module @deepseek-ai/dsh/args @@ -51,8 +52,8 @@ interface MetaInvocation { } /** - * Guided fresh-session entry: `dsh upgrade` seeds the first turn with the - * `dsh-upgrade` skill. It always mints a + * Guided fresh-session entry: `dsh experimental-upgrade` seeds the first turn + * with the `dsh-upgrade` skill. It always mints a * fresh session in the invoking directory and takes no options — `--resume`, * `--config`, and `-p` are rejected as mistyped, so there is nothing to carry. */ @@ -248,14 +249,15 @@ Examples: } // Registration order is the rendered help order, so daily use comes first - // and the harness-development surfaces (`web --dev`, `meta`) come last. - // `upgrade` is a guided fresh-session entry: it takes no options and always - // mints a fresh session, so nothing is left to carry. + // and the harness-development surfaces (`web --dev`, `experimental-meta`) + // come last. `experimental-upgrade` is a guided fresh-session entry: it + // takes no options and always mints a fresh session, so nothing is left to + // carry. program - .command('upgrade') + .command('experimental-upgrade') .description('update this dsh installation to the latest version') .action(() => { - rejectParentOptions('upgrade') + rejectParentOptions('experimental-upgrade') resolved = { mode: 'upgrade' } }) @@ -283,10 +285,10 @@ Examples: }) program - .command('meta') + .command('experimental-meta') .description('work on the dsh source that runs this command, from any directory') .action(() => { - rejectParentOptions('meta') + rejectParentOptions('experimental-meta') resolved = { mode: 'meta' } }) diff --git a/apps/cli/src/tui-onboarding/tui-first-run-welcome-art.ts b/apps/cli/src/tui-onboarding/tui-first-run-welcome-art.ts new file mode 100644 index 0000000000..afaf56db3d --- /dev/null +++ b/apps/cli/src/tui-onboarding/tui-first-run-welcome-art.ts @@ -0,0 +1,111 @@ +/** + * Static terminal rasters derived from the official 24x24 DeepSeek icon. + * + * Source: `../../assets/deepseek-color.svg`, whose path data is copied exactly + * from the supplied official icon (viewBox `0 0 24 24`, fill `#4D6BFE`). Each + * tier rasterizes that path into a square binary + * mask without redrawing its contour. The Unicode form packs two source rows + * into `▀`/`▄`/`█`; the ASCII fallback packs the same two bits into + * `'`/`_`/`#`. Assets contain no ANSI and are never generated at runtime. + * @module @deepseek-ai/dsh/tui-onboarding/tui-first-run-welcome-art + */ + +/** Responsive official-icon raster tier. */ +export type TuiFirstRunWelcomeArtTier = 'full' | 'compact' | 'minimal' + +/** One raster with a block-cell primary and bit-equivalent ASCII fallback. */ +export interface TuiFirstRunWelcomeArt { + /** Two vertical source pixels per terminal cell. */ + readonly unicode: readonly string[] + /** Same two-bit cells encoded as top `'`, bottom `_`, and both `#`. */ + readonly ascii: readonly string[] +} + +const fullUnicode = Object.freeze([ + ' ▄', + ' ▄▄▄▄▄▄▄▄▄▄███▀ ██▄', + ' ▄███████████████▄ ████▄ ▄▄▄▄██', + ' ▄███████████████████▄ ████████████▀', + ' ▄██████████████████████▄ ▀█████████▀', + '▄███▀█████████████████████▄ ████▀▀', + '███ ▀▀█████████▀▀▀█████████▀', + '███ ▀███████▀█ ▀███████', + '███▄ ▀███████▄ ▀█████▀', + '▀███ ▀██████████████', + ' ▀███▄ ▀███████████▀', + ' ▀███▄ ▄▄▄ ▀████████▀', + ' █████▄ ███▄▄ ▀█████▄▄', + ' ▀█████████████▄▄▄▄█▀█████▀', + ' ▀▀███████████▀▀', +]) + +const fullAscii = Object.freeze([ + ' _', + " __________###' ##_", + ' _###############_ ####_ ____##', + " _###################_ ############'", + " _######################_ '#########'", + "_###'#####################_ ####''", + "### ''#########'''#########'", + "### '#######'# '#######", + "###_ '#######_ '#####'", + "'### '##############", + " '###_ '###########'", + " '###_ ___ '########'", + " #####_ ###__ '#####__", + " '#############____#'#####'", + " ''###########''", +]) + +const compactUnicode = Object.freeze([ + ' ▄▄▄▄▄▄▄██▀ █▄ ▄', + ' ▄███████████▄▄ ███▄▄████', + ' ████████████████▄ ▀██████▀', + '██▀▀▀▀▀████████████▄▄██▀', + '██ ▀█████▄ ▀█████', + '██▄ ▀████▄ ▄████', + ' ██▄ ████████▀', + ' ██▄ ▄▄ ▀█████▀', + ' ▀███▄▄▄███▄ ████▄▄', + ' ▀▀▀███████▀▀', +]) + +const compactAscii = Object.freeze([ + " _______##' #_ _", + ' _###########__ ###__####', + " ################_ '######'", + "##'''''############__##'", + "## '#####_ '#####", + "##_ '####_ _####", + " ##_ ########'", + " ##_ __ '#####'", + " '###___###_ ####__", + " '''#######''", +]) + +const minimalUnicode = Object.freeze([ + ' ▄▄▄▄▄▄ ▄▄', + ' ▄████████▄ ▀████▀', + '█▀▀▀▀███████▄██▀', + '█▄ ▀███ ▀███', + '▀█▄ ▀█████', + ' ▀█▄▄ █▄▄▀███▄', + ' ▀▀▀▀▀▀', +]) + +const minimalAscii = Object.freeze([ + ' ______ __', + " _########_ '####'", + "#''''#######_##'", + "#_ '### '###", + "'#_ '#####", + " '#__ #__'###_", + " ''''''", +]) + +/** Exact-path terminal rasters by responsive tier. */ +export const TUI_FIRST_RUN_WELCOME_WHALE = Object.freeze({ + full: Object.freeze({ unicode: fullUnicode, ascii: fullAscii }), + compact: Object.freeze({ unicode: compactUnicode, ascii: compactAscii }), + minimal: Object.freeze({ unicode: minimalUnicode, ascii: minimalAscii }), +}) satisfies Readonly> diff --git a/apps/cli/src/tui-onboarding/tui-first-run-welcome-copy.ts b/apps/cli/src/tui-onboarding/tui-first-run-welcome-copy.ts new file mode 100644 index 0000000000..60cec25c52 --- /dev/null +++ b/apps/cli/src/tui-onboarding/tui-first-run-welcome-copy.ts @@ -0,0 +1,49 @@ +/** + * Centrally owned version and all-locale Chinese copy for the shipped TUI first-run notice. + * + * A material wording change increments {@link TUI_FIRST_RUN_WELCOME_NOTICE_VERSION} + * so every Harness home presents the revised notice once. + * @module @deepseek-ai/dsh/tui-onboarding/tui-first-run-welcome-copy + */ + +/** Copy version persisted after the user explicitly continues. */ +export const TUI_FIRST_RUN_WELCOME_NOTICE_VERSION = 4 + +/** Locale-shaped text rendered by the first-run welcome overlay. */ +export interface TuiFirstRunWelcomeNoticeCopy { + /** Overlay heading. */ + readonly title: string + /** Ordered prose paragraphs. */ + readonly paragraphs: readonly string[] + /** Enter action label. */ + readonly continueLabel: string + /** Hint shown when the prose is scrollable. */ + readonly scrollHint: string + /** Status shown while the acknowledgement reaches disk. */ + readonly saving: string + /** Retry message shown when the acknowledgement cannot be persisted. */ + readonly saveError: string +} + +/** Complete Chinese notice used for every locale. */ +const TUI_FIRST_RUN_WELCOME_CHINESE_COPY = Object.freeze({ + title: 'DeepSeek Harness', + paragraphs: Object.freeze([ + '感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部测试阶段，功能仍待完善，体验难免有些粗糙。', + '“如切如磋，如琢如磨。” 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中发现的问题，也可能促使我们重新审视，甚至推翻已有的设计。', + '为了帮助我们更准确地还原您真实使用中的问题，内测版本默认会上传所有 Session Log；如需关闭，请设置环境变量 DSH_TELEMETRY_DISABLED=1。另外，如果您有任何反馈与建议，请在企业微信群中留言告诉我们。每一条反馈，都会帮助我们把它打磨得更好。', + ]), + continueLabel: '继续', + scrollHint: '↑/↓ 滚动', + saving: '正在保存确认…', + saveError: '无法保存确认，请按 Enter 重试。', +}) + +/** Locale map whose entries deliberately share the single Chinese owner copy. */ +export const TUI_FIRST_RUN_WELCOME_NOTICE_COPY = Object.freeze({ + 'zh-CN': TUI_FIRST_RUN_WELCOME_CHINESE_COPY, + en: TUI_FIRST_RUN_WELCOME_CHINESE_COPY, +}) + +/** Locale presented by the shipped first-run notice. */ +export const TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE = 'zh-CN' as const diff --git a/apps/cli/src/tui-onboarding/tui-first-run-welcome.ts b/apps/cli/src/tui-onboarding/tui-first-run-welcome.ts new file mode 100644 index 0000000000..41b4c5aca2 --- /dev/null +++ b/apps/cli/src/tui-onboarding/tui-first-run-welcome.ts @@ -0,0 +1,385 @@ +/** + * Effect-owned first-run overlay for the shipped `dsh` TUI. + * + * The launcher owns the per-DSH_HOME acknowledgement boundary; the component + * reaches the terminal only through the mounted `ctx.tui` overlay service and + * never touches the session or model context. + * @module @deepseek-ai/dsh/tui-onboarding/tui-first-run-welcome + */ + +import { randomUUID } from 'node:crypto' +import { lstat, mkdir, open, rename, rm } from 'node:fs/promises' +import { basename, dirname, join } from 'node:path' +import type { Context } from 'cordis' +import { + Key, + matchesKey, + truncateToWidth, + visibleWidth, + wrapTextWithAnsi, +} from '@earendil-works/pi-tui' +import { + disposeRootAndExit, + type TuiComponent, + type TuiFocusable, + type TuiOverlayHost, +} from '@deepseek-ai/dsh-tui' +import { + TUI_FIRST_RUN_WELCOME_NOTICE_COPY, + TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE, + TUI_FIRST_RUN_WELCOME_NOTICE_VERSION, + type TuiFirstRunWelcomeNoticeCopy, +} from './tui-first-run-welcome-copy.ts' +import { + TUI_FIRST_RUN_WELCOME_WHALE, + type TuiFirstRunWelcomeArtTier, +} from './tui-first-run-welcome-art.ts' + +// TODO: Move acknowledgement persistence behind @deepseek-ai/dsh-storage once +// its backend contract supports concurrent host processes. This same-value +// marker must not inherit JSON lost updates or SQLite busy failures. +const ACKNOWLEDGEMENT_DIRECTORY = 'notices' +const ACKNOWLEDGEMENT_BASENAME = 'tui-first-run-welcome' + +/** Cordis plugin name. */ +export const name = 'tui-first-run-welcome' +/** The notice can open only after the terminal-local overlay service mounts. */ +export const inject = ['tui'] + +/** Launcher-resolved configuration for the terminal-local notice. */ +interface Config { + /** Absolute DeepSeek Harness home owning this acknowledgement. */ + readonly dshHome: string + /** Render the bit-equivalent printable ASCII icon fallback. */ + readonly asciiArt?: boolean +} + +/** + * Detect an explicitly non-Unicode terminal locale for the static ASCII art fallback. + * @param env - Process environment carrying locale and terminal declarations. + * @returns `true` only when the environment explicitly declares an ASCII-only locale or dumb terminal. + */ +export function needsTuiFirstRunWelcomeAsciiArt( + env: Readonly> = process.env, +): boolean { + const locale = env.LC_ALL ?? env.LC_CTYPE ?? env.LANG + return env.TERM === 'dumb' || locale === 'C' || locale === 'POSIX' +} + +/** + * Resolve the immutable marker for one notice version. + * @param dshHome - Resolved Harness home. + * @param version - Copy version whose acknowledgement is queried. + * @returns Absolute marker path beneath the Harness home. + */ +export function tuiFirstRunWelcomeAcknowledgementPath(dshHome: string, version: number): string { + return join( + dshHome, + ACKNOWLEDGEMENT_DIRECTORY, + `${ACKNOWLEDGEMENT_BASENAME}-v${String(version)}.ack`, + ) +} + +/** + * Test whether one notice version has been acknowledged. + * @param dshHome - Resolved Harness home. + * @param version - Copy version to inspect. + * @returns `true` only for a regular marker file; a malformed marker fails loud. + */ +export async function hasTuiFirstRunWelcomeAcknowledgement( + dshHome: string, + version: number = TUI_FIRST_RUN_WELCOME_NOTICE_VERSION, +): Promise { + const path = tuiFirstRunWelcomeAcknowledgementPath(dshHome, version) + try { + const info = await lstat(path) + if (!info.isFile()) throw new Error(`TUI welcome acknowledgement is not a file: ${path}`) + return true + } catch (error) { + if ((error as NodeJS.ErrnoException | null)?.code === 'ENOENT') return false + throw error + } +} + +/** + * Persist one version acknowledgement by syncing a random same-directory file + * before atomically replacing the immutable marker. Concurrent launches publish + * the same fact, so same-value last-writer-wins replacement loses no state. + * @param dshHome - Resolved Harness home. + * @param version - Copy version being acknowledged. + */ +export async function acknowledgeTuiFirstRunWelcome( + dshHome: string, + version: number = TUI_FIRST_RUN_WELCOME_NOTICE_VERSION, +): Promise { + const path = tuiFirstRunWelcomeAcknowledgementPath(dshHome, version) + const directory = dirname(path) + const temp = join(directory, `.${basename(path)}.${randomUUID()}.tmp`) + await mkdir(directory, { recursive: true, mode: 0o700 }) + await syncDirectory(dirname(directory)) + let handle: Awaited> | undefined + try { + handle = await open(temp, 'wx', 0o600) + await handle.sync() + const created = handle + handle = undefined + await created.close() + await rename(temp, path) + } catch (error) { + /* v8 ignore start -- fault-injected UI coverage proves failed acknowledgements stay uncommitted and retryable */ + try { + await handle?.close() + } finally { + await rm(temp, { force: true }) + } + throw error + /* v8 ignore stop */ + } + try { + await syncDirectory(directory) + /* v8 ignore next -- rename is the commit point; directory-fsync fault injection is platform-specific */ + } catch { + // Swallow post-rename directory fsync failure: the marker is already committed, + // and crash loss can only make the notice reappear on the safe side. + } +} + +/** Sync one POSIX directory after publishing a child entry. */ +/* v8 ignore start -- Windows rejects directory opens; POSIX unit coverage owns this path. */ +async function syncDirectory(path: string): Promise { + if (process.platform === 'win32') return + const handle = await open(path, 'r') + try { + await handle.sync() + } finally { + await handle.close() + } +} +/* v8 ignore stop */ + +/** Render one visible-width-padded line inside the notice frame. */ +function framed(content: string, innerWidth: number, host: TuiOverlayHost): string { + const clipped = truncateToWidth(content, innerWidth, '') + return `${host.theme.dim('│')} ${clipped}${' '.repeat(Math.max(0, innerWidth - visibleWidth(clipped)))} ${host.theme.dim('│')}` +} + +/** Center one line by terminal column width. */ +function centered(content: string, width: number): string { + const clipped = truncateToWidth(content, width, '') + const remaining = Math.max(0, width - visibleWidth(clipped)) + return `${' '.repeat(Math.floor(remaining / 2))}${clipped}` +} + +/** + * Select the art tier for the actual overlay width and viewport height. + * @param innerWidth - Columns inside the frame. + * @param viewportRows - Current terminal rows. + * @returns full, compact, minimal, or no art when prose must take priority. + */ +export function tuiFirstRunWelcomeArtTier( + innerWidth: number, + viewportRows: number, +): TuiFirstRunWelcomeArtTier | undefined { + const compositionCapacity = Math.max(1, Math.max(7, Math.floor(viewportRows * 0.9)) - 5) + if (innerWidth >= 96 && TUI_FIRST_RUN_WELCOME_WHALE.full.unicode.length <= compositionCapacity) return 'full' + if (innerWidth >= 80 && TUI_FIRST_RUN_WELCOME_WHALE.compact.unicode.length + 4 <= compositionCapacity) return 'compact' + if (innerWidth >= 64 && TUI_FIRST_RUN_WELCOME_WHALE.minimal.unicode.length + 4 <= compositionCapacity) return 'minimal' + return undefined +} + +/** Wrap the centrally owned prose while promoting its opening quotation. */ +function proseLines( + copy: TuiFirstRunWelcomeNoticeCopy, + width: number, + host: TuiOverlayHost, +): string[] { + const lines: string[] = [] + for (const [index, paragraph] of copy.paragraphs.entries()) { + if (index > 0) lines.push('') + const quoteEnd = paragraph.startsWith('“') ? paragraph.indexOf('”') : -1 + if (quoteEnd > 0) { + const quote = paragraph.slice(0, quoteEnd + 1) + const remainder = paragraph.slice(quoteEnd + 1).trimStart() + lines.push(...wrapTextWithAnsi(host.theme.bold(host.theme.text(host.display(quote))), width)) + lines.push('') + if (remainder !== '') lines.push(...wrapTextWithAnsi(host.theme.text(host.display(remainder)), width)) + } else { + lines.push(...wrapTextWithAnsi(host.theme.text(host.display(paragraph)), width)) + } + } + return lines +} + +/** Render centered static brand art without putting ANSI into its owner file. */ +function artLines( + tier: TuiFirstRunWelcomeArtTier, + width: number, + host: TuiOverlayHost, + asciiArt: boolean, +): string[] { + const art = TUI_FIRST_RUN_WELCOME_WHALE[tier][asciiArt ? 'ascii' : 'unicode'] + return art.map(line => centered(host.theme.brand(line), width)) +} + +/** Responsive, scrollable notice whose only completion input is Enter. */ +export class TuiFirstRunWelcomeComponent implements TuiComponent, TuiFocusable { + focused = false + private scrollOffset = 0 + private bodyCapacity = 1 + private maxScrollOffset = 0 + private saving = false + private saveFailed = false + + constructor( + private readonly host: TuiOverlayHost, + private readonly copy: TuiFirstRunWelcomeNoticeCopy, + private readonly acknowledge: () => Promise, + private readonly exit: () => void, + private readonly asciiArt = false, + ) {} + + invalidate(): void {} + + render(width: number): string[] { + const frameWidth = Math.max(6, width) + const innerWidth = Math.max(1, frameWidth - 4) + const viewportRows = this.host.viewport.rows + const tier = tuiFirstRunWelcomeArtTier(innerWidth, viewportRows) + const availableRows = Math.max(7, Math.floor(viewportRows * 0.9)) + const title = this.host.theme.bold(this.host.theme.brand(this.copy.title)) + let fixedHeader: string[] = [] + let fullContentHeader: string[] = [] + let body: string[] + let fullArt: string[] | undefined + const fullArtWidth = 44 + + if (tier === 'full') { + fullArt = artLines(tier, fullArtWidth, this.host, this.asciiArt) + const contentWidth = Math.max(1, innerWidth - fullArtWidth - 3) + fullContentHeader = [centered(title, contentWidth), ''] + body = proseLines(this.copy, contentWidth, this.host) + } else { + const art = tier === undefined ? [] : artLines(tier, innerWidth, this.host, this.asciiArt) + fixedHeader = [...art, ...art.length === 0 ? [] : [''], centered(title, innerWidth), ''] + body = proseLines(this.copy, innerWidth, this.host) + } + + const compositionCapacity = Math.max(1, availableRows - 5) + const bodyLimit = Math.max(1, compositionCapacity - fixedHeader.length - fullContentHeader.length) + this.bodyCapacity = Math.min(body.length, bodyLimit) + const maxOffset = Math.max(0, body.length - this.bodyCapacity) + this.maxScrollOffset = maxOffset + this.scrollOffset = Math.min(this.scrollOffset, maxOffset) + const visibleBody = body.slice(this.scrollOffset, this.scrollOffset + this.bodyCapacity) + + const top = this.host.theme.dim(`╭${'─'.repeat(Math.max(0, frameWidth - 2))}╮`) + const separator = this.host.theme.dim(`├${'─'.repeat(Math.max(0, frameWidth - 2))}┤`) + const bottom = this.host.theme.dim(`╰${'─'.repeat(Math.max(0, frameWidth - 2))}╯`) + const action = this.host.theme.bold(this.host.theme.accent(`Enter ${this.copy.continueLabel}`)) + const hasAbove = this.scrollOffset > 0 + const hasBelow = this.scrollOffset < maxOffset + const scroll = hasAbove || hasBelow + ? `${hasAbove ? '↑' : ' '} ${this.copy.scrollHint} ${hasBelow ? '↓' : ' '}` + : '' + const status = this.saveFailed + ? this.host.theme.error(this.copy.saveError) + : this.saving + ? this.host.theme.dim(this.copy.saving) + : this.host.theme.dim(scroll) + + const fullContent = [...fullContentHeader, ...visibleBody] + const composition = fullArt === undefined + ? [...fixedHeader, ...visibleBody] + : Array.from({ length: Math.max(fullArt.length, fullContent.length) }, (_, index) => { + const art = fullArt[index] ?? '' + const line = fullContent[index] ?? '' + const left = `${art}${' '.repeat(Math.max(0, fullArtWidth - visibleWidth(art)))}` + return `${left} ${line}` + }) + + return [ + top, + ...composition.map(line => framed(line, innerWidth, this.host)), + separator, + framed(centered(action, innerWidth), innerWidth, this.host), + framed(centered(status, innerWidth), innerWidth, this.host), + bottom, + ] + } + + handleInput(data: string): void { + if (matchesKey(data, Key.ctrl('c')) || matchesKey(data, Key.ctrl('d'))) { + this.exit() + return + } + if (matchesKey(data, Key.enter)) { + if (!this.saving) void this.commit() + return + } + if (this.saving || matchesKey(data, Key.escape)) return + if (matchesKey(data, Key.up)) this.scrollBy(-1) + else if (matchesKey(data, Key.down)) this.scrollBy(1) + else if (matchesKey(data, Key.pageUp)) this.scrollBy(-this.bodyCapacity) + else if (matchesKey(data, Key.pageDown)) this.scrollBy(this.bodyCapacity) + else if (matchesKey(data, Key.home)) this.scrollTo(0) + else if (matchesKey(data, Key.end)) this.scrollTo(this.maxScrollOffset) + } + + private scrollBy(delta: number): void { + this.scrollTo(this.scrollOffset + delta) + } + + private scrollTo(offset: number): void { + this.scrollOffset = Math.min(this.maxScrollOffset, Math.max(0, offset)) + this.host.invalidate() + } + + private async commit(): Promise { + this.saving = true + this.saveFailed = false + this.host.invalidate() + try { + await this.acknowledge() + this.host.close() + } catch { + this.saving = false + this.saveFailed = true + this.host.invalidate() + } + } +} + +/** + * Open the first-run notice through the mounted TUI's FIFO overlay owner. + * @param ctx - Plugin context carrying the terminal-local TUI service. + * @param config - Launcher-resolved Harness home. + */ +export function apply(ctx: Context, config: Config): void { + const copy = TUI_FIRST_RUN_WELCOME_NOTICE_COPY[TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE] + const pending = new Set>() + const acknowledge = (): Promise => { + const task = acknowledgeTuiFirstRunWelcome(config.dshHome) + pending.add(task) + const settled = (): void => { pending.delete(task) } + void task.then(settled, settled) + return task + } + ctx.effect(() => async () => { + await Promise.allSettled(pending) + }, 'tui first-run welcome acknowledgement') + ctx.tui.openOverlay({ + create: host => new TuiFirstRunWelcomeComponent( + host, + copy, + acknowledge, + () => { disposeRootAndExit(ctx, 0) }, + config.asciiArt ?? false, + ), + options: { + width: '100%', + maxHeight: '90%', + anchor: 'center', + margin: 0, + }, + }) +} diff --git a/apps/cli/src/tui.ts b/apps/cli/src/tui.ts index 7809e9ec1c..15e7d6f77b 100644 --- a/apps/cli/src/tui.ts +++ b/apps/cli/src/tui.ts @@ -8,10 +8,11 @@ * from it, so `dsh` acts on whatever project it is launched in. Session storage * is the exception — it lives under the Harness home so `/resume` reaches every * workspace, and an in-place resume enters the selected session's own directory. - * `dsh meta` is the one exception — it makes this harness checkout the - * workspace. `dsh upgrade` is a fresh session whose first turn auto-invokes a - * bundled skill. After boot, the agent's system prompt is told the path to this - * harness checkout so it can find its own source. + * `dsh experimental-meta` is the one exception — it makes this harness + * checkout the workspace. `dsh experimental-upgrade` is a fresh session whose + * first turn auto-invokes a bundled skill. After boot, the agent's system + * prompt is told the path to this harness checkout so it can find its own + * source. * @module @deepseek-ai/dsh/tui */ @@ -28,6 +29,7 @@ import { loadPersonalPatches, resolveConfigPath, } from '@deepseek-ai/dsh-app-boot' +import { resolveDshHome } from '@deepseek-ai/dsh-paths' import { SessionId } from '@deepseek-ai/dsh-session' import { configHasTelemetryRow, resolveTelemetryPatch } from './app-cli-entry.ts' import { SESSION_QUERY_SQLITE_PATH_KEY } from '@deepseek-ai/dsh-session-query-sqlite' @@ -40,6 +42,16 @@ import { type MainSessionIdentity, type TuiResumeHost, } from '@deepseek-ai/dsh-tui' +import { + apply as applyTuiFirstRunWelcome, + hasTuiFirstRunWelcomeAcknowledgement, + inject as tuiFirstRunWelcomeInject, + name as tuiFirstRunWelcomeName, + needsTuiFirstRunWelcomeAsciiArt, +} from './tui-onboarding/tui-first-run-welcome.ts' +import { + TUI_FIRST_RUN_WELCOME_NOTICE_VERSION, +} from './tui-onboarding/tui-first-run-welcome-copy.ts' const NAME = 'dsh' @@ -59,7 +71,7 @@ const SESSION_QUERY_DB = `session-query-${String(process.pid)}-${randomUUID()}.d // The harness checkout root: three hops up from apps/cli/{src,lib}, resolved // from this bin's location so it holds however `dsh` is launched (a PATH // symlink, an arbitrary cwd). The agent is told where its own source lives. -/** The harness checkout used as the `dsh meta` workspace and source prompt path. */ +/** The harness checkout used as the `dsh experimental-meta` workspace and source prompt path. */ export const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url)) /* v8 ignore start -- composition over the unit-tested dsh-app-boot helpers; @@ -76,10 +88,11 @@ export const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url)) * {@link CONFIGURED_AGENT_IDENTITIES_KEY}, so no config key selects the session * and an overlay replacing the agent row cannot drop it. * @param workspace - a directory to make the workspace instead of the invoking - * one, or `undefined` to keep the cwd. Only `dsh meta` passes it. + * one, or `undefined` to keep the cwd. Only `dsh experimental-meta` passes it. * @param initialSkill - a bundled skill to auto-invoke as a fresh session's - * first turn, or `undefined`. Set only by `dsh upgrade` and ignored on a resume, - * so it never re-fires; reaches the app through {@link INITIAL_SKILL_KEY}. + * first turn, or `undefined`. Set only by `dsh experimental-upgrade` and + * ignored on a resume, so it never re-fires; reaches the app through + * {@link INITIAL_SKILL_KEY}. * @param configReplace - a config path to boot as the ENTIRE tree, bypassing the * shared base, the TUI overlay, and the personal overlay alike, or `undefined` * to compose them; already parsed from `--config-replace`. @@ -111,6 +124,11 @@ export async function runTui( // both together. Sessions themselves live under the Harness home so `/resume` // spans every workspace, and are unaffected by this chdir. if (workspace !== undefined) process.chdir(workspace) + const dshHome = resolveDshHome() + const showFirstRunWelcome = !await hasTuiFirstRunWelcomeAcknowledgement( + dshHome, + TUI_FIRST_RUN_WELCOME_NOTICE_VERSION, + ) process.env.DSH_BUNDLED_SKILL_DIR = join(SOURCE_ROOT, 'skills') // The in-place `/resume` handoff re-execs `dsh` with a normalized `--resume` // flag, so the resumed process rehydrates through this same intake. The @@ -122,8 +140,9 @@ export async function runTui( const entry = process.argv[1] const execve = process.execve?.bind(process) const app: { current?: Context } = {} - // Resume always enters the default surface because meta rejects parent - // options, including `--resume`. The resumed session already persists its cwd. + // Resume always enters the default surface because experimental-meta rejects + // parent options, including `--resume`. The resumed session already persists + // its cwd. const resumeArgs = (sessionId: string): string[] => [ `--resume=${sessionId}`, // Both config flags must survive the handoff: resuming into a different @@ -229,5 +248,15 @@ export async function runTui( ) app.current = ctx addHarnessSourceSection(ctx, SOURCE_ROOT) + if (showFirstRunWelcome) { + await ctx.plugin({ + name: tuiFirstRunWelcomeName, + inject: tuiFirstRunWelcomeInject, + apply: applyTuiFirstRunWelcome, + }, { + dshHome, + asciiArt: needsTuiFirstRunWelcomeAsciiArt(), + }) + } } /* v8 ignore stop */ diff --git a/apps/cli/tests/args.spec.ts b/apps/cli/tests/args.spec.ts index cda7818e63..9da69fb91c 100644 --- a/apps/cli/tests/args.spec.ts +++ b/apps/cli/tests/args.spec.ts @@ -24,13 +24,13 @@ function exitCode(argv: string[]): number { afterEach(() => { vi.restoreAllMocks() }) describe('parseDshArgs', () => { - it('routes each mode by its shape: default TUI, -p headless, meta and web subcommands', () => { + it('routes each mode by its shape: default TUI, -p headless, experimental and web subcommands', () => { expect(parse([])).toEqual({ mode: 'tui' }) expect(parse(['--config', 'custom.yml'])).toEqual({ mode: 'tui', config: 'custom.yml' }) expect(parse(['--config-replace', 'tree.yml'])).toEqual({ mode: 'tui', configReplace: 'tree.yml' }) expect(parse(['--resume', 'sess', '--config', 'app.yml'])).toEqual({ mode: 'tui', config: 'app.yml', resume: 'sess' }) expect(parse(['-p', 'do the thing'])).toEqual({ mode: 'headless', prompt: 'do the thing' }) - expect(parse(['meta'])).toEqual({ mode: 'meta' }) + expect(parse(['experimental-meta'])).toEqual({ mode: 'meta' }) // Bare `web` carries no host/port: the shipped Web overlay owns the default. expect(parse(['web'])).toEqual({ mode: 'web', dev: false }) expect(parse(['web', '--config', 'web.yml'])).toEqual({ mode: 'web', dev: false, config: 'web.yml' }) @@ -39,7 +39,7 @@ describe('parseDshArgs', () => { expect(parse(['web', '--host', '0.0.0.0', '--port', '8080', '--dev', '--workspace-root', '/w'])) .toEqual({ mode: 'web', host: '0.0.0.0', port: 8080, dev: true, workspaceRoot: '/w' }) // Guided fresh-session entries carry nothing: bare mode discriminant only. - expect(parse(['upgrade'])).toEqual({ mode: 'upgrade' }) + expect(parse(['experimental-upgrade'])).toEqual({ mode: 'upgrade' }) // --trusted-host is variadic and repeatable; authorities pass through unvalidated. expect(parse(['web', '--trusted-host', 'harness.internal:3080', 'lab.internal', '--trusted-host', '10.0.0.9'])) .toEqual({ mode: 'web', dev: false, trustedHosts: ['harness.internal:3080', 'lab.internal', '10.0.0.9'] }) @@ -64,8 +64,8 @@ describe('parseDshArgs', () => { expect(exitCode(['web', '--dump-config', '--dump-default-config'])).toBe(1) expect(exitCode(['web', '--dump-default-config', '--config', 'w.yml'])).toBe(1) // A leaked dump flag on a subcommand that has none is a mistyped invocation. - expect(exitCode(['meta', '--dump-config'])).toBe(1) - expect(exitCode(['upgrade', '--dump-config'])).toBe(1) + expect(exitCode(['experimental-meta', '--dump-config'])).toBe(1) + expect(exitCode(['experimental-upgrade', '--dump-config'])).toBe(1) }) it('exits nonzero instead of silently starting fresh or dropping inputs', () => { @@ -88,17 +88,20 @@ describe('parseDshArgs', () => { expect(exitCode(['--config-replace', 'tree.yml', 'web'])).toBe(1) // Same rule for each subcommand that shares no option with the default // surface, so a leaked flag is a typo, not something to ignore. - // `meta` fixes its own config tree and always starts fresh, so every - // default-surface option is rejected. - expect(exitCode(['meta', '--resume', 's'])).toBe(1) - expect(exitCode(['meta', '--config', 'c.yml'])).toBe(1) - expect(exitCode(['meta', '--config-replace', 'tree.yml'])).toBe(1) - expect(exitCode(['meta', '-p', 'task'])).toBe(1) - // `upgrade` takes no options: any leaked default-surface flag is a - // mistyped invocation, not a silently-dropped input. - expect(exitCode(['upgrade', '--resume', 's'])).toBe(1) - expect(exitCode(['upgrade', '--config', 'c.yml'])).toBe(1) - expect(exitCode(['-p', 'task', 'upgrade'])).toBe(1) + // `experimental-meta` fixes its own config tree and always starts fresh, + // so every default-surface option is rejected. + expect(exitCode(['experimental-meta', '--resume', 's'])).toBe(1) + expect(exitCode(['experimental-meta', '--config', 'c.yml'])).toBe(1) + expect(exitCode(['experimental-meta', '--config-replace', 'tree.yml'])).toBe(1) + expect(exitCode(['experimental-meta', '-p', 'task'])).toBe(1) + // `experimental-upgrade` takes no options: any leaked default-surface flag + // is a mistyped invocation, not a silently-dropped input. + expect(exitCode(['experimental-upgrade', '--resume', 's'])).toBe(1) + expect(exitCode(['experimental-upgrade', '--config', 'c.yml'])).toBe(1) + expect(exitCode(['-p', 'task', 'experimental-upgrade'])).toBe(1) + // The pre-release command names have no compatibility aliases. + expect(exitCode(['meta'])).toBe(1) + expect(exitCode(['upgrade'])).toBe(1) }) it('exits 0 for --help (disclosing web) and --version', () => { diff --git a/apps/cli/tests/fixtures/composition-echo-llm.ts b/apps/cli/tests/fixtures/composition-echo-llm.ts new file mode 100644 index 0000000000..9b34754e10 --- /dev/null +++ b/apps/cli/tests/fixtures/composition-echo-llm.ts @@ -0,0 +1,51 @@ +import type { Context } from 'cordis' +import type { + GenerateOptions, + LlmModelInfo, + LlmResolvedModelInfo, + StreamChunk, +} from '@deepseek-ai/dsh-llm' +import { LlmAdapter } from '@deepseek-ai/dsh-llm' + +/** Terminal marker the preset smoke waits for before it asks the TUI to exit. */ +export const COMPOSITION_REPLY_TEXT = 'Shipped composition acknowledged.' + +// Provider id and model the keyless tail routes `main` to; that overlay is the +// only caller, so the pair lives here as plain constants. +const COMPOSITION_PROVIDER = 'composition-keyless' +const COMPOSITION_MODEL = 'composition-keyless-model' + +/** + * Network-free adapter for the shipped-composition smoke. It answers every + * request — tool-ful agent turns and the tool-less auxiliary calls alike — with + * one fixed text and never calls a tool, because the assertion under test is the + * assembled tool catalog the loop logs, not any tool's behavior. + */ +class CompositionEchoAdapter extends LlmAdapter { + override listModels(provider: string): Promise { + return Promise.resolve([{ provider, id: COMPOSITION_MODEL, name: 'Preset Keyless' }]) + } + + override resolveModel(provider: string, model: string): Promise { + return Promise.resolve({ provider, id: model, name: 'Preset Keyless', context: { contextWindow: 128_000 } }) + } + + override async * stream(_options: GenerateOptions): AsyncIterable { + yield { type: 'block-start', index: 0, blockType: 'text' } + for (const char of COMPOSITION_REPLY_TEXT) yield { type: 'text-delta', index: 0, text: char } + yield { type: 'block-end', index: 0, block: { type: 'text', text: COMPOSITION_REPLY_TEXT } } + yield { type: 'usage', usage: { inputTokens: 20, outputTokens: COMPOSITION_REPLY_TEXT.length } } + yield { type: 'finish', reason: { kind: 'stop' } } + } +} + +export const name = 'composition-echo-llm' +export const inject = ['llm'] + +/** + * Register the network-free adapter the shipped-composition smoke routes through. + * @param ctx - the loader-mounted plugin context. + */ +export function apply(ctx: Context): void { + ctx.llm.registerAdapter([COMPOSITION_PROVIDER], new CompositionEchoAdapter()) +} diff --git a/apps/cli/tests/fixtures/composition-keyless-tail.cordis.yml b/apps/cli/tests/fixtures/composition-keyless-tail.cordis.yml new file mode 100644 index 0000000000..443fed6be7 --- /dev/null +++ b/apps/cli/tests/fixtures/composition-keyless-tail.cordis.yml @@ -0,0 +1,52 @@ +# Keyless tail for the shipped-composition smoke, applied as `--config` so the +# launcher boots `base.cordis.yml` + `tui.cordis.yml` and then this file. +# +# Everything below is test isolation, never composition under test: the model is +# replaced so no request leaves the process, the settle marker gates the smoke's +# first prompt, and the session artifacts move into the smoke's temporary +# workspace so the log inspection can read them. + +# A patch's `name` is an assertion rather than a replacement, so the base +# adapter row is disabled and the scripted one inserted. Relative specifiers +# resolve against the INCLUDED file's directory (apps/cli/config), not this +# file's, because the include moves baseUrl there. +- id: llm-deepseek + disabled: true + +- insert: + - id: composition-echo-llm + name: '../tests/fixtures/composition-echo-llm.ts' + - id: composition-settled + name: '../tests/fixtures/composition-settled.ts' + +- id: agent-loop + config: + agents: + - id: main + provider: composition-keyless + model: composition-keyless-model + cwd: !!js process.cwd() + +- id: session-persistence-jsonl + config: + root: './.sessions' + compression: none + +- id: session-query-sqlite + config: + path: './.sessions/session-query.db' + +# The title call is a second, tool-less request that would race the log +# inspection for no coverage: the catalog under test rides the agent turn. +- id: session-title-llm + disabled: true + +- id: tui + config: + sessionId: !!js configuredAgentIdentities?.main?.id ?? 'main' + welcome: 'composition smoke ready.' + showReasoning: true + +# HMR watches the repository; a PTY subprocess test must not start a watcher. +- id: hmr + disabled: true diff --git a/apps/cli/tests/fixtures/composition-settled.ts b/apps/cli/tests/fixtures/composition-settled.ts new file mode 100644 index 0000000000..0e3aff9c4e --- /dev/null +++ b/apps/cli/tests/fixtures/composition-settled.ts @@ -0,0 +1,24 @@ +import type { Context } from 'cordis' + +/** + * Marker the shipped-composition smoke gates its first prompt on. The TUI renders as soon as + * its own fiber starts, so a prompt typed at the banner can reach the loop while + * later rows — tool plugins, persistence — are still activating, and would + * assemble a partial catalog. Waiting for this line makes the turn observe the + * settled tree. + */ +export const COMPOSITION_SETTLED_MARKER = 'COMPOSITION_TREE_SETTLED' + +export const name = 'composition-settled' + +/** + * Announce settled Loader activation on the terminal byte stream, after every + * entry in the booted tree has started. The write is detached: awaiting the + * Loader from inside an entry would wait on this entry's own activation. + * @param ctx - the loader-mounted plugin context. + */ +export function apply(ctx: Context): void { + void ctx.loader.await().then(() => { + process.stdout.write(`\n${COMPOSITION_SETTLED_MARKER}\n`) + }) +} diff --git a/apps/cli/tests/pty-harness.ts b/apps/cli/tests/pty-harness.ts index a6c33160fa..07361cf654 100644 --- a/apps/cli/tests/pty-harness.ts +++ b/apps/cli/tests/pty-harness.ts @@ -6,11 +6,11 @@ import { execa } from 'execa' import { resolveExampleLaunch, type ExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' const POSIX_PTY_DRIVER = String.raw` -import errno, json, os, pty, select, signal, sys, time -node, launch_args_json, launch_env_json, cwd, actions_json, expected_exit, timeout_seconds = sys.argv[1:] +import errno, fcntl, json, os, pty, select, signal, struct, sys, termios, time +node, launch_args_json, launch_env_json, cwd, actions_json, expected_exit, timeout_seconds, columns, rows = sys.argv[1:] env = os.environ.copy() env.update(json.loads(launch_env_json)) -env.update({"COLUMNS": "100", "LINES": "30"}) +env.update({"COLUMNS": columns, "LINES": rows}) # Deterministic banner: a developer shell's COLORTERM=truecolor would switch the # banner to the per-letter gradient (one SGR per letter), breaking literal # DEEPSEEK assertions. The gradient path has its own unit and snapshot coverage. @@ -20,6 +20,7 @@ pid, fd = pty.fork() if pid == 0: os.chdir(cwd) os.execvpe(node, [node, *json.loads(launch_args_json)], env) +fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", int(rows), int(columns), 0, 0)) output = bytearray() action_index = 0 @@ -36,9 +37,14 @@ while time.monotonic() < deadline: chunk = b"" if chunk: output.extend(chunk) - while action_index < len(actions) and actions[action_index]["waitFor"].encode() in output: + while action_index < len(actions): + marker = actions[action_index]["waitFor"].encode() + if output.count(marker) < actions[action_index].get("occurrence", 1): + break action = actions[action_index] - if "writeFile" in action: + if "signal" in action: + os.kill(pid, getattr(signal, action["signal"])) + elif "writeFile" in action: target = os.path.join(cwd, action["writeFile"]["path"]) os.makedirs(os.path.dirname(target), exist_ok=True) with open(target, "w", encoding="utf-8") as handle: @@ -68,9 +74,15 @@ if actual_exit != int(expected_exit): /** One terminal input or workspace mutation performed after its marker renders. */ type TuiPtyAction = - | { readonly waitFor: string; readonly send: string } | { readonly waitFor: string + readonly occurrence?: number + readonly send: string + } + | { readonly waitFor: string; readonly occurrence?: number; readonly signal: 'SIGTERM' } + | { + readonly waitFor: string + readonly occurrence?: number readonly writeFile: { readonly path: string; readonly content: string } readonly send?: string } @@ -89,6 +101,12 @@ export interface TuiPtySmokeOptions { readonly env?: Readonly readonly expectedExitCode?: number readonly timeoutMs?: number + /** Existing isolated workspace to reuse; when omitted the harness creates and removes one. */ + readonly cwd?: string + /** Pseudo-terminal columns; defaults to 100. */ + readonly columns?: number + /** Pseudo-terminal rows; defaults to 30. */ + readonly rows?: number /** Seed the isolated workspace (`cwd`, with `$DSH_HOME` at `.dsh` and the agents home at `.agents`) before launch. */ readonly prepare?: (cwd: string) => Promise /** Inspect the workspace after a passing run, before the temp dir is removed. */ @@ -119,6 +137,8 @@ async function runPosixPtySmoke( JSON.stringify(options.actions ?? []), String(options.expectedExitCode ?? 0), String(timeoutMs / 1_000), + String(options.columns ?? 100), + String(options.rows ?? 30), ], { stdin: 'ignore', timeout: timeoutMs + 5_000, @@ -150,8 +170,8 @@ async function runWindowsPtySmoke( let timedOut = false const terminal = pty.spawn(launch.command, launch.args, { name: 'xterm-256color', - cols: 100, - rows: 30, + cols: options.columns ?? 100, + rows: options.rows ?? 30, cwd, env: definedEnv({ ...process.env, @@ -159,8 +179,8 @@ async function runWindowsPtySmoke( // Match the POSIX driver: no COLORTERM, so the banner never takes the // truecolor gradient path under a developer's shell. COLORTERM: undefined, - COLUMNS: '100', - LINES: '30', + COLUMNS: String(options.columns ?? 100), + LINES: String(options.rows ?? 30), }), }) const timer = setTimeout(() => { @@ -169,9 +189,14 @@ async function runWindowsPtySmoke( }, timeoutMs) terminal.onData((chunk) => { output += chunk - while (actionIndex < actions.length && output.includes(actions[actionIndex]!.waitFor)) { + while ( + actionIndex < actions.length + && output.split(actions[actionIndex]!.waitFor).length - 1 >= (actions[actionIndex]!.occurrence ?? 1) + ) { const action = actions[actionIndex]! - if ('writeFile' in action) { + if ('signal' in action) { + terminal.kill(action.signal) + } else if ('writeFile' in action) { const target = join(cwd, action.writeFile.path) mkdirSync(dirname(target), { recursive: true }) writeFileSync(target, action.writeFile.content) @@ -205,7 +230,8 @@ async function runWindowsPtySmoke( * @returns complete pseudo-terminal output. */ export async function runTuiPtySmoke(options: TuiPtySmokeOptions): Promise { - const cwd = await mkdtemp(join(tmpdir(), options.tempDirPrefix)) + const ownedCwd = options.cwd === undefined + const cwd = options.cwd ?? await mkdtemp(join(tmpdir(), options.tempDirPrefix)) const timeoutMs = options.timeoutMs ?? 25_000 try { await options.prepare?.(cwd) @@ -231,6 +257,6 @@ export async function runTuiPtySmoke(options: TuiPtySmokeOptions): Promise +} + +/** + * Read the request header the loop assembled for its first request from the + * session log the smoke's workspace persisted — the model-visible composition + * itself, not a registry projection taken beside it. + * @param cwd - the smoke's temporary workspace. + * @returns the assembled catalog, system prompt, and `bash` argument shape. + */ +async function loggedHeader(cwd: string): Promise { + const sessionsDir = join(cwd, '.sessions') + const entries = await readdir(sessionsDir, { recursive: true }) + // A single keyless run writes one session log. + const logRelPath = entries.find(name => name.endsWith('.jsonl')) + if (logRelPath === undefined) throw new Error(`no session log written under ${sessionsDir}`) + const lines = (await readFile(join(sessionsDir, logRelPath), 'utf8')).split('\n').filter(Boolean) + for (const line of lines) { + const event = JSON.parse(line) as SessionEvent + if (event.type !== 'request/header') continue + const tools = event.data.header.tools ?? [] + const bash = tools.find(schema => schema.name === 'bash') + return { + names: tools.map(schema => schema.name).sort(), + bashArguments: (bash?.parameters as { properties?: Record } | undefined)?.properties ?? {}, + } + } + throw new Error(`session log ${logRelPath} has no request/header event`) +} + +describe('shipped dsh composition (real Loader tree in a PTY)', () => { + it('assembles exactly the shipped TUI catalog', async () => { + let observed: LoggedHeader | undefined + const output = await runTuiPtySmoke({ + label: 'dsh shipped composition', + tempDirPrefix: 'dsh-shipped-tui-', + binScript: dshBinScript, + tsconfigPath, + configPath: keylessTail, + env: { DEEPSEEK_API_KEY: 'keyless-composition-no-call', DSH_TELEMETRY_DISABLED: '1' }, + prepare: cwd => acknowledgeTuiFirstRunWelcome(join(cwd, '.dsh')), + // Artifact CI builds and smokes concurrently on a contended runner. + ...(process.env.DSH_EXAMPLE_MODE === 'lib' ? { timeoutMs: 60_000 } : {}), + actions: [ + { waitFor: COMPOSITION_SETTLED_MARKER, send: 'Describe the shipped composition.\r' }, + { waitFor: COMPOSITION_REPLY_TEXT, send: '/exit\r' }, + ], + inspect: async (cwd) => { observed = await loggedHeader(cwd) }, + }) + expect(output).toContain(COMPOSITION_REPLY_TEXT) + expect(observed?.names.filter(name => !RIPGREP_TOOLS.includes(name))).toEqual(EXPECTED_TUI_TOOLS) + expect([[], RIPGREP_TOOLS]).toContainEqual(observed?.names.filter(name => RIPGREP_TOOLS.includes(name))) + // The TUI mounts the unrestricted local executors, so `tool-bash` emits no + // escalation pair. Pinning its absence keeps a later sandbox change from + // arriving here unannounced. + expect(Object.keys(observed?.bashArguments ?? {})).not.toContain('sandbox_permissions') + }, LOADER_SMOKE_TEST_TIMEOUT_MS) +}) diff --git a/apps/cli/tests/snapshots/queued-manual-compact/terminal.expected.txt b/apps/cli/tests/snapshots/queued-manual-compact/terminal.expected.txt new file mode 100644 index 0000000000..0df46a7018 --- /dev/null +++ b/apps/cli/tests/snapshots/queued-manual-compact/terminal.expected.txt @@ -0,0 +1,128 @@ +terminal 100x36 buffer=normal length=66 base=30 viewport=30 +lifecycle started=1 stopped=0 progress=inactive +title "Reply with exactly the word: — DSH TUI snapshot" +cursor hidden column=7 viewportRow=35 bufferRow=65 +buffer +0| " DEEPSEEK HARNESS" + style 1-8 fg=bright-magenta bold + style 10-16 bold +1| " Reply with exactly the word:" + style 1-28 dim +2| " main-session" + style 1-12 dim +3| +4| "Context · snapshot-seed" + style 0-22 dim +5| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +6| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +7| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +8| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +9| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +10| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +11| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +12| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +13| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +14| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +15| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +16| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +17| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +18| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-99 dim +19| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context. " + style 0-94 dim +20| +21| "You " + style 0-2 fg=bright-magenta bold underline +22| "Reply with exactly the word: ONE. No tools. " +23| +24| "Assistant " + style 0-8 fg=bright-magenta bold underline +25| "Reasoning " + style 0-8 dim italic +26| "The user wants me to reply with exactly the word \"ONE\" and use no tools. " + style 0-71 dim italic +27| "ONE " +28| "Model wait 0.0s · Completed 2026-07-21 12:00:00 " + style 0-46 dim +29| +30| "Keyboard shortcuts " + style 0-17 fg=bright-magenta bold +31| "Enter send • Shift/Alt+Enter newline • Up/Down prompt history " + style 0-60 dim +32| "Esc cancel turn • Ctrl+O cycle cards (collapse/expand/hide) • Ctrl+R toggle reasoning • Ctrl+L " + style 0-99 dim +33| "redraw " + style 0-5 dim +34| "Ctrl+C cancel while running; clear input or exit while idle • Ctrl+D exit " + style 0-72 dim +35| " " +36| "/clear — Clear the transcript view (session history is unchanged) " + style 0-64 dim +37| "/compact — Compact older conversation history " + style 0-44 dim +38| "/exit — Exit after the active turn reaches idle " + style 0-46 dim +39| "/help — Show keyboard shortcuts and commands " + style 0-43 dim +40| "/model [[provider/]model] — Show or switch this session's model " + style 0-62 dim +41| "/palette — Show every color and attribute role this terminal renders " + style 0-67 dim +42| "/quit — Exit after the active turn reaches idle " + style 0-46 dim +43| "/reload — EXPERIMENTAL (dev): re-read loader config files and apply the diff (idle only) " + style 0-87 dim +44| "/resume — List this workspace's resumable sessions " + style 0-49 dim +45| "/status — Show session diagnostics, system prompt, and registered tools " + style 0-70 dim +46| "/skill: [instructions] — load a skill into the conversation " + style 0-64 dim +47| +48| "Context · snapshot-injector" + style 0-26 dim +49| "Injected while compaction was running. " + style 0-37 dim +50| +51| "… earlier context was compacted … " + style 0-32 dim +52| +53| "You " + style 0-2 fg=bright-magenta bold underline +54| "Reply with exactly the word: TWO. No tools. " +55| +56| "Compacted 2 history items (~387 tokens). " + style 0-39 dim +57| +58| "Assistant " + style 0-8 fg=bright-magenta bold underline +59| "Reasoning " + style 0-8 dim italic +60| "The user wants me to reply with exactly the word \"TWO\" and no tools. " + style 0-67 dim italic +61| "TWO " +62| "Model wait 0.0s · Completed 2026-07-21 12:00:00 " + style 0-46 dim +63| +64| "/workspace/project deepseek-v4-flash ↑2.9k ↓41 cache 49% 3% cont" + style 0-49 fg=bright-magenta bold + style 52-68 dim + style 71-90 dim + style 93-99 dim +65| " dsh ◍ " + style 1-3 fg=bright-magenta bold + style 5-6 dim + style 7-7 inverse diff --git a/apps/cli/tests/tui-first-run-snapshots/120-columns.expected.txt b/apps/cli/tests/tui-first-run-snapshots/120-columns.expected.txt new file mode 100644 index 0000000000..9a5051ceb3 --- /dev/null +++ b/apps/cli/tests/tui-first-run-snapshots/120-columns.expected.txt @@ -0,0 +1,76 @@ +overlay 120x30 rows=20 +0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮" + style 0-119 dim +1| "│ ▄ DeepSeek Harness │" + style 0-0 dim + style 10-37 fg=blue + style 75-90 fg=blue bold + style 119-119 dim +2| "│ ▄▄▄▄▄▄▄▄▄▄███▀ ██▄ │" + style 0-0 dim + style 9-38 fg=blue + style 119-119 dim +3| "│ ▄███████████████▄ ████▄ ▄▄▄▄██ 感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部测试阶段，功能 │" + style 0-0 dim + style 4-43 fg=blue + style 119-119 dim +4| "│ ▄███████████████████▄ ████████████▀ 仍待完善，体验难免有些粗糙。 │" + style 0-0 dim + style 4-43 fg=blue + style 119-119 dim +5| "│ ▄██████████████████████▄ ▀█████████▀ │" + style 0-0 dim + style 4-42 fg=blue + style 119-119 dim +6| "│ ▄███▀█████████████████████▄ ████▀▀ “如切如磋，如琢如磨。” │" + style 0-0 dim + style 6-41 fg=blue + style 49-70 bold + style 119-119 dim +7| "│ ███ ▀▀█████████▀▀▀█████████▀ │" + style 0-0 dim + style 7-40 fg=blue + style 119-119 dim +8| "│ ███ ▀███████▀█ ▀███████ 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中发现的 │" + style 0-0 dim + style 7-39 fg=blue + style 119-119 dim +9| "│ ███▄ ▀███████▄ ▀█████▀ 问题，也可能促使我们重新审视，甚至推翻已有的设计。 │" + style 0-0 dim + style 7-39 fg=blue + style 119-119 dim +10| "│ ▀███ ▀██████████████ │" + style 0-0 dim + style 8-39 fg=blue + style 119-119 dim +11| "│ ▀███▄ ▀███████████▀ 为了帮助我们更准确地还原您真实使用中的问题，内测版本默认会上传所有 │" + style 0-0 dim + style 8-38 fg=blue + style 119-119 dim +12| "│ ▀███▄ ▄▄▄ ▀████████▀ Session Log；如需关闭，请设置环境变量 DSH_TELEMETRY_DISABLED=1。另外 │" + style 0-0 dim + style 9-38 fg=blue + style 119-119 dim +13| "│ █████▄ ███▄▄ ▀█████▄▄ ，如果您有任何反馈与建议，请在企业微信群中留言告诉我们。每一条反馈， │" + style 0-0 dim + style 9-38 fg=blue + style 119-119 dim +14| "│ ▀█████████████▄▄▄▄█▀█████▀ 都会帮助我们把它打磨得更好。 │" + style 0-0 dim + style 8-39 fg=blue + style 119-119 dim +15| "│ ▀▀███████████▀▀ │" + style 0-0 dim + style 12-34 fg=blue + style 119-119 dim +16| "├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤" + style 0-119 dim +17| "│ Enter 继续 │" + style 0-0 dim + style 54-64 fg=bright-magenta bold + style 119-119 dim +18| "│ │" + style 0-0 dim + style 119-119 dim +19| "╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯" + style 0-119 dim diff --git a/apps/cli/tests/tui-first-run-snapshots/160-columns.expected.txt b/apps/cli/tests/tui-first-run-snapshots/160-columns.expected.txt new file mode 100644 index 0000000000..a374d14da8 --- /dev/null +++ b/apps/cli/tests/tui-first-run-snapshots/160-columns.expected.txt @@ -0,0 +1,76 @@ +overlay 160x30 rows=20 +0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮" + style 0-159 dim +1| "│ ▄ DeepSeek Harness │" + style 0-0 dim + style 10-37 fg=blue + style 95-110 fg=blue bold + style 159-159 dim +2| "│ ▄▄▄▄▄▄▄▄▄▄███▀ ██▄ │" + style 0-0 dim + style 9-38 fg=blue + style 159-159 dim +3| "│ ▄███████████████▄ ████▄ ▄▄▄▄██ 感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部测试阶段，功能仍待完善，体验难免有些粗糙。 │" + style 0-0 dim + style 4-43 fg=blue + style 159-159 dim +4| "│ ▄███████████████████▄ ████████████▀ │" + style 0-0 dim + style 4-43 fg=blue + style 159-159 dim +5| "│ ▄██████████████████████▄ ▀█████████▀ “如切如磋，如琢如磨。” │" + style 0-0 dim + style 4-42 fg=blue + style 49-70 bold + style 159-159 dim +6| "│ ▄███▀█████████████████████▄ ████▀▀ │" + style 0-0 dim + style 6-41 fg=blue + style 159-159 dim +7| "│ ███ ▀▀█████████▀▀▀█████████▀ 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中发现的问题，也可能促使我们重新审视，甚至推翻已 │" + style 0-0 dim + style 7-40 fg=blue + style 159-159 dim +8| "│ ███ ▀███████▀█ ▀███████ 有的设计。 │" + style 0-0 dim + style 7-39 fg=blue + style 159-159 dim +9| "│ ███▄ ▀███████▄ ▀█████▀ │" + style 0-0 dim + style 7-39 fg=blue + style 159-159 dim +10| "│ ▀███ ▀██████████████ 为了帮助我们更准确地还原您真实使用中的问题，内测版本默认会上传所有 Session Log；如需关闭，请设置环境变量 │" + style 0-0 dim + style 8-39 fg=blue + style 159-159 dim +11| "│ ▀███▄ ▀███████████▀ DSH_TELEMETRY_DISABLED=1。另外，如果您有任何反馈与建议，请在企业微信群中留言告诉我们。每一条反馈，都会帮助我 │" + style 0-0 dim + style 8-38 fg=blue + style 159-159 dim +12| "│ ▀███▄ ▄▄▄ ▀████████▀ 们把它打磨得更好。 │" + style 0-0 dim + style 9-38 fg=blue + style 159-159 dim +13| "│ █████▄ ███▄▄ ▀█████▄▄ │" + style 0-0 dim + style 9-38 fg=blue + style 159-159 dim +14| "│ ▀█████████████▄▄▄▄█▀█████▀ │" + style 0-0 dim + style 8-39 fg=blue + style 159-159 dim +15| "│ ▀▀███████████▀▀ │" + style 0-0 dim + style 12-34 fg=blue + style 159-159 dim +16| "├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤" + style 0-159 dim +17| "│ Enter 继续 │" + style 0-0 dim + style 74-84 fg=bright-magenta bold + style 159-159 dim +18| "│ │" + style 0-0 dim + style 159-159 dim +19| "╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯" + style 0-159 dim diff --git a/apps/cli/tests/tui-first-run-snapshots/60-columns-low-height.expected.txt b/apps/cli/tests/tui-first-run-snapshots/60-columns-low-height.expected.txt new file mode 100644 index 0000000000..bdf8a46a6f --- /dev/null +++ b/apps/cli/tests/tui-first-run-snapshots/60-columns-low-height.expected.txt @@ -0,0 +1,31 @@ +overlay 60x12 rows=10 +0| "╭──────────────────────────────────────────────────────────╮" + style 0-59 dim +1| "│ DeepSeek Harness │" + style 0-0 dim + style 22-37 fg=blue bold + style 59-59 dim +2| "│ │" + style 0-0 dim + style 59-59 dim +3| "│ 感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部 │" + style 0-0 dim + style 59-59 dim +4| "│ 测试阶段，功能仍待完善，体验难免有些粗糙。 │" + style 0-0 dim + style 59-59 dim +5| "│ │" + style 0-0 dim + style 59-59 dim +6| "├──────────────────────────────────────────────────────────┤" + style 0-59 dim +7| "│ Enter 继续 │" + style 0-0 dim + style 24-34 fg=bright-magenta bold + style 59-59 dim +8| "│ ↑/↓ 滚动 ↓ │" + style 0-0 dim + style 24-35 dim + style 59-59 dim +9| "╰──────────────────────────────────────────────────────────╯" + style 0-59 dim diff --git a/apps/cli/tests/tui-first-run-snapshots/60-columns.expected.txt b/apps/cli/tests/tui-first-run-snapshots/60-columns.expected.txt new file mode 100644 index 0000000000..ae53f4bfda --- /dev/null +++ b/apps/cli/tests/tui-first-run-snapshots/60-columns.expected.txt @@ -0,0 +1,64 @@ +overlay 60x30 rows=21 +0| "╭──────────────────────────────────────────────────────────╮" + style 0-59 dim +1| "│ DeepSeek Harness │" + style 0-0 dim + style 22-37 fg=blue bold + style 59-59 dim +2| "│ │" + style 0-0 dim + style 59-59 dim +3| "│ 感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部 │" + style 0-0 dim + style 59-59 dim +4| "│ 测试阶段，功能仍待完善，体验难免有些粗糙。 │" + style 0-0 dim + style 59-59 dim +5| "│ │" + style 0-0 dim + style 59-59 dim +6| "│ “如切如磋，如琢如磨。” │" + style 0-0 dim + style 2-23 bold + style 59-59 dim +7| "│ │" + style 0-0 dim + style 59-59 dim +8| "│ 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实 │" + style 0-0 dim + style 59-59 dim +9| "│ 使用中发现的问题，也可能促使我们重新审视，甚至推翻已有的 │" + style 0-0 dim + style 59-59 dim +10| "│ 设计。 │" + style 0-0 dim + style 59-59 dim +11| "│ │" + style 0-0 dim + style 59-59 dim +12| "│ 为了帮助我们更准确地还原您真实使用中的问题，内测版本默认 │" + style 0-0 dim + style 59-59 dim +13| "│ 会上传所有 Session Log；如需关闭，请设置环境变量 │" + style 0-0 dim + style 59-59 dim +14| "│ DSH_TELEMETRY_DISABLED=1。另外，如果您有任何反馈与建议， │" + style 0-0 dim + style 59-59 dim +15| "│ 请在企业微信群中留言告诉我们。每一条反馈，都会帮助我们把 │" + style 0-0 dim + style 59-59 dim +16| "│ 它打磨得更好。 │" + style 0-0 dim + style 59-59 dim +17| "├──────────────────────────────────────────────────────────┤" + style 0-59 dim +18| "│ Enter 继续 │" + style 0-0 dim + style 24-34 fg=bright-magenta bold + style 59-59 dim +19| "│ │" + style 0-0 dim + style 59-59 dim +20| "╰──────────────────────────────────────────────────────────╯" + style 0-59 dim diff --git a/apps/cli/tests/tui-first-run-snapshots/80-columns.expected.txt b/apps/cli/tests/tui-first-run-snapshots/80-columns.expected.txt new file mode 100644 index 0000000000..c3a8b5d496 --- /dev/null +++ b/apps/cli/tests/tui-first-run-snapshots/80-columns.expected.txt @@ -0,0 +1,89 @@ +overlay 80x30 rows=27 +0| "╭──────────────────────────────────────────────────────────────────────────────╮" + style 0-79 dim +1| "│ ▄▄▄▄▄▄ ▄▄ │" + style 0-0 dim + style 33-46 fg=blue + style 79-79 dim +2| "│ ▄████████▄ ▀████▀ │" + style 0-0 dim + style 31-48 fg=blue + style 79-79 dim +3| "│ █▀▀▀▀███████▄██▀ │" + style 0-0 dim + style 32-47 fg=blue + style 79-79 dim +4| "│ █▄ ▀███ ▀███ │" + style 0-0 dim + style 32-46 fg=blue + style 79-79 dim +5| "│ ▀█▄ ▀█████ │" + style 0-0 dim + style 33-46 fg=blue + style 79-79 dim +6| "│ ▀█▄▄ █▄▄▀███▄ │" + style 0-0 dim + style 33-46 fg=blue + style 79-79 dim +7| "│ ▀▀▀▀▀▀ │" + style 0-0 dim + style 35-44 fg=blue + style 79-79 dim +8| "│ │" + style 0-0 dim + style 79-79 dim +9| "│ DeepSeek Harness │" + style 0-0 dim + style 32-47 fg=blue bold + style 79-79 dim +10| "│ │" + style 0-0 dim + style 79-79 dim +11| "│ 感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部测试阶段，功能仍待完 │" + style 0-0 dim + style 79-79 dim +12| "│ 善，体验难免有些粗糙。 │" + style 0-0 dim + style 79-79 dim +13| "│ │" + style 0-0 dim + style 79-79 dim +14| "│ “如切如磋，如琢如磨。” │" + style 0-0 dim + style 2-23 bold + style 79-79 dim +15| "│ │" + style 0-0 dim + style 79-79 dim +16| "│ 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中发现的问题，也 │" + style 0-0 dim + style 79-79 dim +17| "│ 可能促使我们重新审视，甚至推翻已有的设计。 │" + style 0-0 dim + style 79-79 dim +18| "│ │" + style 0-0 dim + style 79-79 dim +19| "│ 为了帮助我们更准确地还原您真实使用中的问题，内测版本默认会上传所有 Session │" + style 0-0 dim + style 79-79 dim +20| "│ Log；如需关闭，请设置环境变量 DSH_TELEMETRY_DISABLED=1。另外，如果您有任何反 │" + style 0-0 dim + style 79-79 dim +21| "│ 馈与建议，请在企业微信群中留言告诉我们。每一条反馈，都会帮助我们把它打磨得更 │" + style 0-0 dim + style 79-79 dim +22| "│ 好。 │" + style 0-0 dim + style 79-79 dim +23| "├──────────────────────────────────────────────────────────────────────────────┤" + style 0-79 dim +24| "│ Enter 继续 │" + style 0-0 dim + style 34-44 fg=bright-magenta bold + style 79-79 dim +25| "│ │" + style 0-0 dim + style 79-79 dim +26| "╰──────────────────────────────────────────────────────────────────────────────╯" + style 0-79 dim diff --git a/apps/cli/tests/tui-first-run-welcome.spec.ts b/apps/cli/tests/tui-first-run-welcome.spec.ts new file mode 100644 index 0000000000..984ab15a03 --- /dev/null +++ b/apps/cli/tests/tui-first-run-welcome.spec.ts @@ -0,0 +1,346 @@ +import { createHash } from 'node:crypto' +import { mkdir, mkdtemp, readFile, rm, stat } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, describe, expect, it, vi } from 'vitest' +import type { Context } from 'cordis' +import { visibleWidth } from '@earendil-works/pi-tui' +import { + type TuiOverlayHost, + type TuiOverlayRequest, + type TuiTheme, +} from '@deepseek-ai/dsh-tui' +import { + acknowledgeTuiFirstRunWelcome, + apply, + hasTuiFirstRunWelcomeAcknowledgement, + needsTuiFirstRunWelcomeAsciiArt, + TuiFirstRunWelcomeComponent, + tuiFirstRunWelcomeAcknowledgementPath, + tuiFirstRunWelcomeArtTier, +} from '../src/tui-onboarding/tui-first-run-welcome.ts' +import { + TUI_FIRST_RUN_WELCOME_NOTICE_COPY, + TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE, + TUI_FIRST_RUN_WELCOME_NOTICE_VERSION, +} from '../src/tui-onboarding/tui-first-run-welcome-copy.ts' +import { TUI_FIRST_RUN_WELCOME_WHALE } from '../src/tui-onboarding/tui-first-run-welcome-art.ts' + +const mockDisposeRootAndExit = vi.hoisted(() => vi.fn()) +vi.mock('@deepseek-ai/dsh-tui', async importOriginal => ({ + ...await importOriginal(), + disposeRootAndExit: mockDisposeRootAndExit, +})) + +const identityTheme: TuiTheme = Object.freeze({ + text: (value: string) => value, + brand: (value: string) => value, + dim: (value: string) => value, + accent: (value: string) => value, + success: (value: string) => value, + warning: (value: string) => value, + error: (value: string) => value, + bold: (value: string) => value, +}) + +function hostFixture(rows: number): { + host: TuiOverlayHost + closed: () => boolean + invalidations: () => number +} { + let closed = false + let invalidations = 0 + const controller = new AbortController() + return { + host: Object.freeze({ + signal: controller.signal, + viewport: Object.freeze({ columns: 160, rows }), + theme: identityTheme, + display: (value: string) => value, + invalidate: () => { invalidations += 1 }, + close: () => { closed = true }, + }), + closed: () => closed, + invalidations: () => invalidations, + } +} + +const copy = TUI_FIRST_RUN_WELCOME_NOTICE_COPY[TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE] +const openingSentence = `${copy.paragraphs[0]!.split('。', 1)[0]}。` +const temporaryHomes: string[] = [] + +function artAnchor(tier: keyof typeof TUI_FIRST_RUN_WELCOME_WHALE): string { + return TUI_FIRST_RUN_WELCOME_WHALE[tier].unicode[tier === 'full' ? 2 : 0]!.trim() +} + +function withoutWhitespace(value: string): string { + return value.replace(/\s/gu, '') +} + +async function temporaryHome(prefix: string): Promise { + const home = await mkdtemp(join(tmpdir(), prefix)) + temporaryHomes.push(home) + return home +} + +afterEach(async () => { + mockDisposeRootAndExit.mockClear() + await Promise.all(temporaryHomes.splice(0).map(home => rm(home, { recursive: true, force: true }))) +}) + +describe('TUI first-run welcome acknowledgement', () => { + it('publishes one immutable per-version marker safely across concurrent acknowledgements', async () => { + const home = await temporaryHome('dsh-tui-welcome-ack-') + expect(await hasTuiFirstRunWelcomeAcknowledgement(home)).toBe(false) + + await Promise.all(Array.from({ length: 8 }, () => acknowledgeTuiFirstRunWelcome(home))) + + expect(await hasTuiFirstRunWelcomeAcknowledgement(home)).toBe(true) + const info = await stat(tuiFirstRunWelcomeAcknowledgementPath(home, TUI_FIRST_RUN_WELCOME_NOTICE_VERSION)) + expect(info.isFile()).toBe(true) + if (process.platform !== 'win32') expect(info.mode & 0o777).toBe(0o600) + }) + + it('treats a notice-version bump as a new one-time acknowledgement', async () => { + const home = await temporaryHome('dsh-tui-welcome-version-') + await acknowledgeTuiFirstRunWelcome(home) + const nextVersion = TUI_FIRST_RUN_WELCOME_NOTICE_VERSION + 1 + + expect(await hasTuiFirstRunWelcomeAcknowledgement(home, nextVersion)).toBe(false) + await acknowledgeTuiFirstRunWelcome(home, nextVersion) + expect(await hasTuiFirstRunWelcomeAcknowledgement(home, nextVersion)).toBe(true) + }) + + it('rejects a malformed marker instead of silently acknowledging it', async () => { + const home = await temporaryHome('dsh-tui-welcome-malformed-') + await mkdir(tuiFirstRunWelcomeAcknowledgementPath(home, TUI_FIRST_RUN_WELCOME_NOTICE_VERSION), { + recursive: true, + }) + await expect(hasTuiFirstRunWelcomeAcknowledgement(home)).rejects.toThrow('is not a file') + await expect(acknowledgeTuiFirstRunWelcome(home)).rejects.toThrow() + }) + + it('detects only explicit ASCII-only terminal environments', () => { + expect(needsTuiFirstRunWelcomeAsciiArt({ TERM: 'dumb' })).toBe(true) + expect(needsTuiFirstRunWelcomeAsciiArt({ LC_ALL: 'C' })).toBe(true) + expect(needsTuiFirstRunWelcomeAsciiArt({ LC_CTYPE: 'POSIX' })).toBe(true) + expect(needsTuiFirstRunWelcomeAsciiArt({ LANG: 'C' })).toBe(true) + expect(needsTuiFirstRunWelcomeAsciiArt({ LANG: 'en_US.UTF-8' })).toBe(false) + expect(typeof needsTuiFirstRunWelcomeAsciiArt()).toBe('boolean') + }) +}) + +describe('TUI first-run welcome composition', () => { + it('pins the supplied official icon and exact Chinese copy at their owner boundaries', async () => { + const icon = (await readFile(new URL('../assets/deepseek-color.svg', import.meta.url), 'utf8')).trimEnd() + expect(createHash('sha256').update(icon).digest('hex')) + .toBe('deba5f98a5c1796e20fcac3149bcd7eb8a32f0bdd04d048819400b1f28bd1439') + expect(createHash('sha256').update(copy.paragraphs.join('\n')).digest('hex')) + .toBe('99f9a828b4f083b28de21bf5e03f939c00238531e765db78911957c44c6e98da') + expect(TUI_FIRST_RUN_WELCOME_NOTICE_COPY.en).toBe(copy) + }) + + it.each([ + { columns: 60, inner: 50, rows: 30, tier: undefined }, + { columns: 80, inner: 68, rows: 30, tier: 'minimal' }, + { columns: 100, inner: 84, rows: 34, tier: 'compact' }, + { columns: 120, inner: 104, rows: 30, tier: 'full' }, + { columns: 160, inner: 140, rows: 30, tier: 'full' }, + ] as const)('renders the responsive composition at $columns columns without overdraw', ({ inner, rows, tier }) => { + const fixture = hostFixture(rows) + const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, async () => {}, () => {}) + const renderWidth = inner + 4 + const lines = component.render(renderWidth) + + expect(tuiFirstRunWelcomeArtTier(inner, rows)).toBe(tier) + expect(lines.every(line => visibleWidth(line) <= renderWidth)).toBe(true) + if (tier === undefined) { + expect(lines.join('\n')).not.toMatch(/[▀▄█]/u) + } else { + expect(lines.join('\n')).toContain(artAnchor(tier)) + } + const rendered = lines.join('\n') + const optOut = copy.paragraphs.at(-1)!.match(/[A-Z_]+=1/u)![0] + expect(rendered).not.toContain(copy.scrollHint) + expect(rendered).toContain(copy.paragraphs.at(-1)!.match(/[A-Za-z]+ [A-Za-z]+/u)![0]) + expect(rendered).toContain(optOut) + expect(lines.join('\n')).toContain(`Enter ${copy.continueLabel}`) + expect(lines.length).toBeLessThanOrEqual(Math.floor(rows * 0.9)) + expect(lines.length).toBeGreaterThan(5) + }) + + it.each([ + { inner: 68, rows: 14, tier: undefined }, + { inner: 68, rows: 17, tier: undefined }, + { inner: 68, rows: 18, tier: 'minimal' }, + { inner: 84, rows: 21, tier: 'minimal' }, + { inner: 84, rows: 22, tier: 'compact' }, + ] as const)('degrades art to preserve the action at $rows rows', ({ inner, rows, tier }) => { + const fixture = hostFixture(rows) + const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, async () => {}, () => {}) + const lines = component.render(inner + 4) + expect(tuiFirstRunWelcomeArtTier(inner, rows)).toBe(tier) + expect(lines.length).toBeLessThanOrEqual(Math.floor(rows * 0.9)) + expect(lines.join('\n')).toContain(`Enter ${copy.continueLabel}`) + }) + + it('drops the whale at low height while keeping prose, scrolling, and Enter reachable', () => { + const fixture = hostFixture(10) + const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, async () => {}, () => {}) + const initial = component.render(54).join('\n') + expect(tuiFirstRunWelcomeArtTier(50, 10)).toBeUndefined() + expect(initial).toContain(openingSentence) + expect(initial).toContain(`Enter ${copy.continueLabel}`) + + component.handleInput('\x1b[F') + const end = component.render(54).join('\n') + expect(withoutWhitespace(end)).toContain(withoutWhitespace(copy.paragraphs.at(-1)!.slice(-7))) + expect(end).toContain(`Enter ${copy.continueLabel}`) + + for (const key of ['\x1b[A', '\x1b[B', '\x1b[5~', '\x1b[6~', '\x1b[H', 'x']) { + component.handleInput(key) + } + component.invalidate() + }) + + it('renders a tiny viewport and a quotation-only paragraph without overdraw', () => { + const fixture = hostFixture(5) + const quoteOnly = { ...copy, paragraphs: ['“如切如磋，如琢如磨。”'] } + const component = new TuiFirstRunWelcomeComponent(fixture.host, quoteOnly, async () => {}, () => {}) + const lines = component.render(2) + expect(lines.every(line => visibleWidth(line) <= 6)).toBe(true) + }) + + it('keeps the side-by-side composition aligned when prose outgrows the full raster', () => { + const fixture = hostFixture(40) + const longCopy = { ...copy, paragraphs: [copy.paragraphs.join(' ').repeat(4)] } + const component = new TuiFirstRunWelcomeComponent(fixture.host, longCopy, async () => {}, () => {}) + const lines = component.render(100) + expect(lines.length).toBeGreaterThan(TUI_FIRST_RUN_WELCOME_WHALE.full.unicode.length) + expect(lines.every(line => visibleWidth(line) <= 100)).toBe(true) + component.handleInput('\x1b[F') + expect(component.render(100).join('\n')).toContain(copy.title) + }) + + it('renders the bit-equivalent ASCII icon fallback for an explicitly non-Unicode terminal', () => { + const fixture = hostFixture(30) + const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, async () => {}, () => {}, true) + const rendered = component.render(72).join('\n') + expect(rendered).toContain(TUI_FIRST_RUN_WELCOME_WHALE.minimal.ascii[0]!.trim()) + expect(rendered).not.toMatch(/[▀▄█]/u) + }) + + it.each(['full', 'compact', 'minimal'] as const)('keeps the $tier ASCII raster bit-equivalent', (tier) => { + const mapped = TUI_FIRST_RUN_WELCOME_WHALE[tier].unicode.map(line => Array.from(line).map((cell) => { + if (cell === '▀') return "'" + if (cell === '▄') return '_' + if (cell === '█') return '#' + return cell + }).join('')) + expect(mapped).toEqual(TUI_FIRST_RUN_WELCOME_WHALE[tier].ascii) + }) + + it('ignores Escape and acknowledges only Enter before closing', async () => { + const fixture = hostFixture(30) + const acknowledge = vi.fn(async () => {}) + const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, acknowledge, () => {}) + component.render(72) + + component.handleInput('\x1b') + await Promise.resolve() + expect(acknowledge).not.toHaveBeenCalled() + expect(fixture.closed()).toBe(false) + + component.handleInput('\r') + await vi.waitFor(() => { expect(fixture.closed()).toBe(true) }) + expect(acknowledge).toHaveBeenCalledOnce() + }) + + it('keeps the notice eligible when Ctrl+C or Ctrl+D requests a normal exit', async () => { + const fixture = hostFixture(30) + const acknowledge = vi.fn(async () => {}) + const exit = vi.fn() + const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, acknowledge, exit) + component.handleInput('\x03') + component.handleInput('\x04') + expect(exit).toHaveBeenCalledTimes(2) + expect(acknowledge).not.toHaveBeenCalled() + expect(fixture.closed()).toBe(false) + }) + + it('does not start a second acknowledgement while the first Enter is pending', async () => { + const fixture = hostFixture(30) + const pending = Promise.withResolvers() + const acknowledge = vi.fn(async () => pending.promise) + const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, acknowledge, () => {}) + component.render(72) + + component.handleInput('\r') + component.handleInput('\r') + component.handleInput('\x1b[B') + expect(component.render(72).join('\n')).toContain(copy.saving) + expect(acknowledge).toHaveBeenCalledOnce() + + pending.resolve(undefined) + await vi.waitFor(() => { expect(fixture.closed()).toBe(true) }) + }) + + it('keeps the overlay open after a persistence failure and lets Enter retry', async () => { + const fixture = hostFixture(30) + let attempts = 0 + const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, async () => { + attempts += 1 + if (attempts === 1) throw new Error('disk unavailable') + }, () => {}) + component.render(72) + + component.handleInput('\r') + await vi.waitFor(() => { + expect(component.render(72).join('\n')).toContain(copy.saveError) + }) + expect(fixture.closed()).toBe(false) + + component.handleInput('\r') + await vi.waitFor(() => { expect(fixture.closed()).toBe(true) }) + expect(attempts).toBe(2) + expect(fixture.invalidations()).toBeGreaterThanOrEqual(3) + }) + + it('opens through the TUI extension and uses the launcher-owned acknowledgement closure', async () => { + const home = await temporaryHome('dsh-tui-welcome-apply-') + let request: TuiOverlayRequest | undefined + let disposePending: (() => Promise) | undefined + const ctx = { + effect(register: () => () => Promise) { + disposePending = register() + return () => {} + }, + tui: { + openOverlay(value: TuiOverlayRequest) { + request = value + return {} as never + }, + }, + } as unknown as Context + apply(ctx, { dshHome: home }) + expect(request?.options).toEqual({ + width: '100%', + maxHeight: '90%', + anchor: 'center', + margin: 0, + }) + + const fixture = hostFixture(30) + const component = request?.create(fixture.host) + expect(component).toBeInstanceOf(TuiFirstRunWelcomeComponent) + component?.handleInput?.('\x03') + expect(mockDisposeRootAndExit).toHaveBeenCalledWith(ctx, 0) + component?.handleInput?.('\r') + await disposePending?.() + expect(await hasTuiFirstRunWelcomeAcknowledgement(home)).toBe(true) + + apply(ctx, { dshHome: home, asciiArt: true }) + expect(request?.create(fixture.host).render(72).join('\n')) + .toContain(TUI_FIRST_RUN_WELCOME_WHALE.minimal.ascii[0]!.trim()) + }) +}) diff --git a/apps/cli/tests/tui-keyless-smoke.e2e.ts b/apps/cli/tests/tui-keyless-smoke.e2e.ts index 359fe6338e..7c7ad10141 100644 --- a/apps/cli/tests/tui-keyless-smoke.e2e.ts +++ b/apps/cli/tests/tui-keyless-smoke.e2e.ts @@ -1,6 +1,7 @@ import { createUserMessage, createMessage } from '@deepseek-ai/dsh-llm' import { realpathSync } from 'node:fs' -import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises' +import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' import { dirname, join } from 'node:path' import { fileURLToPath } from 'node:url' import { describe, expect, it } from 'vitest' @@ -8,12 +9,30 @@ import { LOADER_SMOKE_TEST_TIMEOUT_MS } from '@deepseek-ai/dsh-loader-smoke' import { packChunkRuns, SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session' import { logPath, toHeaderLine } from '../../../packages/session-persistence/session-persistence-jsonl/src/format.ts' import { runTuiPtySmoke, type TuiPtySmokeOptions } from './pty-harness.ts' +import { HeadlessTerminal } from '../../../packages/ui/tui/tests/headless-terminal.ts' +import { + acknowledgeTuiFirstRunWelcome, + hasTuiFirstRunWelcomeAcknowledgement, +} from '../src/tui-onboarding/tui-first-run-welcome.ts' +import { + TUI_FIRST_RUN_WELCOME_NOTICE_COPY, + TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE, +} from '../src/tui-onboarding/tui-first-run-welcome-copy.ts' +import { TUI_FIRST_RUN_WELCOME_WHALE } from '../src/tui-onboarding/tui-first-run-welcome-art.ts' const dshBinScript = fileURLToPath(new URL('../src/bin.ts', import.meta.url)) // `--config` layers an overlay over the shared base, so the default surface // needs no config argument at all; these are the overlays under test. const scriptedConfigPath = fileURLToPath(new URL('./fixtures/tui-scripted.cordis.yml', import.meta.url)) const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) +const firstRunSnapshots = fileURLToPath(new URL('./tui-first-run-snapshots/', import.meta.url)) +const synchronizedFrameEnd = '\x1b[?2026l' +// Artifact mode gives the inner PTY driver 60 seconds and its execa owner a +// five-second backstop. Keep Vitest outside both deadlines so the harness can +// report its own marker, exit, and cleanup failure instead of being cut off. +const PTY_SMOKE_TEST_TIMEOUT_MS = process.env.DSH_EXAMPLE_MODE === 'lib' + ? 75_000 + : LOADER_SMOKE_TEST_TIMEOUT_MS /** * Seed the isolated process workspace: ordinary files land in `cwd`, personal @@ -125,20 +144,77 @@ async function readLoggedRequestContext(cwd: string): Promise & { label: string }): Promise { +function smoke(overrides: Partial & { + label: string + showFirstRunWelcome?: boolean +}): Promise { + const { showFirstRunWelcome = false, prepare, ...options } = overrides return runTuiPtySmoke({ tempDirPrefix: 'dsh-tui-smoke-', binScript: dshBinScript, tsconfigPath, - // Telemetry now mounts in the shared base: keep fixture sessions from - // POSTing to the production endpoint when run outside CI's workflow env. - env: { DEEPSEEK_API_KEY: 'keyless-tui-no-call', DSH_TELEMETRY_DISABLED: '1' }, + env: { + DEEPSEEK_API_KEY: 'keyless-tui-no-call', + DSH_TELEMETRY_DISABLED: '1', + LANG: 'en_US.UTF-8', + LC_ALL: 'en_US.UTF-8', + LC_CTYPE: 'en_US.UTF-8', + TERM: 'xterm-256color', + }, // Artifact CI builds and smokes concurrently on a contended runner. ...(process.env.DSH_EXAMPLE_MODE === 'lib' ? { timeoutMs: 60_000 } : {}), - ...overrides, + ...options, + prepare: async (cwd) => { + if (!showFirstRunWelcome) await acknowledgeTuiFirstRunWelcome(join(cwd, '.dsh')) + await prepare?.(cwd) + }, }) } +const firstRunCopy = TUI_FIRST_RUN_WELCOME_NOTICE_COPY[TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE] +const firstRunOpeningSentence = `${firstRunCopy.paragraphs[0]!.split('。', 1)[0]}。` + +function firstRunArtAnchor(tier: keyof typeof TUI_FIRST_RUN_WELCOME_WHALE): string { + return TUI_FIRST_RUN_WELCOME_WHALE[tier].unicode[tier === 'full' ? 2 : 0]!.trim() +} + +/** Keep only the overlay rows, excluding platform-specific scrollback and the underlying TUI. */ +function overlaySnapshot(snapshot: string, columns: number, rows: number): string { + const blocks: string[][] = [] + for (const line of snapshot.split('\n')) { + if (/^\d+(?:-\d+)?~?\| /u.test(line)) blocks.push([line]) + else if (line.startsWith(' style ') && blocks.length > 0) blocks.at(-1)?.push(line) + } + const first = blocks.findIndex(block => block[0]?.includes('╭') === true) + const last = blocks.findIndex((block, index) => index >= first && block[0]?.includes('╰') === true) + if (first < 0 || last < first) throw new Error('first-run PTY snapshot has no complete overlay frame') + const overlay = blocks.slice(first, last + 1).flatMap((block, index) => [ + block[0]!.replace(/^\d+(?:-\d+)?(~)?\|/u, `${String(index)}$1|`), + ...block.slice(1), + ]) + return [`overlay ${String(columns)}x${String(rows)} rows=${String(last - first + 1)}`, ...overlay, ''].join('\n') +} + +/** Project the first synchronized PTY frame containing `marker` into an overlay-only snapshot. */ +async function firstRunFrameSnapshot( + output: string, + marker: string, + columns: number, + rows: number, +): Promise { + const markerIndex = output.indexOf(marker) + if (markerIndex < 0) throw new Error(`first-run PTY output has no marker ${JSON.stringify(marker)}`) + const frameEnd = output.indexOf(synchronizedFrameEnd, markerIndex) + if (frameEnd < 0) throw new Error(`first-run PTY output has no complete frame after ${JSON.stringify(marker)}`) + const terminal = new HeadlessTerminal(columns, rows) + try { + terminal.write(output.slice(0, frameEnd + synchronizedFrameEnd.length)) + return overlaySnapshot(await terminal.snapshot(), columns, rows) + } finally { + await terminal.dispose() + } +} + // The scripted conversation switches to the pro model first: the scripted // adapter proves routing + prompt variables by rejecting tool-ful calls on any // other route (see fixtures/tui-scripted-llm.ts). @@ -148,6 +224,138 @@ const SELECT_PRO_MODEL = [ ] as const describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => { + it.each([ + { columns: 60, tier: undefined }, + { columns: 80, tier: 'minimal' }, + { columns: 120, tier: 'full' }, + { columns: 160, tier: 'full' }, + ] as const)('renders and acknowledges the responsive first-run composition at $columns columns', async ({ columns, tier }) => { + const output = await smoke({ + label: `dsh first-run welcome ${String(columns)} columns`, + tempDirPrefix: `dsh-tui-welcome-${String(columns)}-`, + configPath: scriptedConfigPath, + showFirstRunWelcome: true, + expectedExitCode: 0, + columns, + rows: 30, + actions: [ + { + waitFor: `Enter ${firstRunCopy.continueLabel}`, + send: '\r\x03', + }, + ], + inspect: async (cwd) => { + expect(await hasTuiFirstRunWelcomeAcknowledgement(join(cwd, '.dsh'))).toBe(true) + const entries = await readdir(join(cwd, '.sessions'), { recursive: true }) + const logs = entries.filter(name => name.endsWith('.jsonl')) + for (const log of logs) { + const stored = await readFile(join(cwd, '.sessions', log), 'utf8') + expect(stored).not.toContain(firstRunCopy.paragraphs[0]) + } + }, + }) + await expect(await firstRunFrameSnapshot(output, firstRunOpeningSentence, columns, 30)) + .toMatchFileSnapshot(join(firstRunSnapshots, `${String(columns)}-columns.expected.txt`)) + if (tier === undefined) { + expect(output).not.toContain(TUI_FIRST_RUN_WELCOME_WHALE.minimal.unicode[0]!.trim()) + } else { + expect(output).toContain(firstRunArtAnchor(tier)) + } + expect(output).toContain(`Enter ${firstRunCopy.continueLabel}`) + }, PTY_SMOKE_TEST_TIMEOUT_MS) + + it('keeps prose and Enter reachable in a low-height real PTY after dropping the whale', async () => { + const output = await smoke({ + label: 'dsh low-height first-run welcome', + tempDirPrefix: 'dsh-tui-welcome-low-', + configPath: scriptedConfigPath, + showFirstRunWelcome: true, + expectedExitCode: 0, + columns: 60, + rows: 12, + actions: [ + { waitFor: firstRunOpeningSentence, send: '\x1b[F' }, + { + waitFor: `Enter ${firstRunCopy.continueLabel}`, + occurrence: 2, + send: '\r\x03', + }, + ], + }) + await expect(await firstRunFrameSnapshot(output, firstRunOpeningSentence, 60, 12)) + .toMatchFileSnapshot(join(firstRunSnapshots, '60-columns-low-height.expected.txt')) + expect(output).toContain(firstRunCopy.title) + expect(output).toContain(firstRunOpeningSentence) + expect(output).toContain('企业微信群') + expect(output).toContain(`Enter ${firstRunCopy.continueLabel}`) + expect(output).not.toContain(TUI_FIRST_RUN_WELCOME_WHALE.minimal.unicode[0]!.trim()) + }, PTY_SMOKE_TEST_TIMEOUT_MS) + + it('shows once and skips the second launch under the same DSH_HOME', async () => { + const cwd = await mkdtemp(join(tmpdir(), 'dsh-tui-welcome-twice-')) + try { + const first = await smoke({ + label: 'dsh first welcome launch', + tempDirPrefix: 'unused-', + cwd, + configPath: scriptedConfigPath, + showFirstRunWelcome: true, + expectedExitCode: 0, + actions: [ + { waitFor: `Enter ${firstRunCopy.continueLabel}`, send: '\r\x03' }, + ], + }) + expect(first).toContain(firstRunCopy.title) + + const second = await smoke({ + label: 'dsh second welcome launch', + tempDirPrefix: 'unused-', + cwd, + configPath: scriptedConfigPath, + showFirstRunWelcome: true, + expectedExitCode: process.platform === 'win32' ? 0 : -15, + actions: [{ waitFor: 'main-session-', signal: 'SIGTERM' }], + }) + expect(second).not.toContain(firstRunOpeningSentence) + expect(second).not.toContain(`Enter ${firstRunCopy.continueLabel}`) + } finally { + await rm(cwd, { recursive: true, force: true }) + } + }, PTY_SMOKE_TEST_TIMEOUT_MS) + + it.skipIf(process.platform === 'win32')('keeps the notice eligible when the process exits before Enter', async () => { + const cwd = await mkdtemp(join(tmpdir(), 'dsh-tui-welcome-abort-')) + try { + await smoke({ + label: 'dsh aborted welcome launch', + tempDirPrefix: 'unused-', + cwd, + configPath: scriptedConfigPath, + showFirstRunWelcome: true, + expectedExitCode: -15, + actions: [{ waitFor: firstRunOpeningSentence, signal: 'SIGTERM' }], + inspect: async (workspace) => { + expect(await hasTuiFirstRunWelcomeAcknowledgement(join(workspace, '.dsh'))).toBe(false) + }, + }) + + const next = await smoke({ + label: 'dsh welcome after aborted launch', + tempDirPrefix: 'unused-', + cwd, + configPath: scriptedConfigPath, + showFirstRunWelcome: true, + expectedExitCode: 0, + actions: [ + { waitFor: `Enter ${firstRunCopy.continueLabel}`, send: '\r\x03' }, + ], + }) + expect(next).toContain(firstRunOpeningSentence) + } finally { + await rm(cwd, { recursive: true, force: true }) + } + }, PTY_SMOKE_TEST_TIMEOUT_MS) + it('boots pi-tui, sweeps the borderless banner in, enters plan mode, and restores the terminal', async () => { // With no configured welcome the borderless banner sweeps in left-to-right; // the detail line's session id (`main-session-`) renders only once @@ -170,7 +378,7 @@ describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => { expect(output).not.toContain('╭') expect(output).not.toContain('╮') expect(output).toContain('\u001B[?2004l') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) it('switches models, streams a response, answers a user-question dialog, and exits cleanly', async () => { const output = await smoke({ @@ -223,7 +431,7 @@ describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => { expect(output).toContain('Registered tools') expect(output).toContain('ask_user_question') expect(output).toContain('\u001B[?2004l') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) it('loads a local skill via /skill: and delivers its body to the model as a user turn', async () => { // The whole user-only invocation path in one keyless boot: `ctx.get('skills')` @@ -259,7 +467,7 @@ describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => { expect(output).not.toContain('[instructions]') expect(output).toContain('Scripted skill body received.') expect(output).toContain('\u001B[?2004l') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) it('adds a watched local skill to live /skill: autocomplete without restarting', async () => { const skill = [ @@ -289,7 +497,7 @@ describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => { }) expect(output).toContain('HOT_ADDED_COMPLETION_MARKER') expect(output).toContain('\u001B[?2004l') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) it.skipIf(process.env.DSH_EXAMPLE_MODE === 'lib')('fuzzy-completes an @file path without reading or submitting the file', async () => { const output = await smoke({ @@ -314,11 +522,51 @@ describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => { expect(output).toContain('File · terminal-special-case.t') expect(output).toContain('@src/terminal-special-case.ts') expect(output).toContain('\u001B[?2004l') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) }) describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { + it('shows the terminal-local notice over a resumed session without changing its log', async () => { + let originalLineCount = 0 + const output = await smoke({ + label: 'dsh first-run notice on resume', + tempDirPrefix: 'dsh-tui-welcome-resume-', + binScript: dshBinScript, + configArgs: ['--resume', 'resume-target', '--config', scriptedConfigPath], + showFirstRunWelcome: true, + expectedExitCode: 0, + prepare: async (cwd) => { + await seedResumeSession(cwd) + const before = await readFile(logPath( + join(cwd, '.sessions'), + realpathSync.native(cwd), + SessionId('resume-target'), + 'none', + ), 'utf8') + originalLineCount = before.split('\n').filter(Boolean).length + }, + actions: [ + { waitFor: `Enter ${firstRunCopy.continueLabel}`, send: '\r\x03' }, + ], + inspect: async (cwd) => { + const after = await readFile(logPath( + join(cwd, '.sessions'), + realpathSync.native(cwd), + SessionId('resume-target'), + 'none', + ), 'utf8') + expect(after).not.toContain(firstRunCopy.paragraphs[0]) + const appended = after.split('\n').filter(Boolean).slice(originalLineCount) + .map(line => JSON.parse(line) as SessionEvent) + expect(appended).not.toContainEqual(expect.objectContaining({ type: 'user/message' })) + expect(appended).not.toContainEqual(expect.objectContaining({ type: 'turn/start' })) + }, + }) + expect(output).toContain(firstRunOpeningSentence) + expect(output).toContain('Resume selector design — DeepSeek Harness') + }, PTY_SMOKE_TEST_TIMEOUT_MS) + it('exec-replaces the TUI for /resume and restores the same session state', async () => { const output = await smoke({ label: 'dsh in-place resume', @@ -338,7 +586,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { expect(released).toBeGreaterThanOrEqual(0) expect(restored).toBeGreaterThan(released) expect(output).toContain('Preserve restored state') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) it('boots the shipped default config with no arguments and no personal overlay', async () => { const output = await smoke({ @@ -353,7 +601,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { expect(output).not.toContain('╭') expect(output).not.toContain('╮') expect(output).toContain('\u001B[?2004l') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) it('applies the personal overlay: config.yaml patches an overlay-inserted row, the invoking directory\'s .env feeds its !!js, and the home .env stays out of the environment', async () => { // The whole personal-config chain in one boot, plus the environment layer @@ -390,7 +638,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { expect(output).toContain('PROJECT OVERLAY READY.') expect(output).not.toContain('HOME ENV LEAKED.') expect(output).toContain('\u001B[?2004l') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) it('fails loud instead of booting when the personal config.yaml is invalid', async () => { const output = await smoke({ @@ -402,7 +650,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { expectedExitCode: 1, }) expect(output).toContain('must be a top-level YAML array of loader patch entries') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) it('routes the --resume flag into the launcher session-identity slot, failing loud on a missing id', async () => { // The flag path end to end: apps/cli parses `--resume missing-session`, @@ -417,7 +665,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { expectedExitCode: 1, }) expect(output).toContain('ui-tui: session "missing-session" failed to start:') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) it('prints the launcher-owned resume command on exit, naming the booted config', async () => { // The exit line is built by apps/cli from this invocation, so it must carry @@ -430,7 +678,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { actions: [{ waitFor: 'scripted TUI ready.', send: '/exit\r' }], }) expect(output).toMatch(/To resume this session: dsh --resume=main-session-[0-9a-f-]{36} --config/) - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) it('keeps resume working when the personal overlay replaces the whole agent-loop config', async () => { // Loader patches replace a targeted `config` key wholesale, so a personal @@ -465,7 +713,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { actions: [{ waitFor: 'OVERLAY REPLACED THE CONFIG.', send: '/exit\r' }], }) expect(output).toMatch(/To resume this session: dsh --resume=main-session-[0-9a-f-]{36}/) - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) it('reports a failing bash command exactly once, as the terminal card exit pill', async () => { // The model-facing result ends in `[exit code: 3]`, which the terminal card @@ -488,7 +736,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { expect(output).toContain('SCRIPTED_BASH_FAILED') expect(output).toContain('[exit 3]') expect(output).not.toContain('[exit code: 3]') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) it('tells the model its source path and offers the bundled maintenance skills', async () => { // The launcher resolves the checkout root three hops up from apps/cli/{src,lib}; @@ -514,5 +762,5 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => { expect(context.skillCatalog).toContain("- `dsh-customize`: Customize or maintain any dsh source checkout — the one powering the current DSH process, the installed `dsh` command, or a sibling dsh/deepseek-harness clone. Use before any requested action that alters such a checkout's files or git state. Read-only questions that only inspect the checkout do not trigger this. Do not edit the personal staging checkout directly.") expect(context.skillCatalog).toContain('- `dsh-upgrade`: Upgrades a source-installed, personally customized DSH checkout to upstream master while preserving local changes and an unchanged rollback worktree. Use when the user asks to update or upgrade DSH.') expect(context.skillCatalog).toContain('- `dsh-upstream-customization`: Classifies personal DSH customizations for upstream contribution and, after explicit per-feature approval, rebuilds one on upstream master and opens a draft pull request. Use when the user asks to contribute, publish, or upstream a local DSH change, or asks whether one is worth proposing.') - }, LOADER_SMOKE_TEST_TIMEOUT_MS) + }, PTY_SMOKE_TEST_TIMEOUT_MS) }) diff --git a/apps/cli/tests/tui.snapshot.ts b/apps/cli/tests/tui.snapshot.ts index 078e4c191e..114d69401b 100644 --- a/apps/cli/tests/tui.snapshot.ts +++ b/apps/cli/tests/tui.snapshot.ts @@ -11,8 +11,12 @@ import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local' import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local' import WorkerCodeRuntime from '@deepseek-ai/dsh-code-runtime-worker' import CommandService from '@deepseek-ai/dsh-commands' +import * as CommandCompact from '@deepseek-ai/dsh-command-compact' +import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic' +import type { SummarizationInput } from '@deepseek-ai/dsh-compact-basic/src/summarizer.ts' import LocalFileSystem from '@deepseek-ai/dsh-fs-local' import * as FsPolicy from '@deepseek-ai/dsh-fs-policy' +import { createUserMessage } from '@deepseek-ai/dsh-llm' import * as ToolFs from '@deepseek-ai/dsh-tool-fs' import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' import { installLlmReplay, parseSessionLog } from '@deepseek-ai/dsh-llm-replay' @@ -45,6 +49,8 @@ type ScenarioInteraction = 'skill-invocation-policy' interface Scenario { name: string + /** Replay fixture owned by an earlier scenario, for a derived presentation case. */ + fixture?: string composition: Composition expectedTools: string[] expectedEventCounts?: Record @@ -68,6 +74,13 @@ interface Scenario { spillMaxInlineBytes?: number /** Run scenario-specific terminal input instead of replaying recorded user prompts. */ interaction?: ScenarioInteraction + /** + * Mount a deterministic compaction backend plus `/compact`, then run the + * human command with a held summary while a prompt and injected context + * arrive. Proves queued input waits for the standalone bracket's durability + * checkpoint instead of racing the replacement. + */ + manualCompact?: boolean } const SCENARIOS: Scenario[] = [ @@ -80,6 +93,14 @@ const SCENARIOS: Scenario[] = [ leavePlanModeAfterFirstTurn: true, recorded: true, }, + { + name: 'queued-manual-compact', + fixture: 'multi-turn-conversation', + composition: 'native', + expectedTools: [], + recorded: false, + manualCompact: true, + }, { name: 'todo-plan', composition: 'native', @@ -149,6 +170,44 @@ function snapshotModeFromEnv(value: string | undefined): SnapshotMode { const MODE = snapshotModeFromEnv(process.env.DSH_SNAPSHOT) const observedScenarios = new Set() +const workerState = Reflect.get(globalThis, '__vitest_worker__') as + | { readonly config?: { readonly testNamePattern?: RegExp } } + | undefined +// Worker argv omits the parent CLI's `-t`; the serialized runner config is the +// authoritative distinction between a focused replay and the full suite. +const TEST_NAME_FILTERED = workerState?.config?.testNamePattern !== undefined + +/** + * Deterministic keyless summary that pauses so the scenario can submit a real + * prompt and inject context while manual compaction holds turn admission. + */ +class DeferredSnapshotCompactService extends BasicCompactService { + readonly summaryStarted = Promise.withResolvers() + readonly releaseSummary = Promise.withResolvers() + + override async summarize( + _input: SummarizationInput, + _agent: Agent, + signal?: AbortSignal, + ): Promise<{ summary: [{ type: 'text'; text: string }]; provider: string; model: string }> { + this.summaryStarted.resolve(undefined) + await this.releaseSummary.promise + signal?.throwIfAborted() + return { + summary: [{ type: 'text', text: 'Keyless manual compaction checkpoint.' }], + provider: 'snapshot', + model: 'snapshot-compactor', + } + } +} + +/** Seed between-turn model-visible history without inventing a loop execution. */ +function seedCompactableHistory(agent: Agent): void { + agent.inject(createUserMessage({ + content: [{ type: 'text', text: 'Older snapshot context. '.repeat(60) }], + source: { kind: 'plugin', plugin: 'snapshot-seed' }, + })) +} function snapshotDisplayPath(displayPath: string, cwd: string, displayCwd: string): string { const rel = relative(cwd, displayPath) @@ -161,10 +220,15 @@ function scenarioDir(scenario: Scenario): string { return join(SNAPSHOTS_DIR, scenario.name) } +/** Directory owning the replay fixture: the scenario's own, or the one it derives from. */ +function fixtureDir(scenario: Scenario): string { + return join(SNAPSHOTS_DIR, scenario.fixture ?? scenario.name) +} + function childFixturePaths(scenario: Scenario): string[] { return Array.from( { length: scenario.childSessions ?? 0 }, - (_, index) => join(scenarioDir(scenario), `session.${index + 1}.jsonl`), + (_, index) => join(fixtureDir(scenario), `session.${index + 1}.jsonl`), ) } @@ -206,6 +270,24 @@ async function settleTerminal(terminal: HeadlessTerminal): Promise { if (stable < 3) throw new Error('TUI frames did not quiesce within 200ms') } +/** Bound deterministic in-process coordination waits with actionable state. */ +async function snapshotDeadline( + operation: Promise, + detail: () => string, +): Promise { + let timer: ReturnType | undefined + try { + return await Promise.race([ + operation, + new Promise((_resolve, reject) => { + timer = setTimeout(() => { reject(new Error(detail())) }, 5_000) + }), + ]) + } finally { + if (timer !== undefined) clearTimeout(timer) + } +} + async function mountScenarioContext( scenario: Scenario, cwd: string, @@ -232,6 +314,9 @@ async function mountScenarioContext( skills: { local: { agentsHome: join(cwd, '.agents') } }, }) await ctx.plugin(TokenMeterService) + if (scenario.manualCompact === true) { + await ctx.plugin(DeferredSnapshotCompactService, { auto: false }) + } await ctx.plugin(LocalSubprocessService) await ctx.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 }) await ctx.plugin(SnapshotLocalFileSystem, { cwd: '/' }) @@ -249,6 +334,7 @@ async function mountScenarioContext( await ctx.plugin(ToolWorkflow) await ctx.plugin(ToolRalph) await ctx.plugin(CommandService) + if (scenario.manualCompact === true) await ctx.plugin(CommandCompact) if (scenario.enterPlanMode === true) { await ctx.plugin(PlanModeService, { section: 'Snapshot plan mode instructions.' }) } @@ -276,9 +362,9 @@ interface ScenarioResult { } async function runScenario(scenario: Scenario): Promise { - const clock = vi.spyOn(Date, 'now').mockReturnValue(new Date(2026, 6, 21, 12, 0, 0).getTime()) - const dir = scenarioDir(scenario) - const fixtureFile = join(dir, 'session.jsonl') + const snapshotTime = new Date(2026, 6, 21, 12, 0, 0).getTime() + const clock = vi.spyOn(Date, 'now').mockReturnValue(snapshotTime) + const fixtureFile = join(fixtureDir(scenario), 'session.jsonl') const childFiles = childFixturePaths(scenario) const prompts = userPrompts(await readFile(fixtureFile, 'utf8')) if (scenario.interaction === undefined) { @@ -292,7 +378,7 @@ async function runScenario(scenario: Scenario): Promise { const terminal = new HeadlessTerminal(100, 36) try { if (scenario.seedWorkspace === true) { - const source = join(scenarioDir(scenario), 'workspace') + const source = join(fixtureDir(scenario), 'workspace') await cp(source, cwd, { recursive: true }) } ctx = await mountScenarioContext(scenario, cwd, displayCwd, fixtureFile, childFiles) @@ -308,6 +394,7 @@ async function runScenario(scenario: Scenario): Promise { agentOptions: { provider: 'deepseek-official', model: 'deepseek-v4-flash' }, }) const agent: Agent = handle.agent + if (scenario.manualCompact === true) seedCompactableHistory(agent) controller = createTuiChat(ctx, { sessionId: 'main-session', theme: { color: true }, @@ -380,6 +467,14 @@ async function runScenario(scenario: Scenario): Promise { } let remainingPrompts = prompts + let queuedPrompt: string | undefined + let manualOrder: string[] | undefined + let manualCommandId: string | undefined + if (scenario.manualCompact === true) { + expect(prompts.length, 'queued manual compaction needs a second replayed prompt').toBeGreaterThanOrEqual(2) + queuedPrompt = prompts.at(-1) + remainingPrompts = prompts.slice(0, -1) + } if (scenario.enterPlanMode === true) { const firstPrompt = prompts[0]! terminal.send(`/plan ${firstPrompt}`) @@ -396,12 +491,93 @@ async function runScenario(scenario: Scenario): Promise { } for (const prompt of remainingPrompts) { + const admitted = agent.session.events.filter(event => + event.type === 'user/message' && event.data.source.kind === 'user').length terminal.send(prompt) terminal.send('\r') + await terminal.flush() + await expect.poll(() => agent.session.events.filter(event => + event.type === 'user/message' && event.data.source.kind === 'user').length).toBe(admitted + 1) await agent.whenIdle() await settleTerminal(terminal) } + if (scenario.manualCompact === true && queuedPrompt !== undefined) { + terminal.send('/help') + terminal.send('\r') + await settleTerminal(terminal) + expect(await terminal.snapshot({ includeScrollback: true })) + .toContain('/compact — Compact older conversation history') + + const compact = ctx.compact as DeferredSnapshotCompactService + const inbox: string[] = [] + manualOrder = [] + ctx.on('agent/inbox/enqueue', (subject, item) => { + if (subject === agent) inbox.push(`enqueue:${item.placement}:${item.id}`) + }) + ctx.on('agent/inbox/dequeue', (subject, message) => { + if (subject === agent) inbox.push(`dequeue:${message.id}`) + }) + ctx.on('session/event', (session, event) => { + if (session !== agent.session) return + if (event.type === 'command/run' && event.data.name === 'compact') { + manualCommandId = event.data.commandId + manualOrder?.push('command/run') + } + if (event.type === 'command/done' && event.data.commandId === manualCommandId) { + manualOrder?.push('command/done') + } + if (event.type.startsWith('compact/')) manualOrder?.push(event.type) + if (event.type === 'user/message' + && event.data.source.kind === 'plugin' + && event.data.source.plugin === 'compact') manualOrder?.push('checkpoint') + if (event.type === 'turn/start') manualOrder?.push(`turn/start:${event.data.trigger.kind}`) + }) + ctx.on('session/flush', (session) => { + if (session === agent.session) manualOrder?.push('flush') + }) + + terminal.send('/compact') + terminal.send('\r') + await terminal.flush() + await snapshotDeadline(compact.summaryStarted.promise, () => + `manual summary did not start; status=${agent.status}; tail=${ + agent.session.events.slice(-8).map(event => event.type).join(',') + }`) + clock.mockReturnValue(snapshotTime + 1_000) + await settleTerminal(terminal) + await expect.poll(() => terminal.snapshot()).toContain('dsh ⊙') + await expect.poll(() => terminal.snapshot()).toContain('Context being compacted 1.0s') + const liveCompaction = await terminal.snapshot() + expect(liveCompaction.indexOf('Context being compacted 1.0s')).toBeLessThan(liveCompaction.indexOf('dsh ⊙')) + clock.mockReturnValue(snapshotTime) + + // Real keystrokes: the prompt keeps its ordinary queue identity while + // admission is reserved, and an injection appends immediately. + terminal.send(queuedPrompt) + terminal.send('\r') + await terminal.flush() + await expect.poll(() => inbox.length).toBe(1) + agent.inject(createUserMessage({ + content: [{ type: 'text', text: 'Injected while compaction was running.' }], + source: { kind: 'plugin', plugin: 'snapshot-injector' }, + })) + expect(inbox[0]).toMatch(/^enqueue:queued:/u) + expect(agent.status).toBe('idle') + expect(agent.session.events.some(event => event.type === 'user/message' + && event.data.source.kind === 'user' + && event.data.content.some(block => block.type === 'text' && block.text === queuedPrompt))).toBe(false) + + const idle = agent.whenIdle() + compact.releaseSummary.resolve(undefined) + await snapshotDeadline(idle, () => + `manual compaction did not reach idle; status=${agent.status}; order=${manualOrder?.join(',') ?? ''}; tail=${ + agent.session.events.slice(-12).map(event => event.type).join(',') + }`) + await settleTerminal(terminal) + expect(inbox).toEqual([inbox[0], `dequeue:${inbox[0]?.slice('enqueue:queued:'.length) ?? ''}`]) + } + const events: SessionEvent[] = [...agent.session.events] const firstHeader = events.find(event => event.type === 'request/header') expect(firstHeader?.type === 'request/header' && firstHeader.data.header.system) @@ -437,6 +613,87 @@ async function runScenario(scenario: Scenario): Promise { expect(events.filter(event => event.type === 'user/message' && event.data.source.kind === 'plugin').map(event => (event.data as { content: unknown }).content)) .toContainEqual([{ type: 'text', text: 'The user switched this session back to the default mode.' }]) } + if (scenario.manualCompact === true) { + const compactStart = events.find(event => event.type === 'compact/start') + const compactSummary = events.find(event => event.type === 'compact/summary') + const compactCheckpoint = events.find(event => event.type === 'user/message' + && event.data.source.kind === 'plugin' && event.data.source.plugin === 'compact') + const injectedEvent = events.find(event => event.type === 'user/message' + && event.data.source.kind === 'plugin' && event.data.source.plugin === 'snapshot-injector') + const compactEnd = events.find(event => event.type === 'compact/end') + expect(compactStart?.data.turn).toBeNull() + expect(compactEnd?.data.turn).toBeNull() + expect(events.filter(event => event.type === 'compact/summary')).toHaveLength(1) + if (compactStart === undefined || compactSummary === undefined + || compactCheckpoint === undefined || injectedEvent === undefined + || compactEnd === undefined) { + throw new Error('manual compaction snapshot is missing its durable marker, summary, checkpoint, or injection') + } + // The markers are time points, not an exclusive container: unrelated + // idle injection is allowed between them while the selected span stays stable. + expect(compactStart.seq).toBeLessThan(injectedEvent.seq) + expect(injectedEvent.seq).toBeLessThan(compactSummary.seq) + expect(compactSummary.seq).toBeLessThan(compactCheckpoint.seq) + expect(compactCheckpoint.seq).toBeLessThan(compactEnd.seq) + + const manualTimeline = manualOrder ?? [] + const commandRunIndex = manualTimeline.indexOf('command/run') + const compactStartIndex = manualTimeline.indexOf('compact/start') + const compactEndIndex = manualTimeline.indexOf('compact/end') + const firstFlushIndex = manualTimeline.indexOf('flush') + const queuedTurnIndex = manualTimeline.indexOf('turn/start:message') + const commandDoneIndex = manualTimeline.indexOf('command/done') + expect(manualTimeline.filter(item => item === 'command/run')).toHaveLength(1) + expect(manualTimeline.filter(item => item === 'command/done')).toHaveLength(1) + expect(compactStartIndex).toBeGreaterThan(commandRunIndex) + expect(compactEndIndex).toBeGreaterThan(compactStartIndex) + expect(firstFlushIndex).toBeGreaterThan(compactEndIndex) + expect(queuedTurnIndex).toBeGreaterThan(firstFlushIndex) + expect(commandDoneIndex).toBeGreaterThan(firstFlushIndex) + + const commandRun = events.find(event => event.type === 'command/run' + && event.data.name === 'compact') + const commandRunId = commandRun?.type === 'command/run' + ? commandRun.data.commandId + : undefined + const commandDone = events.find(event => event.type === 'command/done' + && event.data.commandId === commandRunId) + expect(commandRun?.type === 'command/run' && commandRun.data).toEqual({ + commandId: commandRunId, + name: 'compact', + args: '', + source: { kind: 'user' }, + }) + expect(commandDone?.type === 'command/done' && commandDone.data).toEqual({ + commandId: commandRunId, + kind: 'success', + text: 'Compacted 2 history items (~387 tokens).', + }) + expect(commandRun !== undefined && commandRun.seq < compactStart.seq).toBe(true) + expect(commandDone !== undefined && commandDone.seq > compactEnd.seq).toBe(true) + expect(agent.session.surface.nodes).not.toContain(commandRun?.seq) + expect(agent.session.surface.nodes).not.toContain(commandDone?.seq) + + // The command line itself never becomes a prompt. + expect(events.some(event => event.type === 'user/message' + && event.data.source.kind === 'user' + && event.data.content.some(block => block.type === 'text' && block.text.trim() === '/compact'))).toBe(false) + const derived = agent.session.deriveMessages().map(message => message.content + .map(block => block.type === 'text' ? block.text : '') + .join('')) + const checkpoint = derived.findIndex(text => text.includes('Keyless manual compaction checkpoint.')) + const injected = derived.findIndex(text => text.includes('Injected while compaction was running.')) + const queued = derived.findIndex(text => text === queuedPrompt) + expect(checkpoint).toBe(0) + expect(injected).toBeGreaterThan(checkpoint) + expect(queued).toBeGreaterThan(injected) + expect(derived).not.toContain('/compact') + expect(derived).not.toContain('Compacted 2 history items (~387 tokens).') + expect(derived.filter(text => text.includes('Injected while compaction was running.'))).toHaveLength(1) + expect(compactSummary.data.shadowedSeqs).not.toContain(injectedEvent.seq) + const queuedTurn = events.findLast(event => event.type === 'turn/start') + expect(queuedTurn !== undefined && compactEnd.seq < queuedTurn.seq).toBe(true) + } if (scenario.spillMaxInlineBytes !== undefined) { // The REAL pipeline ran (tools execute on replay too): the durable // dispatch copy is bounded to a preview + locator under the run cwd, @@ -514,7 +771,23 @@ describe('TUI recorded-session terminal snapshots', () => { }) afterAll(async () => { - expect([...observedScenarios].sort()).toEqual(SCENARIOS.map(scenario => scenario.name).sort()) + const scenarioNames = SCENARIOS.map(scenario => scenario.name).sort() + const observedNames = [...observedScenarios].sort() + if (TEST_NAME_FILTERED) { + expect(observedNames).not.toHaveLength(0) + expect(scenarioNames).toEqual(expect.arrayContaining(observedNames)) + } else { + expect(observedNames).toEqual(scenarioNames) + } + for (const [index, scenario] of SCENARIOS.entries()) { + if (scenario.fixture === undefined) continue + const sourceIndex = SCENARIOS.findIndex(candidate => candidate.name === scenario.fixture) + expect(sourceIndex, `${scenario.name} fixture source ${scenario.fixture} must exist`).toBeGreaterThanOrEqual(0) + expect(sourceIndex, `${scenario.name} fixture source must precede it`).toBeLessThan(index) + const source = SCENARIOS[sourceIndex] + expect(source?.fixture, `${scenario.name} fixture source must own its replay files`).toBeUndefined() + expect(source?.recorded, `${scenario.name} fixture source must be recordable`).toBe(true) + } const directories = (await readdir(SNAPSHOTS_DIR, { withFileTypes: true })) .filter(entry => entry.isDirectory()) .map(entry => entry.name) @@ -522,14 +795,14 @@ afterAll(async () => { expect(directories).toEqual(SCENARIOS.map(scenario => scenario.name).sort()) for (const scenario of SCENARIOS) { const expected = [ - 'session.jsonl', + ...scenario.fixture === undefined ? ['session.jsonl'] : [], 'terminal.expected.txt', - ...scenario.seedWorkspace === true ? ['workspace'] : [], + ...scenario.seedWorkspace === true && scenario.fixture === undefined ? ['workspace'] : [], ...Array.from({ length: scenario.childSessions ?? 0 }, (_, index) => `session.${index + 1}.jsonl`), ].sort() expect((await readdir(scenarioDir(scenario))).sort()).toEqual(expected) for (const fixture of ['session.jsonl', ...childFixturePaths(scenario).map(path => basename(path))]) { - const content = await readFile(join(scenarioDir(scenario), fixture), 'utf8') + const content = await readFile(join(fixtureDir(scenario), fixture), 'utf8') expect(scrubRequestHeaders(content), `${scenario.name}/${fixture} carries request-header bulk`).toBe(content) } } diff --git a/apps/web/tests/live-interactions.e2e.ts b/apps/web/tests/live-interactions.e2e.ts index 186c71be11..387faab3b7 100644 --- a/apps/web/tests/live-interactions.e2e.ts +++ b/apps/web/tests/live-interactions.e2e.ts @@ -28,14 +28,14 @@ import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './suppor const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/live-interactions', import.meta.url)) const FIXTURE = join(SNAPSHOT_DIR, 'session.jsonl') // One golden pins the stable mid-turn loading state; the other three capture -// what the user is left looking at after cancel, after a non-retryable failure -// (pins the FIXME(web-error-surface) gap as a reviewable artifact: NO error -// copy in the tree), and after retry recovery. +// what the user is left looking at after cancel, after a non-retryable failure, +// and after retry recovery. const CANCEL_EXPECTED = join(SNAPSHOT_DIR, 'cancel.expected.md') const LOADING_EXPECTED = join(SNAPSHOT_DIR, 'loading.expected.md') const ERROR_EXPECTED = join(SNAPSHOT_DIR, 'error-auth.expected.md') const RETRY_EXPECTED = join(SNAPSHOT_DIR, 'retry.expected.md') const MODE = webSnapshotMode() +const AUTH_PROVIDER_MESSAGE = 'Authentication Fails, Your api key: sk-preview-secret is invalid' // The recorded base: one text-only turn whose derived script the sidecars // patch. Kept deliberately tool-free so the derived script is exactly one @@ -158,7 +158,7 @@ describe('web e2e: live-turn interactions (cancel / error / retry)', () => { it.skipIf(MODE === 'record')('surfaces a non-retryable AUTH failure without retrying', async () => { await launch(() => ({ - patches: [{ at: 0, entry: { kind: 'throw', chunks: [], message: 'invalid api key', code: 'AUTH' } }], + patches: [{ at: 0, entry: { kind: 'throw', chunks: [], message: AUTH_PROVIDER_MESSAGE, code: 'AUTH' } }], })) onTestFailed(() => saveFailureShot(page, 'web-e2e-error-auth')) const { settled } = await sendPrompt() @@ -166,28 +166,28 @@ describe('web e2e: live-turn interactions (cancel / error / retry)', () => { expect(turnEndReasons(sessionEvents).at(-1)).toBe('error') // AUTH is outside llm-retry's retryable set: no retry record. expect(sessionEvents.filter(e => e.type === 'llm/retry').length).toBe(0) - // Product gap found by this lane, pinned as-is: the client consumes no - // agent/error frames and a pre-chunk failure freezes no partial, so THIS - // failure renders no error copy anywhere — the user sees the send simply - // stop. FIXME(web-error-surface): assert visible error text here once the - // web UI grows an error rendering; until then the pinned contract is - // "no crash, composer recovers, turn logged as error". await expect.poll(() => page.locator('textarea').first().isEnabled(), { timeout: 10_000 }).toBe(true) expect(await page.locator('[data-streaming="true"]').count()).toBe(0) - // The blank workspace also has an enabled composer. Wait for the driven - // session's only visible message before capturing its no-error-copy state. - await expect.poll(() => page.getByText(PROMPT, { exact: true }).first().isVisible(), { timeout: 10_000 }).toBe(true) - // Golden of the same gap: the prompt bubble alone, no error copy in the - // tree — the diff that changes when web-error-surface lands. + const errorStatus = page.getByRole('status').filter({ hasText: 'This turn failed' }) + await errorStatus.waitFor({ timeout: 10_000 }) + expect(await errorStatus.textContent()).toContain('API key is invalid') + expect(await errorStatus.textContent()).toContain('AUTH') + expect(await page.locator('body').textContent()).not.toContain('sk-preview-secret') const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold!.workspaceCwd) await compareOrRefreshGolden(ERROR_EXPECTED, snapshot, MODE) + await page.getByRole('tab', { name: 'Trajectory' }).click() + const requestMarker = page.locator('tr[data-request-only="true"]').last() + .getByRole('button', { name: /Request #/ }) + await requestMarker.click() + await page.getByText('API key is invalid', { exact: true }).waitFor({ timeout: 10_000 }) + expect(await page.locator('body').textContent()).not.toContain('sk-preview-secret') expect(tripwire.pageErrors).toEqual([]) expect(tripwire.warnings).toEqual([]) }, 120_000) it.skipIf(MODE === 'record')('keeps a terminal request marker inside the trajectory table', async () => { await launch(() => ({ - patches: [{ at: 0, entry: { kind: 'throw', chunks: [], message: 'invalid api key', code: 'AUTH' } }], + patches: [{ at: 0, entry: { kind: 'throw', chunks: [], message: AUTH_PROVIDER_MESSAGE, code: 'AUTH' } }], })) const { settled } = await sendPrompt() await settled diff --git a/apps/web/tests/navigation-panes.e2e.ts b/apps/web/tests/navigation-panes.e2e.ts index 87e19a6915..d6fe3d0942 100644 --- a/apps/web/tests/navigation-panes.e2e.ts +++ b/apps/web/tests/navigation-panes.e2e.ts @@ -147,14 +147,21 @@ describe('web e2e: navigation & panes over a rich seeded session', () => { await expect.poll(() => page.locator('tr[data-turn-start="true"]').count(), { timeout: 15_000 }).toBe(2) await expect.poll(() => page.getByRole('columnheader').count(), { timeout: 10_000 }).toBe(0) await page.locator('tr[data-kind="tool"]').first().click() - await expect.poll(() => page.getByRole('complementary', { name: 'Event details' }).count(), { timeout: 10_000 }).toBe(1) + const details = page.getByRole('complementary', { name: 'Event details' }) + await expect.poll(() => details.count(), { timeout: 10_000 }).toBe(1) + await page.evaluate(() => { document.body.setAttribute('data-ds-dark-theme', '') }) + const darkSummarySurfaces = await details.getByRole('heading', { name: 'Payload' }).evaluate(heading => ({ + heading: getComputedStyle(heading).backgroundColor, + panel: getComputedStyle(heading.closest('[aria-label="Event details"]')!).backgroundColor, + })) + expect(darkSummarySurfaces.heading).toBe(darkSummarySurfaces.panel) + await page.evaluate(() => { document.body.removeAttribute('data-ds-dark-theme') }) await page.getByRole('tab', { name: 'Result' }).click() await expect.poll(() => page.getByText('NAVIGATION_OK', { exact: false }).count(), { timeout: 10_000 }).toBeGreaterThanOrEqual(1) const snapshot = (await captureStableAria(page, '[class*="viewArea"]', scaffold.workspaceCwd)) .split(SEED_ID).join('{{seededId}}') await compareOrRefreshGolden(TRAJECTORY_EXPECTED, snapshot, MODE) - await page.getByRole('complementary', { name: 'Event details' }) - .getByRole('button', { name: 'Close details' }).click() + await details.getByRole('button', { name: 'Close details' }).click() }, 60_000) it.skipIf(MODE === 'record')('focuses the ledger by dragging an overview interval', async () => { diff --git a/apps/web/tests/queue-actions.e2e.ts b/apps/web/tests/queue-actions.e2e.ts index 57b8afb4ff..006b2816cd 100644 --- a/apps/web/tests/queue-actions.e2e.ts +++ b/apps/web/tests/queue-actions.e2e.ts @@ -1,16 +1,16 @@ // Keyless browser coverage for pending queue actions through the shipped Web -// composition and real HTTP/SSE wire. A replay override parks the active turn -// so two ordinary follow-ups remain addressable while the page edits one and -// removes one. The queue uses an existing recorded model -// call; this scenario owns only the user-visible mid-turn golden. +// composition and real HTTP/SSE wire. Replay overrides park consecutive turns +// so the page can edit and remove exact occurrences, then stop the active turn +// while proving the preserved Queue advances in FIFO order. import { existsSync } from 'node:fs' -import { mkdtemp, rm, writeFile } from 'node:fs/promises' +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { fileURLToPath } from 'node:url' import { join } from 'node:path' import type { Browser, Page } from 'playwright' import { chromium } from 'playwright' import { afterEach, describe, expect, it, onTestFailed } from 'vitest' +import { deriveReplayScript, parseSessionLog, type ReplayEntry } from '@deepseek-ai/dsh-llm-replay' import type { SessionEvent } from '@deepseek-ai/dsh-session' import { assertFixtureInventory, captureStableAria, compareOrRefreshGolden, @@ -22,6 +22,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/queue-actions', import.m const FIXTURE = fileURLToPath(new URL('./snapshots/live-interactions/session.jsonl', import.meta.url)) const COLLAPSED_EXPECTED = join(SNAPSHOT_DIR, 'collapsed.expected.md') const EDITING_EXPECTED = join(SNAPSHOT_DIR, 'editing.expected.md') +const PRESERVED_EXPECTED = join(SNAPSHOT_DIR, 'preserved.expected.md') const UI_EXPECTED = join(SNAPSHOT_DIR, 'ui.expected.md') const MODE = webSnapshotMode() @@ -29,6 +30,12 @@ const ACTIVE_PROMPT = 'Reply with a one-sentence description of event sourcing, const REMOVE = 'Queue item to remove' const EDIT = 'Queue item to edit' const EDITED = 'Edited queue item' +const TAIL = 'Queue item preserved after stop' + +/** Durable turn-end classifications observed by the scenario. */ +function turnEndReasons(events: readonly SessionEvent[]): string[] { + return events.flatMap(event => event.type === 'turn/end' ? [event.data.reason.kind] : []) +} describe('web e2e: queue row actions', () => { let scaffold: WebScaffold | undefined @@ -52,13 +59,19 @@ describe('web e2e: queue row actions', () => { if (failures.length > 1) throw new AggregateError(failures, 'queue-actions teardown failed') }) - it.skipIf(MODE === 'record')('edits and removes exact pending occurrences', async () => { + it.skipIf(MODE === 'record')('edits and removes exact occurrences and preserves Queue across stop', async () => { overrideDir = await mkdtemp(join(tmpdir(), 'dsh-web-queue-actions-')) const readyFile = join(overrideDir, '.hang-ready') + const nextReadyFile = join(overrideDir, '.next-hang-ready') const overridePath = join(overrideDir, 'replay.override.json') - await writeFile(overridePath, JSON.stringify({ - patches: [{ at: 0, entry: { kind: 'hang', readyFile } }], - })) + const recorded = deriveReplayScript(parseSessionLog(await readFile(FIXTURE, 'utf8'))) + expect(recorded).toHaveLength(1) + const replay: ReplayEntry[] = [ + { kind: 'hang', readyFile }, + { kind: 'hang', readyFile: nextReadyFile }, + recorded[0]!, + ] + await writeFile(overridePath, JSON.stringify(replay)) const sessionEvents: SessionEvent[] = [] scaffold = await launchWebScaffold({ replayFixture: FIXTURE, replayOverride: overridePath }) @@ -135,17 +148,34 @@ describe('web e2e: queue row actions', () => { expect(tripwire.pageErrors).toEqual([]) expect(tripwire.warnings).toEqual([]) - const editedRow = page.getByText(EDITED, { exact: true }).locator('..') - await editedRow.getByRole('button', { name: 'Remove queued message' }).click() - await expect.poll(() => page.getByText(EDITED, { exact: true }).count()).toBe(0) + await input.fill(TAIL) + await input.press('Enter') + await expect.poll( + () => page.getByRole('button', { name: 'Remove queued message' }).count(), + { timeout: 10_000 }, + ).toBe(2) + + await page.getByRole('button', { name: 'Stop generating' }).click() + await expect.poll(() => existsSync(nextReadyFile), { timeout: 15_000 }).toBe(true) + await page.getByText(TAIL, { exact: true }).waitFor() + await expect.poll(() => page.getByRole('button', { name: 'Remove queued message' }).count()) + .toBe(1) + + const preservedSnapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd) + await compareOrRefreshGolden(PRESERVED_EXPECTED, preservedSnapshot, MODE) + await page.getByRole('button', { name: 'Stop generating' }).click() await settled + expect(turnEndReasons(sessionEvents)).toEqual(['aborted', 'aborted', 'completed']) + expect(sessionEvents.filter(event => event.type === 'user/message' && event.data.source.kind === 'user')) + .toHaveLength(3) + await expect.poll(() => page.locator('[data-queue-dock]').count()).toBe(0) }, 120_000) it.skipIf(MODE === 'record')('keeps its snapshot inventory closed', async () => { await assertFixtureInventory( SNAPSHOT_DIR, - ['collapsed.expected.md', 'editing.expected.md', 'ui.expected.md'], + ['collapsed.expected.md', 'editing.expected.md', 'preserved.expected.md', 'ui.expected.md'], ) }) }) diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts index ea39e2d29b..249ff619cb 100644 --- a/apps/web/tests/scaffold.ts +++ b/apps/web/tests/scaffold.ts @@ -496,7 +496,7 @@ export async function seedSession(scaffold: WebScaffold, fixtureText: string, id * volatility collapse to stable tokens. */ function normalizeAria(snapshot: string, workspaceCwd: string): string { - // The header breadcrumb renders the workspace's basename, not the full + // The session heading renders the workspace's basename, not the full // path, so both spellings must collapse to the token. const base = workspaceCwd.split('/').pop()! return snapshot diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts index 9acb0fa136..6a4c079953 100644 --- a/apps/web/tests/seeded-history.e2e.ts +++ b/apps/web/tests/seeded-history.e2e.ts @@ -357,6 +357,27 @@ describe('web e2e: seeded history renders through cold resume', () => { await compareOrRefreshGolden(COMMAND_ROW_EXPECTED, snapshot, MODE) }, 60_000) + it.skipIf(MODE === 'record')('fits short injected context without a scrollport', async () => { + const agent = scaffold.ctx.agents.get(SessionId(SEED_ID)) + if (agent === undefined) throw new Error('seeded session did not attach an agent') + agent.inject(createUserMessage({ + content: [{ type: 'text', text: 'Short injected context.' }], + source: { kind: 'plugin', plugin: 'fixture' }, + })) + + const disclosures = page.getByRole('button', { name: 'Context injection' }) + await expect.poll(() => disclosures.count(), { timeout: 10_000 }).toBe(2) + const disclosure = disclosures.nth(1) + await disclosure.click() + await expect.poll(() => disclosure.getAttribute('aria-expanded')).toBe('true') + + const body = page.locator('[data-context-injection-body]') + const bodyBox = await body.boundingBox() + if (bodyBox === null) throw new Error('short context disclosure geometry is not measurable') + expect(bodyBox.height).toBeLessThan(141) + expect(await body.evaluate(element => element.scrollHeight > element.clientHeight)).toBe(false) + }) + it.skipIf(MODE === 'record')('issued zero model calls and stayed clean', async () => { // No replay fixture was installed and the llm seam is open — any stray // stream would have failed the turn loudly. Cleanliness pins the wire. diff --git a/apps/web/tests/shipped-composition.e2e.ts b/apps/web/tests/shipped-composition.e2e.ts new file mode 100644 index 0000000000..0cad833303 --- /dev/null +++ b/apps/web/tests/shipped-composition.e2e.ts @@ -0,0 +1,83 @@ +// Boots the shipped Web composition over the built dist this lane already uses +// and asserts what that composition produces: the model-visible tool catalog +// and the sandbox/approval knobs it ships with. No browser and no model call — +// these are composition facts, and the browser scenarios in this lane cover the +// surface itself. +import { tmpdir } from 'node:os' +import { afterEach, expect, it } from 'vitest' +import { canonicalPath, writableRoots } from '@deepseek-ai/dsh-sandbox' +// Empty type imports carry the tools/sandboxPolicy/approval Context merges. +import type {} from '@deepseek-ai/dsh-tools' +import type {} from '@deepseek-ai/dsh-sandbox-policy' +import type {} from '@deepseek-ai/dsh-user-approval' +import { launchWebScaffold, type WebScaffold } from './scaffold.ts' + +/** + * The catalog the shipped Web composition puts in front of the model, minus the + * ripgrep-dependent pair below. The absences are deliberate, not incidental + * gaps: the `cordis_*` toolset executes model-written JavaScript that no + * sandbox row confines, `web_fetch` chooses its own request target, and + * `mcp_*` servers spawn outside `ctx.bash`. The composition Agent Note owns the + * rationale and its sources. + */ +const EXPECTED_TOOLS = [ + 'ask_user_question', + 'bash', + 'create_goal', + 'edit', + 'exit_plan_mode', + 'get_goal', + 'ralph', + 'read', + 'session_event_read', + 'session_event_search', + 'session_event_trace', + 'session_search', + 'session_trace', + 'skill', + 'str_replace_editor', + 'subagent', + 'subagent_fork', + 'task_kill', + 'task_list', + 'task_output', + 'todo_write', + 'update_goal', + 'web_search', + 'workflow', + 'write', +] + +/** + * `glob` and `grep` come from `dsh-tool-fs-search`, which probes `command -v rg` + * through the mounted bash executor at load and registers neither tool when + * ripgrep is absent. That is a host dependency, not a composition decision, so the + * pair is asserted separately — present together or absent together. + */ +const RIPGREP_TOOLS = ['glob', 'grep'] + +let scaffold: WebScaffold | undefined + +afterEach(async () => { + await scaffold?.close() + scaffold = undefined +}) + +it('assembles the shipped Web catalog and keeps its access default', async () => { + scaffold = await launchWebScaffold() + const names = scaffold.ctx.tools.schemas().map(schema => schema.name).sort() + expect(names.filter(name => !RIPGREP_TOOLS.includes(name))).toEqual(EXPECTED_TOOLS) + expect([[], RIPGREP_TOOLS]).toContainEqual(names.filter(name => RIPGREP_TOOLS.includes(name))) + // `workspace-write` is not "the workspace and nothing else": the shared roots + // helper always admits the temp directories too. Pinning it against an + // explicit mode keeps the claim independent of this surface's default, and + // keeps a future boundary test from being run inside /tmp — where an + // "escape" write succeeds by design and reads as a sandbox failure. + expect(writableRoots(scaffold.ctx.sandboxPolicy.resolve({ mode: 'workspace-write' }))).toEqual( + expect.arrayContaining([canonicalPath('/tmp'), canonicalPath(tmpdir())]), + ) + // The Web surface keeps its shipped access default; the base's confined one + // reaches the TUI. Pinning both keeps a base change from moving Web silently. + expect(scaffold.ctx.sandboxPolicy.defaultMode).toBe('danger-full-access') + expect(scaffold.ctx.approval.config.policy).toBe('never') +}, 120_000) diff --git a/apps/web/tests/snapshots/code-mode-round/ui.expected.md b/apps/web/tests/snapshots/code-mode-round/ui.expected.md index 183bd366a0..9b539fc432 100644 --- a/apps/web/tests/snapshots/code-mode-round/ui.expected.md +++ b/apps/web/tests/snapshots/code-mode-round/ui.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - 'button "Using ONE run_code program: run" [disabled]' + - 'heading "Using ONE run_code program: run" [level=1]' - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/cordis-tool-round/ui.expected.md b/apps/web/tests/snapshots/cordis-tool-round/ui.expected.md index 636b1e6d28..6445b0fd8b 100644 --- a/apps/web/tests/snapshots/cordis-tool-round/ui.expected.md +++ b/apps/web/tests/snapshots/cordis-tool-round/ui.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Use only Cordis tools. First" [disabled] + - heading "Use only Cordis tools. First" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/fresh-round-trip/ui.expected.md b/apps/web/tests/snapshots/fresh-round-trip/ui.expected.md index 3f7fa52b2e..32b0d9de50 100644 --- a/apps/web/tests/snapshots/fresh-round-trip/ui.expected.md +++ b/apps/web/tests/snapshots/fresh-round-trip/ui.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Use the bash tool to" [disabled] + - heading "Use the bash tool to" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/lifecycle-chrome/command-menu.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/command-menu.expected.md index 47ba98cf05..1da9b9a45e 100644 --- a/apps/web/tests/snapshots/lifecycle-chrome/command-menu.expected.md +++ b/apps/web/tests/snapshots/lifecycle-chrome/command-menu.expected.md @@ -1,6 +1,7 @@ - listbox "Trigger suggestions": - text: Commands - - option "goal set or view the goal for a long-running task" [selected] + - option "compact Compact older conversation history" [selected] + - option "goal set or view the goal for a long-running task" - option "permission Switch the permission preset (sandbox mode + approval policy)" - option "plan Enter or leave plan mode" - option "model Select the model for this conversation" diff --git a/apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md index f58e5b77f2..35921f50ce 100644 --- a/apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md +++ b/apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Reply with the single word" [disabled] + - heading "Reply with the single word" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/live-interactions/cancel.expected.md b/apps/web/tests/snapshots/live-interactions/cancel.expected.md index 3333237798..2354cc2b66 100644 --- a/apps/web/tests/snapshots/live-interactions/cancel.expected.md +++ b/apps/web/tests/snapshots/live-interactions/cancel.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Reply with a one-sentence description" [disabled] + - heading "Reply with a one-sentence description" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/live-interactions/error-auth.expected.md b/apps/web/tests/snapshots/live-interactions/error-auth.expected.md index c65690aa73..05efb17f29 100644 --- a/apps/web/tests/snapshots/live-interactions/error-auth.expected.md +++ b/apps/web/tests/snapshots/live-interactions/error-auth.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Reply with a one-sentence description" [disabled] + - heading "Reply with a one-sentence description" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" @@ -13,6 +12,9 @@ - img - img - text: Context injection +- status: + - text: This turn failedAPI key is invalid + - code: AUTH - textbox "Message the agent" - button "Commands": - img diff --git a/apps/web/tests/snapshots/live-interactions/loading.expected.md b/apps/web/tests/snapshots/live-interactions/loading.expected.md index b442b4345a..ecabb944c2 100644 --- a/apps/web/tests/snapshots/live-interactions/loading.expected.md +++ b/apps/web/tests/snapshots/live-interactions/loading.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Reply with a one-sentence description" [disabled] + - heading "Reply with a one-sentence description" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/live-interactions/retry.expected.md b/apps/web/tests/snapshots/live-interactions/retry.expected.md index f34dddd7dd..4b57ca7a98 100644 --- a/apps/web/tests/snapshots/live-interactions/retry.expected.md +++ b/apps/web/tests/snapshots/live-interactions/retry.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Reply with a one-sentence description" [disabled] + - heading "Reply with a one-sentence description" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/message-actions/ui.expected.md b/apps/web/tests/snapshots/message-actions/ui.expected.md index 613e9a3605..257318c27f 100644 --- a/apps/web/tests/snapshots/message-actions/ui.expected.md +++ b/apps/web/tests/snapshots/message-actions/ui.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Use the read tool twice" [disabled] + - heading "Use the read tool twice" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/plan-review/approved.expected.md b/apps/web/tests/snapshots/plan-review/approved.expected.md index c971a6b2e4..c7f5c6d664 100644 --- a/apps/web/tests/snapshots/plan-review/approved.expected.md +++ b/apps/web/tests/snapshots/plan-review/approved.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - 'button "Plan a small change: add" [disabled]' + - 'heading "Plan a small change: add" [level=1]' - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/question-composer/answered.expected.md b/apps/web/tests/snapshots/question-composer/answered.expected.md index fec84d06db..d916f82f4b 100644 --- a/apps/web/tests/snapshots/question-composer/answered.expected.md +++ b/apps/web/tests/snapshots/question-composer/answered.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Use the ask_user_question tool to" [disabled] + - heading "Use the ask_user_question tool to" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/queue-actions/collapsed.expected.md b/apps/web/tests/snapshots/queue-actions/collapsed.expected.md index 829f21a70f..052df599d7 100644 --- a/apps/web/tests/snapshots/queue-actions/collapsed.expected.md +++ b/apps/web/tests/snapshots/queue-actions/collapsed.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Reply with a one-sentence description" [disabled] + - heading "Reply with a one-sentence description" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/queue-actions/editing.expected.md b/apps/web/tests/snapshots/queue-actions/editing.expected.md index 169dde2c51..98b234ec69 100644 --- a/apps/web/tests/snapshots/queue-actions/editing.expected.md +++ b/apps/web/tests/snapshots/queue-actions/editing.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Reply with a one-sentence description" [disabled] + - heading "Reply with a one-sentence description" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/queue-actions/preserved.expected.md b/apps/web/tests/snapshots/queue-actions/preserved.expected.md new file mode 100644 index 0000000000..335610097d --- /dev/null +++ b/apps/web/tests/snapshots/queue-actions/preserved.expected.md @@ -0,0 +1,43 @@ +- banner: + - heading "Reply with a one-sentence description" [level=1] + - tablist: + - tab "Chat" [selected] + - tab "Trajectory" +- text: Reply with a one-sentence description of event sourcing, then stop. {{clock}} +- button "Copy": + - img +- button "Branch into a new conversation": + - img +- button "Context injection": + - img + - img + - text: Context injection +- paragraph: partial +- text: Stopped +- button "Copy": + - img +- button "Branch into a new conversation": + - img +- text: {{clock}} Edited queue item {{clock}} +- button "Copy": + - img +- button "Branch into a new conversation": + - img +- paragraph: partial +- status: Deep diving... +- list: + - listitem: + - text: Queue item preserved after stop + - button "Edit queued message": + - img + - button "Remove queued message": + - img +- textbox "Message the agent" +- button "Commands": + - img +- 'button "Access mode, current: Full access"': Full access +- button "Select model, current DeepSeek-V4-Flash": + - text: DeepSeek-V4-Flash + - img +- button "Stop generating" +- text: 1 turns · 1 steps Input 0 tok · Output 0 tok diff --git a/apps/web/tests/snapshots/queue-actions/ui.expected.md b/apps/web/tests/snapshots/queue-actions/ui.expected.md index e2c91f7584..664aaa7041 100644 --- a/apps/web/tests/snapshots/queue-actions/ui.expected.md +++ b/apps/web/tests/snapshots/queue-actions/ui.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Reply with a one-sentence description" [disabled] + - heading "Reply with a one-sentence description" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/seeded-history/command-row.expected.md b/apps/web/tests/snapshots/seeded-history/command-row.expected.md index 0173726c38..ceeb45dd8a 100644 --- a/apps/web/tests/snapshots/seeded-history/command-row.expected.md +++ b/apps/web/tests/snapshots/seeded-history/command-row.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Use the read tool twice" [disabled] + - heading "Use the read tool twice" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/seeded-history/ui.expected.md b/apps/web/tests/snapshots/seeded-history/ui.expected.md index 0062b6cfab..3cee5a52de 100644 --- a/apps/web/tests/snapshots/seeded-history/ui.expected.md +++ b/apps/web/tests/snapshots/seeded-history/ui.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Use the read tool twice" [disabled] + - heading "Use the read tool twice" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/steering/mid-steer.expected.md b/apps/web/tests/snapshots/steering/mid-steer.expected.md index 27b40ef442..671e39a351 100644 --- a/apps/web/tests/snapshots/steering/mid-steer.expected.md +++ b/apps/web/tests/snapshots/steering/mid-steer.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Use the ask_user_question tool to" [disabled] + - heading "Use the ask_user_question tool to" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/steering/settled.expected.md b/apps/web/tests/snapshots/steering/settled.expected.md index 92269104ad..ba04efc20f 100644 --- a/apps/web/tests/snapshots/steering/settled.expected.md +++ b/apps/web/tests/snapshots/steering/settled.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Use the ask_user_question tool to" [disabled] + - heading "Use the ask_user_question tool to" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" @@ -21,7 +20,7 @@ - img - img - text: Ask question 1/1 answered -- text: "Interjection Interjection: include the word BANANA in your final reply." +- text: "Interjection: include the word BANANA in your final reply." - button "Think The user selected \"Yes\" and wants me to include the word \"BANANA\" in my final reply. Let me acknowledge their answer.": - img - img diff --git a/apps/web/tests/snapshots/web-search-round/ui.expected.md b/apps/web/tests/snapshots/web-search-round/ui.expected.md index 37d53a0df6..b8eb6a1156 100644 --- a/apps/web/tests/snapshots/web-search-round/ui.expected.md +++ b/apps/web/tests/snapshots/web-search-round/ui.expected.md @@ -1,6 +1,5 @@ - banner: - - navigation "Session hierarchy": - - button "Use web_search to search exactly" [disabled] + - heading "Use web_search to search exactly" [level=1] - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/startup-auto-selection.e2e.ts b/apps/web/tests/startup-auto-selection.e2e.ts new file mode 100644 index 0000000000..f3a953c1e6 --- /dev/null +++ b/apps/web/tests/startup-auto-selection.e2e.ts @@ -0,0 +1,119 @@ +// Web e2e scenario: startup auto-selection keeps the hero on screen. +// +// A page load with a workspace already registered runs +// `WorkspacesService.startInitialSelection`: it connects the most recent +// workspace and opens its blank session. `openState` flips to `loading` the +// moment `open()` lands, which used to drive `data-phase=settling` on the +// conversation root — `visibility:hidden` over the composer seat and the +// header for the whole `session.history` round-trip, so the center column went +// blank and repainted, reading as a full-page refresh on every launch. +// +// The unit spec pins the phase condition over hand-built stores. What only the +// assembled application can show is that the path a user actually takes +// reaches it: the real selection service, the real client session opening over +// the real /api transport, and a real browser deciding what is painted. +// +// The round-trip against a loopback host is far too fast to observe, so this +// scenario HOLDS the `session.history` response open at the browser's network +// boundary and asserts the visible frame while it is in flight. That gate is +// what makes the assertions non-vacuous: with the exemption reverted the held +// window is exactly when `settling` is painted and the composer is hidden. +// +// Zero model calls: registering a workspace and opening its blank session are +// host RPCs with no model involvement. A stray stream would fail loud with +// NO_ADAPTER. +import type { Browser, Page } from 'playwright' +import { chromium } from 'playwright' +import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' +import { acknowledgeReloadConnectionLoss, launchWebScaffold, watchConsole, type WebScaffold } from './scaffold.ts' +import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts' + +/** Wire path of the history round-trip the conversation root waits out (POST /api/session.history). */ +const HISTORY_ROUTE = '**/api/session.history' + +/** + * The conversation root's own phase attribute. `div` disambiguates it from the + * composer textarea, which carries an unrelated `data-phase` of its own. + */ +const ROOT_PHASE = 'div[data-phase]' + +/** Every distinct `data-phase` the conversation root shows, in order, across one page load. */ +function recordedPhases(page: Page): Promise { + return page.evaluate(() => (window as unknown as { __conversationPhases: string[] }).__conversationPhases) +} + +describe('web e2e: startup auto-selection', () => { + let scaffold: WebScaffold + let browser: Browser + let page: Page + let tripwire: ReturnType + + beforeAll(async () => { + scaffold = await launchWebScaffold({}) + browser = await chromium.launch() + page = await newEnglishPage(browser) + tripwire = watchConsole(page) + await page.goto(scaffold.baseUrl, { waitUntil: 'load' }) + await page.waitForSelector('[class*="frame"]', { timeout: 30_000 }) + // A registered workspace is the precondition for auto-selection: the first + // load has nothing to select, so the reload below is the path under test. + await connectFreshWorkspace(page, scaffold.workspaceCwd, 'startup-auto-selection') + }, 180_000) + + afterAll(async () => { + await browser?.close() + await scaffold?.close() + }) + + it('keeps the hero and the composer on screen while the auto-selected blank session opens', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-startup-auto-selection')) + // Runs before any page script on the reload below, so the first phase the + // root ever renders is recorded, not just the ones after a listener attaches. + await page.addInitScript(() => { + const phases: string[] = [] + ;(window as unknown as { __conversationPhases: string[] }).__conversationPhases = phases + setInterval(() => { + const phase = document.querySelector('div[data-phase]')?.getAttribute('data-phase') + if (phase === null || phase === undefined) return + if (phases[phases.length - 1] !== phase) phases.push(phase) + }, 8) + }) + + let releaseHistory = (): void => {} + const historyHeld = new Promise((resolve) => { releaseHistory = resolve }) + let historyRequested = (): void => {} + const historyInFlight = new Promise((resolve) => { historyRequested = resolve }) + let gated = false + await page.route(HISTORY_ROUTE, async (route) => { + // Only the auto-selection's own round-trip is held; later pages must not + // deadlock behind a gate this test has already released. + if (gated) { await route.continue(); return } + gated = true + historyRequested() + await historyHeld + await route.continue() + }) + + const warningsBefore = tripwire.warnings.length + await page.reload({ waitUntil: 'commit' }) + await historyInFlight + + // The frame a user sees while the session is still opening: hero phase, the + // hero title, and a composer that is actually painted (`settling` hides the + // seat with `visibility:hidden`, which Playwright reports as not visible). + await page.waitForSelector(ROOT_PHASE, { timeout: 15_000 }) + expect(await page.locator(ROOT_PHASE).first().getAttribute('data-phase')).toBe('hero') + expect(await page.getByText("Let's start building").isVisible()).toBe(true) + expect(await page.locator('textarea').first().isVisible()).toBe(true) + + releaseHistory() + await page.locator('textarea:enabled[placeholder="Describe what you want to build"]') + .waitFor({ timeout: 15_000 }) + acknowledgeReloadConnectionLoss(tripwire, warningsBefore) + + // Settling is not merely absent from the frame sampled above: the root + // never entered it at any point of the load. + expect(await recordedPhases(page)).toEqual(['hero']) + expect(tripwire.pageErrors).toEqual([]) + }, 120_000) +}) diff --git a/apps/web/tests/steering.e2e.ts b/apps/web/tests/steering.e2e.ts index 6bd369ea2c..a329f2c02e 100644 --- a/apps/web/tests/steering.e2e.ts +++ b/apps/web/tests/steering.e2e.ts @@ -1,16 +1,15 @@ -// Web e2e scenario: mid-turn steering, end to end. The product composer -// deliberately exposes Queue only, so the steer is POSTed from the page -// itself over the same same-origin /api transport the client uses. -// TODO(web-steer-ui): Drive this through a dedicated steering interaction -// once one exists. Everything downstream is product: the gateway -// routes mode:'steer' to Agent.steer, the loop drains it at the step -// boundary into a durable steering/message event, the SSE mux pushes it, and -// the transcript renders the badged interjection bubble. The question -// composer supplies the deterministic mid-turn window: while ask_user_question -// blocks, the turn is provably running, so record and replay perform the -// identical steer-then-answer sequence with zero timing dependence — and the -// recorded final reply proves the steer reached the MODEL (it obeys an -// instruction that only the steering message carries). +// Web e2e scenario: mid-turn steering over the host wire. The Web UI has no +// steer entry, so the steer is POSTed from the page over the same +// same-origin /api transport the client uses. Everything downstream is +// product: the gateway routes mode:'steer' to Agent.steer, the loop drains +// it at the step boundary into a durable steering/message event, the SSE mux +// pushes it, and the transcript shows the text as a plain bubble (no +// interjection chrome). The question composer supplies the deterministic +// mid-turn window: while ask_user_question blocks, the turn is provably +// running, so record and replay perform the identical steer-then-answer +// sequence with zero timing dependence — and the recorded final reply proves +// the steer reached the MODEL (it obeys an instruction that only the +// steering message carries). import { readFile } from 'node:fs/promises' import { fileURLToPath } from 'node:url' import { join } from 'node:path' @@ -29,11 +28,11 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/steering', import.meta.u const FIXTURE = join(SNAPSHOT_DIR, 'session.jsonl') // Two goldens for the two distinct states this interaction produces: the // mid-turn moment (steer ACCEPTED but deliberately invisible — the loop -// drains steering at the step boundary, so no interjection bubble exists -// while the question still blocks the step) and the settled transcript -// (badged bubble in place, final reply obeying it). The pair pins the -// timing semantics visually: if the client ever starts rendering pending -// steers eagerly, the mid-steer golden flips first. +// drains steering at the step boundary, so no steering text exists while +// the question still blocks the step) and the settled transcript (plain +// bubble in place, final reply obeying it). The pair pins the timing +// semantics visually: if the client ever starts rendering pending steers +// eagerly, the mid-steer golden flips first. const MID_EXPECTED = join(SNAPSHOT_DIR, 'mid-steer.expected.md') const SETTLED_EXPECTED = join(SNAPSHOT_DIR, 'settled.expected.md') const MODE = webSnapshotMode() @@ -80,7 +79,7 @@ describe('web e2e: mid-turn steering lands durably and visibly', () => { await scaffold?.close() }) - it('steers during the blocked step; the interjection is logged, rendered, and obeyed', async () => { + it('steers during the blocked step; the message is logged, rendered, and obeyed', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-steering')) if (MODE !== 'record') { // The steer must NOT be a user/message — it lands as steering/message. @@ -118,10 +117,9 @@ describe('web e2e: mid-turn steering lands durably and visibly', () => { if (MODE !== 'record') { // Mid-turn golden: the ACCEPTED steer is durable in the inbox but the // loop drains steering only at the step boundary, so no steering/message - // exists yet and no interjection bubble renders — the composer still - // blocks, alone. The DOM is stable here (no further SSE frames can - // arrive until the question is answered), making this state capturable. - expect(await page.getByText('Interjection', { exact: true }).count()).toBe(0) + // exists yet and no steer text renders — the composer still blocks, + // alone. The DOM is stable here (no further SSE frames can arrive until + // the question is answered), making this state capturable. expect(await page.getByText(STEER, { exact: true }).count()).toBe(0) expect(await page.getByRole('button', { name: 'Edit queued message' }).count()).toBe(0) const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd) @@ -155,14 +153,13 @@ describe('web e2e: mid-turn steering lands durably and visibly', () => { expect(turnEnds).toHaveLength(1) expect((turnEnds[0] as SessionEvent & { data: { reason: { kind: string } } }).data.reason.kind).toBe('completed') - // Visible: the badged interjection bubble plus the reply that obeys it + // Visible: the plain steering bubble plus the reply that obeys it // (steer text + final reply each contain the marker word). - await expect.poll(() => page.getByText('Interjection', { exact: true }).count(), { timeout: 15_000 }).toBe(1) - await expect.poll(() => page.getByText('Interjection:', { exact: false }).count(), { timeout: 10_000 }).toBe(1) + await expect.poll(() => page.getByText(STEER, { exact: true }).count(), { timeout: 15_000 }).toBe(1) await expect.poll(() => page.getByText('BANANA', { exact: false }).count(), { timeout: 10_000 }).toBeGreaterThanOrEqual(2) expect(await page.locator('[data-question-key]').count()).toBe(0) - // Settled golden: badge + interjection between the question round trip - // and the obeying reply, composer takeover gone. + // Settled golden: steer text between the question round trip and the + // obeying reply, composer takeover gone. const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd) await compareOrRefreshGolden(SETTLED_EXPECTED, snapshot, MODE) expect(tripwire.pageErrors).toEqual([]) diff --git a/apps/web/tests/workspace-management.e2e.ts b/apps/web/tests/workspace-management.e2e.ts index 95d44d4162..1ffcf6f490 100644 --- a/apps/web/tests/workspace-management.e2e.ts +++ b/apps/web/tests/workspace-management.e2e.ts @@ -1,7 +1,8 @@ // Web e2e scenarios: workspace management — adding a workspace through the // composed directory dialog (its own New folder affordance is the product's -// one creation route), the rename round trip over the real wire -// (workspace.rename RPC + durable registry), duplicate-name pre-check, the +// one creation route), same-basename directory adoption, the rename round +// trip over the real wire (workspace.rename RPC + durable registry), the +// duplicate-name pre-check, the // flat "In one list" view with its persisted group-by preference, the session // hover card and row action menu, and the session archive round trip (row // menu → workspace.archiveSession RPC → durable global set → row hidden @@ -538,6 +539,27 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff expect(tripwire.pageErrors).toEqual([]) }, 90_000) + it('opens folders with identical basenames as distinct workspaces', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-ws-duplicate-basename')) + const firstPath = join(scaffold.workspaceCwd, 'same-basename-a', 'xx') + const secondPath = join(scaffold.workspaceCwd, 'same-basename-b', 'xx') + await mkdir(firstPath, { recursive: true }) + await mkdir(secondPath, { recursive: true }) + + await adoptDirectory(firstPath, { waitForAgent: true }) + await adoptDirectory(secondPath, { waitForAgent: true }) + + const matchingWorkspaces = scaffold.ctx.workspace.list() + .filter(workspace => workspace.title === 'xx') + expect(matchingWorkspaces.map(workspace => workspace.path).sort()) + .toEqual([firstPath, secondPath].sort()) + await expect.poll( + () => page.locator('button[aria-label="Workspace actions for xx"]').count(), + { timeout: 10_000 }, + ).toBe(2) + expect(tripwire.pageErrors).toEqual([]) + }, 90_000) + it.skipIf(MODE === 'record')('issued zero model calls and stayed clean', async () => { expect(tripwire.warnings).toEqual([]) // The directory-browser aria golden is this spec's one owned artifact; diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json index 42fdadddb1..c795dc7aef 100644 --- a/apps/web/tsconfig.json +++ b/apps/web/tsconfig.json @@ -48,7 +48,9 @@ "tests/queue-actions.e2e.ts", "tests/skill-invocation-policy.e2e.ts", "tests/permission-policy-context.e2e.ts", - "tests/access-confirmation.e2e.ts" + "tests/access-confirmation.e2e.ts", + "tests/shipped-composition.e2e.ts", + "tests/startup-auto-selection.e2e.ts" ], "references": [ { diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts index 7043de4911..1e8eb07210 100644 --- a/apps/web/vite.config.ts +++ b/apps/web/vite.config.ts @@ -22,6 +22,7 @@ export default defineConfig({ { find: /^@deepseek-ai\/dsh-client-web-react$/, replacement: src('../../packages/client/web-react/src/index.ts') }, { find: /^@deepseek-ai\/dsh-client-ui-slots$/, replacement: src('../../packages/client/ui-slots/src/index.ts') }, { find: /^@deepseek-ai\/dsh-client-ui-primitives$/, replacement: src('../../packages/client/ui-primitives/src/index.ts') }, + { find: /^@deepseek-ai\/dsh-client-schema-form$/, replacement: src('../../packages/client/schema-form/src/index.ts') }, { find: /^@deepseek-ai\/dsh-client-modules\/client$/, replacement: src('../../packages/client/modules/src/client/index.ts') }, ], }, diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index 1ee5e3a3aa..e305eb5f42 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.i18n.yaml @@ -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/architecture.md -architecture.md: 929d2d28fd93d06cf18abeeac968860048657faf -architecture.zh.md: c9e495359d804c49181e78b6099c4aa2b1125d92 +architecture.md: 75340b6fb3e4e109974bcb9d9ccabec004d853e1 +architecture.zh.md: 0955a40f3571fe9146c75a6b1094f945fcc5219c diff --git a/docs/architecture.md b/docs/architecture.md index 929d2d28fd..75340b6fb3 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -130,11 +130,11 @@ Adapter failures close their step before `agent/request-error` receives the exac Other failures use `agent/error`. Cancellation and disposal beat recovery. Before request-header commit, the turn signal cancels asynchronous model-capability preparation; undispatched tools get synthetic `tool/call`/`ABORTED_BEFORE_DISPATCH` pairs. Effective `cancel(cause)` emits its cause before queue clearing and abort; observers cannot veto; idle calls emit nothing. Durability records user or parent cancellation as `aborted`, teardown as `disposed`; teardown awaits quiescence. The cause affects reporting, not late result-context handling ([decision](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)). -Turn and step events are turn-enclosed; idle injected `user/message` events may sit between turns. Reload closes an interrupted tail with a synthetic turn end. After close, only `agent/error` reports failures. Each turn has one [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap). +Turn and step events are turn-enclosed. Idle `user/message` and standalone `compact/* { turn: null }` consume no turn; their lock-time markers may interleave with injection. Reload synthesizes interrupted turn ends; `session/end-seed` distinguishes stale compaction orphans from live locks. After close, only `agent/error` reports failures. Each turn has one [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap). ### Agent Handles -`ctx.agents` owns live agents and returns `AgentHandle { agent, dispose() }`. Plugins use full `send()` options or `followup()`, `steer()`, and `inject()` presets; `cancel()` and `whenIdle()` control lifecycle. One awaited disposer coordinates teardown ownership. +`ctx.agents` owns agents, returning `AgentHandle { agent, dispose() }`. Plugins use `send()` or `followup()`, `steer()`, and `inject()` presets; [`reserveTurnAdmission()`](../packages/core/agent/README.md#agent-interface-typests) synchronously reserves idle for durable work without changing queued prompt identity. `cancel()` and `whenIdle()` control lifecycle. Awaited disposal owns teardown. ### Agent Scope @@ -150,7 +150,7 @@ The session log is authoritative. `deriveMessages()` projects model history; raw Durability is a plugin concern. Backends eagerly drain synchronous `session/event` notifications. `session/flush` barriers precede each request and top-level tool dispatch, then follow `turn/end` before another queued turn or idle observation. `SessionPersistence` stores `SessionEvent` directly and metadata in `SessionHeader`; JSONL defaults to checksummed Zstandard, while SQLite shares the contract ([decision](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)). -Log-only events may sit between turns. Owners append through `Session`, flushing only for durability. `session/title` relies on eager persistence and lifecycle drains. Latest title wins with provenance; fallback and provider work never delays responses. Such records are fork boundaries, so forks inherit titles ([decision](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)). +Between turns, owners append log-only events through `Session`, flushing only for durability. `session/title` needs eager persistence and lifecycle drains; manual compaction flushes its bracket before releasing admission. Title work never delays responses; latest wins with provenance. Title records are inherited fork boundaries ([decision](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)). ### Model Content diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index c9e495359d..0955a40f35 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -130,11 +130,11 @@ idle inject: 其他故障使用 `agent/error`。取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消异步模型能力准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 在清空队列和中止前发出原因；观察方不能否决；空闲调用不发事件。持久化层将用户或父级取消记录为 `aborted`，拆卸记录为 `disposed`；拆卸会等待完全停稳。原因只影响报告方式，不影响延迟完成的结果上下文处理（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。 -轮次和步骤事件均位于轮次边界内；空闲时注入的 `user/message` 可以位于两个轮次之间。重新加载会用合成的轮次结束事件闭合中断尾部。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap)。 +轮次和步骤事件均位于轮次边界内。空闲 `user/message` 与独立的 `compact/* { turn: null }` 不占用轮次；其锁定时刻标记可以与注入交错。重新加载会为中断的轮次合成结束事件；`session/end-seed` 区分陈旧的压缩遗留项与活跃锁。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap)。 ### Agent 句柄 -`ctx.agents` 拥有活跃 agent，并返回 `AgentHandle { agent, dispose() }`。插件使用全部 `send()` 选项，或 `followup()`、`steer()` 和 `inject()` 预设；`cancel()` 与 `whenIdle()` 控制生命周期。一个需等待完成的 disposer 协调拆卸归属。 +`ctx.agents` 拥有 agent，返回 `AgentHandle { agent, dispose() }`。插件使用 `send()`，或使用 `followup()`、`steer()` 和 `inject()` 预设；[`reserveTurnAdmission()`](../packages/core/agent/README.md#agent-interface-typests) 为持久工作同步预留空闲状态，同时不改变排队提示词身份。`cancel()` 与 `whenIdle()` 控制生命周期。需等待完成的资源释放负责拆卸。 ### Agent 作用域 @@ -150,7 +150,7 @@ idle inject: 持久性由插件负责。后端会尽快排空同步的 `session/event` 通知。`session/flush` 屏障位于每次请求与顶层工具分发之前，并在 `turn/end` 之后、处理另一个已排队轮次或观察到空闲状态之前执行。`SessionPersistence` 直接存储 `SessionEvent`，并将元数据存入 `SessionHeader`；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一契约（[决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)）。 -纯日志事件可以位于轮次之间。事件所有方通过 `Session` 追加，仅为持久性而刷写。`session/title` 依赖尽快持久化与生命周期排空。最新标题按后写覆盖并携带来源信息；回退与提供方工作绝不会延迟响应。这类记录可作为 fork 边界，因此 fork 会继承标题（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。 +在轮次之间，事件所有方通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 需要尽快持久化与生命周期排空；手动压缩会在释放轮次接纳预留前 flush 其标记对。标题工作绝不延迟响应；最新标题按后写覆盖并携带来源信息。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。 ### 模型内容 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 12bde08080..a356a151e3 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -349,7 +349,7 @@ Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:25`](../package ## `@deepseek-ai/dsh-compact-basic` -Requires: `llm` · `tokenMeter` +Requires: `llm` · `tokenMeter` · `sessions` ```ts config-catalog /** Basic compaction configuration with an optional exact-target policy table. */ @@ -2010,8 +2010,8 @@ export interface Config extends TuiConfig { /** * Skill name auto-invoked as this session's first user turn, exactly as if * the user typed `/skill:`. Set only by a launcher for a fresh - * skill-guided session (`dsh migrate`/`dsh upgrade`); absent leaves the first - * turn to the user. + * skill-guided session (`dsh migrate`/`dsh experimental-upgrade`); absent + * leaves the first turn to the user. */ initialSkill?: string } @@ -2308,6 +2308,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co - `@deepseek-ai/dsh-client-ui-theme` ([`packages/client/ui-theme/src/index.ts`](../packages/client/ui-theme/src/index.ts)) - `@deepseek-ai/dsh-client-ui-trajectory` ([`packages/client/ui-trajectory/src/index.ts`](../packages/client/ui-trajectory/src/index.ts)) - `@deepseek-ai/dsh-client-ui-workspace` ([`packages/client/ui-workspace/src/index.ts`](../packages/client/ui-workspace/src/index.ts)) +- `@deepseek-ai/dsh-command-compact` — requires `commands` · `compact` ([`packages/compact/command-compact/src/index.ts`](../packages/compact/command-compact/src/index.ts)) - `@deepseek-ai/dsh-command-goal` — requires `commands` · `goals` ([`packages/goal/command-goal/src/index.ts`](../packages/goal/command-goal/src/index.ts)) - `@deepseek-ai/dsh-commands` ([`packages/ui/commands/src/index.ts`](../packages/ui/commands/src/index.ts)) - `@deepseek-ai/dsh-fs-policy` ([`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts)) diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 497e0d220d..a7ff21e2f4 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -32,7 +32,7 @@ Effective broad cancellation was requested, before queued/outbox work is cleared Types: [Agent](../core-data-structures/core.md) · [AgentCancelCause](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:319`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:333`](../../packages/core/agent/src/types.ts) ### `agent/created` — emit @@ -54,7 +54,7 @@ A fully configured agent and live session were published. Setup is composition-o Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:250`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:264`](../../packages/core/agent/src/types.ts) ### `agent/disposed` — emit @@ -74,7 +74,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:273`](../../packages/core/agent/src/types.ts) ### `agent/error` — emit @@ -96,7 +96,7 @@ A step or turn errored. The machine reports a failure here (plus the logger) eve Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:433`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:447`](../../packages/core/agent/src/types.ts) ### `agent/inbox/dequeue` — emit @@ -117,7 +117,7 @@ The driver claimed one item out of the inbox: a queued item at a turn boundary, Types: [Agent](../core-data-structures/core.md) · [InboxItem](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:297`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:311`](../../packages/core/agent/src/types.ts) ### `agent/inbox/discard` — emit @@ -140,7 +140,7 @@ Pending inbox items were dropped without delivering them, so every enqueue occur Types: [Agent](../core-data-structures/core.md) · [InboxItem](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:309`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:323`](../../packages/core/agent/src/types.ts) ### `agent/inbox/enqueue` — emit @@ -161,7 +161,7 @@ An item entered the queued or steering inbox. `placement` is the acceptance-time Types: [Agent](../core-data-structures/core.md) · [InboxItem](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:278`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:292`](../../packages/core/agent/src/types.ts) ### `agent/inbox/update` — emit @@ -181,7 +181,7 @@ A still-pending queued item changed content. The item id, placement, and positio Types: [Agent](../core-data-structures/core.md) · [InboxItem](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:287`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:301`](../../packages/core/agent/src/types.ts) ### `agent/prompt-submit` — waterfall @@ -204,7 +204,7 @@ Allow, rewrite, or block one claimed prompt before it becomes a user message or Types: [Agent](../core-data-structures/core.md) · [PromptDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md) -Source: [`packages/core/agent/src/types.ts:346`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:360`](../../packages/core/agent/src/types.ts) ### `agent/request` — waterfall @@ -228,7 +228,7 @@ Replace the frozen call configuration. `await next()` yields the config the mach Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:372`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:386`](../../packages/core/agent/src/types.ts) ### `agent/request-error` — waterfall @@ -258,7 +258,7 @@ Handle a model-request failure after its failed step has closed but before the f Types: [Agent](../core-data-structures/core.md) · [LlmFailure](../core-data-structures/llm-streaming.md) · [RequestError](../core-data-structures/core.md) · [RequestErrorAction](../core-data-structures/core.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:391`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:405`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -280,7 +280,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SessionStartSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:332`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:346`](../../packages/core/agent/src/types.ts) ### `agent/settled` — emit @@ -305,7 +305,7 @@ One drain chain reached its terminal turn: that turn's `turn/end` is already com Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SettleReason](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:420`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:434`](../../packages/core/agent/src/types.ts) ### `agent/status` — emit @@ -325,7 +325,7 @@ Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` s Types: [Agent](../core-data-structures/core.md) · [AgentStatus](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:268`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:282`](../../packages/core/agent/src/types.ts) ### `agent/step` — serial @@ -349,7 +349,7 @@ Awaited serial checkpoint before EVERY request of a turn is built (the first as Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:359`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:373`](../../packages/core/agent/src/types.ts) ### `agent/turn-stopping` — serial @@ -375,7 +375,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) -Source: [`packages/core/agent/src/types.ts:406`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:420`](../../packages/core/agent/src/types.ts) ## `agent-loop/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 9090eaa8aa..9fbf6bf327 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -463,6 +463,26 @@ Abstract compaction service. Implementations own trigger policy, retention, and */ abstract compactIfNeeded( agent: CompactAgentContext, trigger: CompactionTrigger, signal: AbortSignal, ): Promise +/** + * Explicitly compact useful history even below automatic pressure thresholds. + * Implementations reserve idle turn admission synchronously before any + * asynchronous work, select a useful range without writing on a no-op, then + * append a standalone `compact/start` before summarization. That durable + * marker is the compaction lock until one `compact/end` attempt. Later waking + * prompts remain accepted in FIFO order and start only after the optional + * durability checkpoint and admission release. Context injected while the + * summary runs may sit between the marker pair; only the selected span must + * remain stable. + * + * @param agent - idle agent whose durable history should be compacted. + * @param signal - command-owned cancellation forwarded to summarization. + * @returns the compaction result, or `null` when no safe useful range exists. + * @throws {@link ManualCompactionError} for expected busy, changed-span, + * summarization/shrink, commit-stage, or persistence failures, and the exact + * abort reason when cancelled. Failed attempts remain visible in the log. + */ +abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise + /** * Forcibly compact a range of surface nodes into a single summary node. * `start` and `end` name an inclusive span by surface position, not numeric seq @@ -486,7 +506,7 @@ abstract compactRegion( start: number, end: number, agent: CompactAgentContext, Types: [CompactionResult](../core-data-structures/compaction.md) · [CompactionTrigger](../core-data-structures/compaction.md) -Source: [`packages/compact/compact/src/index.ts:45`](../../packages/compact/compact/src/index.ts) +Source: [`packages/compact/compact/src/index.ts:80`](../../packages/compact/compact/src/index.ts) ## `ctx.credentials` — `Credentials` (abstract seam) @@ -2363,7 +2383,7 @@ The concrete provider retains pi-tui, focus, and terminal lifecycle state. Plugi abstract openOverlay(request: TuiOverlayRequest): TuiOverlaySession ``` -Source: [`packages/ui/tui/src/index.ts:241`](../../packages/ui/tui/src/index.ts) +Source: [`packages/ui/tui/src/index.ts:242`](../../packages/ui/tui/src/index.ts) ## `ctx.typert` — `TypertRegistry` @@ -2539,7 +2559,7 @@ Durable workspace registry. Startup waits for `sessionPersistence`, builds one c * original error and a non-directory rejects. Repeated calls for the same * canonical path return the existing entity without changing its title. * A newly created workspace is prepended to the durable registry order. - * A different canonical path cannot create a duplicate display title. + * Different canonical paths may share a display title. * @param path - Existing directory to own, in any path spelling. * @param title - Display title used only when a new record is created. * @returns the existing or newly durable workspace. @@ -2592,7 +2612,7 @@ async resolveByPath(path: string): Promise Types: [SessionId](../core-data-structures/core.md) -Source: [`packages/workspace/workspace/src/index.ts:92`](../../packages/workspace/workspace/src/index.ts) +Source: [`packages/workspace/workspace/src/index.ts:81`](../../packages/workspace/workspace/src/index.ts) ## Inherited `ctx` members (cordis core + loader/hmr/timer) diff --git a/docs/core-data-structures/compaction.i18n.yaml b/docs/core-data-structures/compaction.i18n.yaml index a933e793c4..972521f7c0 100644 --- a/docs/core-data-structures/compaction.i18n.yaml +++ b/docs/core-data-structures/compaction.i18n.yaml @@ -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/core-data-structures/compaction.md -compaction.md: 3ae4d7e50452b549654b7a7162141a4be505d784 -compaction.zh.md: 448c3aaf298b65ebe88565190c5b3978b975f5f3 +compaction.md: 070adc65fb25b2536c88701c375cc0b2a5308559 +compaction.zh.md: 9167882f63b2931ba3ce49697e0c87164394af89 diff --git a/docs/core-data-structures/compaction.md b/docs/core-data-structures/compaction.md index 3ae4d7e504..070adc65fb 100644 --- a/docs/core-data-structures/compaction.md +++ b/docs/core-data-structures/compaction.md @@ -2,7 +2,7 @@ English | [中文](compaction.zh.md) -The compaction seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) split like bash: interface ([dsh-compact](../../packages/compact/compact), `ctx.compact`), implementation (a backend such as [dsh-compact-basic](../../packages/compact/compact-basic)), and consumer (a `/compact` tool, deferred). Compaction is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A tokenizer- or template-based backend is a sibling package implementing the same interface. Unlike bash, the interface necessarily depends on `dsh-session` and `dsh-llm`: its verbs act on an agent-owned `Session`, and its durable summary event uses the `ContentBlock` vocabulary (see the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)). +The compaction seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) split like bash: interface ([dsh-compact](../../packages/compact/compact), `ctx.compact`), implementation (a backend such as [dsh-compact-basic](../../packages/compact/compact-basic)), and human consumer ([dsh-command-compact](../../packages/compact/command-compact)). Compaction is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A tokenizer- or template-based backend is a sibling package implementing the same interface. Unlike bash, the interface necessarily depends on `dsh-session` and `dsh-llm`: its verbs act on an agent-owned `Session`, and its durable summary event uses the `ContentBlock` vocabulary (see the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)). Source: [`packages/compact/compact/src/types.ts`](../../packages/compact/compact/src/types.ts) @@ -12,12 +12,14 @@ Compaction extends [`SessionEventMap`](session.md) with three event types via de | Event | Payload | Role | |---|---|---| -| `compact/start` | `{ turn }` | acquires the log-recorded lock | +| `compact/start` | `{ turn }` | acquires the log-recorded lock; a number identifies the open automatic turn, while `null` identifies a standalone manual attempt | | `compact/summary` | `{ summary, rawOutput?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance: the safe summary projection, optional complete provider output and usage, the shadowed surface-boundary pair (`start`/`end` seqs — a position span, not a numeric interval), the shadowed seqs in surface order, the estimated token count, and the summarize call's envelope (`provider`, `model`, plus its generation cap when one applied) — logged so the one-shot request is reconstructable from log + code (the reconstructability Agent Note) | -| `compact/end` | `{ turn, error? }` | releases the lock (`error` set when summarization threw) | +| `compact/end` | `{ turn, error? }` | releases the lock with the same numeric-or-null owner (`error` records an unsuccessful attempt) | The lock brackets the **whole** operation: `compact/start` is appended first, then summarization, the `compact/summary` provenance record, and the `user/message` replacement all land, and only then `compact/end`. Releasing the lock last turns a crash mid-operation into a detectable orphaned lock (a `compact/start` with no matching `compact/end`) rather than a `compact/end` that falsely claims compaction finished. +The markers are lock time points, not an exclusive container. An unrelated idle injection can appear between a standalone manual start and end while summarization is pending. The manual path revalidates only its selected positional span, so that injected context survives after the replacement checkpoint. A live unmatched start blocks every entry point; an unmatched start before a newer `session/end-seed` is stale evidence from a prior lifecycle and is ignored. + These variants are merged inside a `declare module '@deepseek-ai/dsh-session'` block, so — unlike the top-level types on the other sub-pages — they are not pasted as a drift-checked ` ```ts type-equiv ` block (the `verify-type-equiv` extractor matches only top-level declarations by name). The payload table above is the catalog entry; follow the source link for the authoritative shapes. ## `CompactionResult` @@ -60,7 +62,16 @@ Automatic callers state why policy is running; implementations may treat confirm type CompactionTrigger = 'pressure' | 'context-overflow' ``` -`CompactService` exposes `compactIfNeeded(agent, trigger, signal)` for automatic `pressure` or `context-overflow` policy, returning `null` when no safe work exists, and `compactRegion(...)` for an explicit inclusive surface range. Every backend marks its replacement `user/message` with `COMPACT_CHECKPOINT_SOURCE`; client and wire consumers import that value and `isCompactCheckpointSource()` from the cordis-free `@deepseek-ai/dsh-compact/checkpoint` subpath, while the package root re-exports both for host consumers. Implementations must forward the supplied signal to summarization. The seam owns no pricing API: the singleton [`ctx.tokenMeter`](token-meter.md) directly owns estimation and replay, while `dsh-compact-basic` owns retention, event sequencing, routed summarization calls, and their configuration. +`CompactService` exposes `compactIfNeeded(agent, trigger, signal)` for automatic `pressure` or `context-overflow` policy, `compactNow(agent, signal)` for one useful idle-session reduction even below pressure, and `compactRegion(...)` for an explicit inclusive surface range. `compactNow()` synchronously reserves the agent's next-turn admission, returns `null` without writing when no useful range exists, records a standalone `turn: null` bracket before summarization, flushes a closed attempt, and then releases admission so ordinary queued prompts derive from the new surface. Every backend marks its replacement `user/message` with `COMPACT_CHECKPOINT_SOURCE`; client and wire consumers import that value and `isCompactCheckpointSource()` from the cordis-free `@deepseek-ai/dsh-compact/checkpoint` subpath, while the package root re-exports both for host consumers. The predicate keeps checkpoint recognition independent of any one backend. Implementations must forward the supplied signal to summarization. The seam owns no pricing API: the singleton [`ctx.tokenMeter`](token-meter.md) directly owns estimation and replay, while `dsh-compact-basic` owns retention, event sequencing, routed summarization calls, and their configuration. + +Expected manual failures use `ManualCompactionErrorCode`: + +```ts type-equiv +/** Expected failure classes for an explicit idle-session compaction request. */ +type ManualCompactionErrorCode = 'busy' | 'changed' | 'summary' | 'commit' | 'persistence' +``` + +`changed` and `summary` leave the conversation surface unchanged but still close and persist the failed attempt in the log. `commit` may follow partial mutation; `persistence` means the in-memory bracket closed but its flush failed. Cancellation remains separate and throws the exact abort reason after required cleanup. Pressure compaction runs at serial `agent/step` before request derivation. Once pressure or canonical overflow qualifies, compact-basic invokes optional [`ctx.toolResultPrune`](../../packages/compact/compact-tool-result-prune/README.md) before range selection, remeasures through `ctx.tokenMeter`, and can advance the surface without a summary. Failed-request recovery runs through `agent/request-error` after the failed step closes and returns a retry action only when the surface replacement generation advances, even if later summary work throws after pruning; cancellation still wins. Region boundaries preserve tool-call/result pairing but not whole turns, allowing early closed steps of one oversized turn to compact. `dsh-compact-basic` owns thresholds, retained-tail policy, overflow caps, and failure handling. diff --git a/docs/core-data-structures/compaction.zh.md b/docs/core-data-structures/compaction.zh.md index 448c3aaf29..9167882f63 100644 --- a/docs/core-data-structures/compaction.zh.md +++ b/docs/core-data-structures/compaction.zh.md @@ -2,7 +2,7 @@ [English](compaction.md) | 中文 -压缩 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)，与 bash 一样分为接口（[dsh-compact](../../packages/compact/compact)，`ctx.compact`）、实现（例如 [dsh-compact-basic](../../packages/compact/compact-basic) 后端）和消费方（延期实现的 `/compact` 工具）。压缩是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。基于 tokenizer 或模板的后端是实现同一接口的兄弟包（package）。与 bash 不同，该接口必然依赖 `dsh-session` 和 `dsh-llm`：其动词作用于 agent 所有的 `Session`，而其持久摘要事件使用 `ContentBlock` 词汇（见[压缩能力 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)）。 +压缩 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)，与 bash 一样分为接口（[dsh-compact](../../packages/compact/compact)，`ctx.compact`）、实现（例如 [dsh-compact-basic](../../packages/compact/compact-basic) 后端）和面向用户的消费方（[dsh-command-compact](../../packages/compact/command-compact)）。压缩是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。基于 tokenizer 或模板的后端是实现同一接口的兄弟包（package）。与 bash 不同，该接口必然依赖 `dsh-session` 和 `dsh-llm`：其动词作用于 agent 所有的 `Session`，而其持久摘要事件使用 `ContentBlock` 词汇（见[压缩能力 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)）。 源码：[`packages/compact/compact/src/types.ts`](../../packages/compact/compact/src/types.ts) @@ -12,12 +12,14 @@ | 事件 | 载荷 | 作用 | |---|---|---| -| `compact/start` | `{ turn }` | 获取日志记录的锁 | +| `compact/start` | `{ turn }` | 获取日志记录的锁；数字标识打开的自动轮次，`null` 标识独立手动尝试 | | `compact/summary` | `{ summary, rawOutput?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance：安全摘要投影、可选的完整 provider 输出与 usage、被遮蔽的 surface 边界对（`start`/`end` seq——位置跨度，而非数值区间）、按 surface 顺序排列的被遮蔽 seq、估算 token 数，以及摘要调用的 envelope（`provider`、`model`，若有生成上限则还包括该上限）——写入日志后，该一次性请求可由日志 + 代码重建（见可重建性 Agent Note） | -| `compact/end` | `{ turn, error? }` | 释放锁（摘要调用抛出异常时设置 `error`） | +| `compact/end` | `{ turn, error? }` | 使用相同的数字或 `null` 归属值释放锁（`error` 记录失败尝试） | 锁括住**整个**操作：先追加 `compact/start`，然后执行摘要生成、写入 `compact/summary` 来源记录与 `user/message` 替换，最后才追加 `compact/end`。最后释放锁意味着操作中途崩溃会表现为可检测的遗留锁（有 `compact/start` 而无匹配的 `compact/end`），而非一个虚假声称压缩已完成的 `compact/end`。 +这些标记表示锁的时间点，而不是排他的容器。摘要等待期间，不相关的空闲注入可以出现在独立的手动 start 与 end 之间。手动路径只重新验证所选位置 span，因此替换检查点之后仍保留该注入上下文。活动的未匹配 start 会阻塞所有入口点；较新 `session/end-seed` 之前的未匹配 start 是先前生命周期留下的陈旧证据，会被忽略。 + 这些变体在 `declare module '@deepseek-ai/dsh-session'` 块内合并，因此——与其他子页面上的顶层类型不同——它们不以漂移检查的 ` ```ts type-equiv ` 块粘贴（`verify-type-equiv` 提取器只按名称匹配顶层声明）。上方的载荷表即为目录条目；权威形状请循源码链接查看。 ## `CompactionResult` @@ -60,7 +62,16 @@ interface CompactionResult { type CompactionTrigger = 'pressure' | 'context-overflow' ``` -`CompactService` 暴露 `compactIfNeeded(agent, trigger, signal)` 以执行自动 `pressure` 或 `context-overflow` 策略；没有可安全执行的工作时返回 `null`。它还针对显式、两端均包含的 surface 范围暴露 `compactRegion(...)`。每个后端都使用 `COMPACT_CHECKPOINT_SOURCE` 标记其替换用的 `user/message`；client 与 wire 消费方从无 cordis 的 `@deepseek-ai/dsh-compact/checkpoint` 子路径导入该值和 `isCompactCheckpointSource()`，包根则为 host 消费方重新导出两者。实现必须把传入的 signal 转发给摘要流程。该 seam 不拥有计价 API：单例 [`ctx.tokenMeter`](token-meter.md) 直接拥有估算与回放，而 `dsh-compact-basic` 拥有保留策略、事件排序、按路由执行的摘要调用及其配置。 +`CompactService` 暴露 `compactIfNeeded(agent, trigger, signal)` 以执行自动 `pressure` 或 `context-overflow` 策略，暴露 `compactNow(agent, signal)` 以便即使未达到压力也对空闲会话进行一次有效缩减，还针对显式、两端均包含的 surface 范围暴露 `compactRegion(...)`。`compactNow()` 会同步预留 agent 的下一轮次接纳；没有有效范围时返回 `null` 且不写入；在摘要前记录独立的 `turn: null` 标记对；flush 已闭合尝试；随后释放接纳预留，使普通排队提示词从新表层派生。每个后端都使用 `COMPACT_CHECKPOINT_SOURCE` 标记其替换用的 `user/message`；client 与 wire 消费方从无 cordis 的 `@deepseek-ai/dsh-compact/checkpoint` 子路径导入该值和 `isCompactCheckpointSource()`，包根则为 host 消费方重新导出两者。该判定函数使检查点识别不依赖任一特定后端。实现必须把传入的 signal 转发给摘要流程。该 seam 不拥有计价 API：单例 [`ctx.tokenMeter`](token-meter.md) 直接拥有估算与回放，而 `dsh-compact-basic` 拥有保留策略、事件排序、按路由执行的摘要调用及其配置。 + +预期的手动失败使用 `ManualCompactionErrorCode`： + +```ts type-equiv +/** Expected failure classes for an explicit idle-session compaction request. */ +type ManualCompactionErrorCode = 'busy' | 'changed' | 'summary' | 'commit' | 'persistence' +``` + +`changed` 和 `summary` 保持会话表层不变，但仍会闭合失败尝试并将其持久化到日志。`commit` 可能发生在部分变更之后；`persistence` 表示内存中的标记对已闭合，但 flush 失败。取消独立于这些失败，并在完成必要清理后抛出原始 abort 原因。 压力压缩在串行 `agent/step` 中运行，先于请求推导。一旦压力或规范化溢出满足条件，compact-basic 会在选择范围前调用可选的 [`ctx.toolResultPrune`](../../packages/compact/compact-tool-result-prune/README.md)，再通过 `ctx.tokenMeter` 重新测量，并且可以在不生成摘要的情况下推进 surface。失败请求的恢复在失败的步骤关闭后通过 `agent/request-error` 运行；仅当 surface replacement generation 前进时才返回重试动作，即便后续摘要工作在剪枝后抛异常亦如此；取消仍然优先。区域边界保持工具调用/结果配对，但不保持整个轮次，因此一个过大轮次中较早关闭的步骤可以被压缩。`dsh-compact-basic` 拥有阈值、保留尾部策略、溢出上限与失败处理。 diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml index 82ef063bec..b1bdfb1a14 100644 --- a/docs/core-data-structures/core.i18n.yaml +++ b/docs/core-data-structures/core.i18n.yaml @@ -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/core-data-structures/core.md -core.md: 5ed6a47c5488005d41fdac9349e4c9d1c550d13d -core.zh.md: 1b16b7ec994c6fccd6fedf1508dec6b1b057edf3 +core.md: 70c63d8a84963f56468b5fcdacb580a798de2e10 +core.zh.md: 280529b7de6c3e8546b71791367710c588ad9282 diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index 5ed6a47c54..70c63d8a84 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -614,6 +614,20 @@ interface Agent { */ send(message: UserMessage, options: SendOptions): void + /** + * Reserve admission of the next ordinary turn while this agent is idle, so an + * operation can mutate durable history before any queued prompt derives a + * request from it. Already-accepted waking work has right of way, including a + * send whose wake is still a pending microtask. Later sends keep their + * ordinary placement, FIFO order, and `wakeup` facts, and + * {@link acceptsNextStep} stays `false`, so a waking `next-step` send becomes + * a queued follow-up rather than steering; cancellation and disposal may + * still discard them. {@link inject} is not withheld. {@link whenIdle} treats + * a live reservation as activity, while lifecycle teardown does not await it. + * @returns the idempotent release, or `undefined` when the agent is running, already reserved, or already committed to waking work. + */ + reserveTurnAdmission(): (() => void) | undefined + /** * Mutate one still-pending queued occurrence synchronously. Editing preserves * the message identity and queue position; removal publishes its terminal @@ -671,7 +685,7 @@ interface Agent { } ``` -`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `acceptsNextStep` is the narrower routing predicate for callers that must choose between steering the current admission/turn and submitting a fresh admitted prompt. `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default. +`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `acceptsNextStep` is the narrower routing predicate for callers that must choose between steering the current admission/turn and submitting a fresh admitted prompt. A live turn-admission reservation is quiescence-relevant without changing `status` or turning later queue entries into steering; its only authority is to defer the next driver claim until release. `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default. The cause is a TypeScript-enforced same-process input. An active `TurnCancellation` holder copies its discriminant into the runtime-only `AbortSignal.reason` and is retired before `turn/end` publication; the frozen `AbortSignal.reason` remains readable after that retirement. Only the loop reads the cause (`user`, `parent`, or lifecycle-only `disposed`) back off its own machine-private signal at settlement — there is no public reader, and a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result. diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md index 1b16b7ec99..280529b7de 100644 --- a/docs/core-data-structures/core.zh.md +++ b/docs/core-data-structures/core.zh.md @@ -622,6 +622,20 @@ interface Agent { */ send(message: UserMessage, options: SendOptions): void + /** + * Reserve admission of the next ordinary turn while this agent is idle, so an + * operation can mutate durable history before any queued prompt derives a + * request from it. Already-accepted waking work has right of way, including a + * send whose wake is still a pending microtask. Later sends keep their + * ordinary placement, FIFO order, and `wakeup` facts, and + * {@link acceptsNextStep} stays `false`, so a waking `next-step` send becomes + * a queued follow-up rather than steering; cancellation and disposal may + * still discard them. {@link inject} is not withheld. {@link whenIdle} treats + * a live reservation as activity, while lifecycle teardown does not await it. + * @returns the idempotent release, or `undefined` when the agent is running, already reserved, or already committed to waking work. + */ + reserveTurnAdmission(): (() => void) | undefined + /** * Mutate one still-pending queued occurrence synchronously. Editing preserves * the message identity and queue position; removal publishes its terminal @@ -679,7 +693,7 @@ interface Agent { } ``` -`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。对于需要在把输入作为 steering 加入当前提示词准入／轮次，还是提交为一个新的待准入提示词之间做选择的调用方，`acceptsNextStep` 才是更窄且准确的路由判断条件。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时，系统会在写入请求 header 前填入确切模型的适配器默认值，否则提供方行为保持不变。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。 +`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。对于需要在把输入作为 steering 加入当前提示词准入／轮次，还是提交为一个新的待准入提示词之间做选择的调用方，`acceptsNextStep` 才是更窄且准确的路由判断条件。活动的轮次接纳预留与完全停稳相关，但不会改变 `status`，也不会把之后的队列项变成 steering；它的唯一权限是将驱动器的下一次认领延迟到释放时。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时，系统会在写入请求 header 前填入确切模型的适配器默认值，否则提供方行为保持不变。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。 cause 是由 TypeScript 强制约束的同进程输入。活跃的 `TurnCancellation` 持有者会把其判别字段复制到仅运行时的 `AbortSignal.reason`，并在发布 `turn/end` 前退役；冻结后的 `AbortSignal.reason` 仍可读取。只有 loop 会在结算时从自己机器私有的 signal 上读回 cause（`user`、`parent` 或仅用于生命周期的 `disposed`）——不存在公开的读取器，signal 也不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。 diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index cce2258651..f2007c814a 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -8,22 +8,22 @@ This matrix shows which packages dispatch each harness-owned event and which pac | Event | Mode | Declared in | Dispatchers | Listeners | | --- | --- | --- | --- | --- | | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:157`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | [`tui`](../packages/ui/tui) | -| `agent/cancel-requested` | `emit` | [`packages/core/agent/src/types.ts:319`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal-session`](../packages/goal/goal-session) | -| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:250`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) | -| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) | -| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:433`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tui`](../packages/ui/tui) | -| `agent/inbox/dequeue` | `emit` | [`packages/core/agent/src/types.ts:297`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`tui`](../packages/ui/tui) | -| `agent/inbox/discard` | `emit` | [`packages/core/agent/src/types.ts:309`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`tui`](../packages/ui/tui) | -| `agent/inbox/enqueue` | `emit` | [`packages/core/agent/src/types.ts:278`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`goal-session`](../packages/goal/goal-session) | -| `agent/inbox/update` | `emit` | [`packages/core/agent/src/types.ts:287`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `apiproxy` | -| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:346`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`tui`](../packages/ui/tui) | -| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:372`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) | -| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:391`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) | -| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:332`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`workspace-context`](../packages/context/workspace-context) | -| `agent/settled` | `emit` | [`packages/core/agent/src/types.ts:420`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`compact-basic`](../packages/compact/compact-basic) | -| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:268`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) | -| `agent/step` | `serial` | [`packages/core/agent/src/types.ts:359`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`plan-mode`](../packages/plan/plan-mode), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) | -| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:406`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `agent/cancel-requested` | `emit` | [`packages/core/agent/src/types.ts:333`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal-session`](../packages/goal/goal-session) | +| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:264`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) | +| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:273`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) | +| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:447`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tui`](../packages/ui/tui) | +| `agent/inbox/dequeue` | `emit` | [`packages/core/agent/src/types.ts:311`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`tui`](../packages/ui/tui) | +| `agent/inbox/discard` | `emit` | [`packages/core/agent/src/types.ts:323`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`tui`](../packages/ui/tui) | +| `agent/inbox/enqueue` | `emit` | [`packages/core/agent/src/types.ts:292`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`goal-session`](../packages/goal/goal-session) | +| `agent/inbox/update` | `emit` | [`packages/core/agent/src/types.ts:301`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `apiproxy` | +| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:360`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`tui`](../packages/ui/tui) | +| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:386`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) | +| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:405`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) | +| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:346`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`workspace-context`](../packages/context/workspace-context) | +| `agent/settled` | `emit` | [`packages/core/agent/src/types.ts:434`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`compact-basic`](../packages/compact/compact-basic) | +| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:282`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) | +| `agent/step` | `serial` | [`packages/core/agent/src/types.ts:373`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`plan-mode`](../packages/plan/plan-mode), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) | +| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:420`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | | `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:30`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` | | `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:154`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy`, [`tui`](../packages/ui/tui) | | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) | diff --git a/docs/module-graph.md b/docs/module-graph.md index 99660d1eab..f0f58a18c1 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -57,6 +57,7 @@ flowchart TD pkg_tool_skill["tool-skill"] end subgraph group_compact["packages/compact"] + pkg_command_compact["command-compact"] pkg_compact["compact"] pkg_compact_basic["compact-basic"] pkg_compact_tool_result_prune["compact-tool-result-prune"] @@ -315,6 +316,7 @@ flowchart TD pkg_client_ui_settings --> pkg_client_ui_primitives pkg_client_ui_settings --> pkg_client_ui_slots pkg_client_ui_settings --> pkg_invariants + pkg_client_ui_trajectory --> pkg_client_runtime pkg_client_ui_trajectory --> pkg_client_ui_primitives pkg_client_ui_trajectory --> pkg_invariants pkg_credentials --> pkg_brand @@ -617,6 +619,9 @@ flowchart TD pkg_fs_sandbox --> pkg_invariants pkg_fs_sandbox --> pkg_sandbox pkg_fs_sandbox --> pkg_sandbox_policy + pkg_command_compact --> pkg_commands + pkg_command_compact --> pkg_compact + pkg_command_compact --> pkg_invariants pkg_compact_basic --> pkg_agent pkg_compact_basic --> pkg_compact pkg_compact_basic --> pkg_compact_tool_result_prune @@ -1078,7 +1083,7 @@ flowchart TD | [`client-locale`](../packages/client/locale) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) | | [`client-test-runtime`](../packages/client/test-runtime) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/support/invariants) | | [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) | -| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`client-ui-primitives`](../packages/client/ui-primitives), [`invariants`](../packages/support/invariants) | +| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`invariants`](../packages/support/invariants) | | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) | | [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) | | [`telemetry`](../packages/sdk/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) | @@ -1157,6 +1162,7 @@ flowchart TD | [`goal-session`](../packages/goal/goal-session) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) | | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) | +| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) | | [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title) | | [`session-title-llm`](../packages/session-title/session-title-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`timeout`](../packages/util/timeout) | diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index ab62f07184..b02dd1d6be 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -209,20 +209,27 @@ Source: [`packages/ui/commands/src/index.ts:132`](../packages/ui/commands/src/in #### `compact/end` — log-only ```ts persistence-catalog -/** Marks the end of a compaction — log-only, releases the lock. `error` set if summarization failed. */ -'compact/end': { turn: number; error?: string } +/** + * Marks the end of a compaction — log-only, releases the lock. Its owner + * matches `compact/start`; `error` records an unsuccessful attempt. + */ +'compact/end': { turn: number | null; error?: string } ``` -Source: [`packages/compact/compact/src/types.ts:44`](../packages/compact/compact/src/types.ts) +Source: [`packages/compact/compact/src/types.ts:51`](../packages/compact/compact/src/types.ts) #### `compact/start` — log-only ```ts persistence-catalog -/** Marks the start of a compaction — log-only, holds the lock until `compact/end`. */ -'compact/start': { turn: number } +/** + * Marks the start of a compaction — log-only, holds the lock until + * `compact/end`. A numbered owner is strictly enclosed by that open turn; + * `null` identifies a standalone manual transaction between turns. + */ +'compact/start': { turn: number | null } ``` -Source: [`packages/compact/compact/src/types.ts:15`](../packages/compact/compact/src/types.ts) +Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact/src/types.ts) #### `compact/summary` — log-only @@ -258,7 +265,7 @@ Source: [`packages/compact/compact/src/types.ts:15`](../packages/compact/compact Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md) -Source: [`packages/compact/compact/src/types.ts:22`](../packages/compact/compact/src/types.ts) +Source: [`packages/compact/compact/src/types.ts:26`](../packages/compact/compact/src/types.ts) ### `hook/*` diff --git a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl index c8321da3bb..43a87440a2 100644 --- a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl +++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl @@ -13,7 +13,7 @@ {"type":"assistant/chunk","seq":11,"time":1785487622703,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} {"type":"assistant/message","seq":12,"time":1785487622703,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"7c207b09-7f6e-4e53-a5d2-77e0d2bbb474"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[7,8,9,10,11],"surfaceOp":"append"} {"type":"tool/call","seq":13,"time":1785487622703,"data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}} -{"type":"tool/result","seq":14,"time":1785487622726,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n /**\n * Register globally or in the calling agent scope. Scoped tools shadow\n * globals; duplicates within one layer and the reserved `run_code` name fail.\n * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n * @returns the exact disposer that unregisters the tool.\n */\n register(definition: ToolDefinition): () => void\n /**\n * Restrict global tools for the calling agent scope. Empty filters, unknown\n * names, scope-local names, and reserved transport names fail. Restrictions\n * intersect; scoped registrations remain visible.\n * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n * @returns the exact disposer that lifts this restriction.\n */\n restrict(filter: ToolRestriction): () => void\n /**\n * Register a monotonic guard after the extensible `tools/pre-execute`\n * waterfall. A plain-context guard applies globally; one registered through\n * `agent.ctx` applies only to that agent. Any matching guard may deny by\n * returning a reason, while no guard can force-allow a call another guard\n * denied. The exact effect disposer is returned for ordered ownership and\n * HMR cleanup.\n * @param guard - synchronous check; a returned string denies the execution.\n * @returns the exact disposer that unregisters the guard.\n */\n guard(guard: ToolGuard): () => void\n /**\n * Look up a tool as one scope sees it (scoped\n * shadows global; a restricted-away global reads as absent). Presenters pass\n * the calling agent so the rendered card matches the definition that\n * actually executed.\n * @param name - the tool name as registered.\n * @param scope - the viewing scope (the agent); omitted = the global view.\n * @returns the definition the scope resolves, or undefined when none is visible.\n */\n get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n /**\n * Project visible definitions onto the allowlisted model-facing schema fields,\n * excluding execution and presentation callbacks.\n * @param scope - the viewing scope (the agent); omitted = the global view.\n * @returns one deep-cloned schema per visible tool.\n */\n schemas(scope?: ScopeKey): ToolSchema[]\n /**\n * Classify a pending call through the caller's visible tool definition. Only\n * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n * throwing classifiers are exclusive.\n * @param exec - call name, parsed arguments, and optional agent scope.\n * @returns the fail-closed scheduling mode.\n */\n executionMode(exec: ToolExecutionInput): ToolExecutionMode\n /**\n * Execute through pre-policy, guards, around-dispatch, post-policy,\n * definition-owned content finalization, and final notification. Tool and\n * listener failures resolve as materialized error results; an invisible tool\n * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n * snapshot final observers receive. Cancellation\n * arriving after entry and before final result materialization skips a\n * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n * successful started outcome with `ABORTED`; already-started work is still\n * drained and may retain a tool-owned structured error.\n * @param exec - the typed same-process call input. The registry assigns its\n * correlation token before policy begins.\n * @returns the materialized final result.\n */\n async execute(exec: ToolExecutionInput): Promise\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n export interface Agent {\n readonly id: SessionId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly status: AgentStatus;\n readonly acceptsNextStep: boolean;\n readonly ctx: Context;\n send(message: UserMessage, options: SendOptions): void;\n updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult;\n cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n whenIdle(): Promise;\n followup(message: UserMessage): void;\n steer(message: UserMessage): void;\n inject(message: UserMessage): void;\n }\n export type AgentCancelCause = {\n readonly kind: 'user';\n } | {\n readonly kind: 'parent';\n };\n export interface AgentOptions {\n provider?: string;\n model?: string;\n maxTokens?: number;\n }\n export type AgentStatus = 'idle' | 'running';\n export interface AssistantMessage extends Message {\n readonly role: 'assistant';\n readonly source: ModelMessageSource;\n }\n export interface AssistantProvenance {\n provider: string;\n model: string;\n replayState?: unknown;\n }\n export type Branded = string & {\n readonly [BRAND]: B;\n };\n export type CallId = Branded<'CallId'>;\n export interface CancelOptions {\n keepInbox?: boolean;\n }\n export interface ContentBlockMap {\n 'text': TextBlock;\n 'reasoning': ReasoningBlock;\n 'tool-call': ToolCallBlock;\n 'tool-result': ToolResultBlock;\n }\n export type ContentBlockType = keyof ContentBlockMap;\n export interface DiffCallView {\n card: 'diff';\n title: string;\n diffs: FileDiff[];\n locations?: FileLocation[];\n }\n export interface DiffResultView {\n card: 'diff';\n title?: string;\n diffs: FileDiff[];\n }\n export interface EpochHeader {\n config: LlmCallConfig;\n adapterDefaults?: LlmCallConfigAdapterDefaults;\n system?: string;\n tools?: ToolSchema[];\n }\n export interface FileDiff {\n path: string;\n oldText: string | null;\n newText: string;\n }\n export interface FileLocation {\n path: string;\n line?: number;\n }\n export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n export interface FinishReasonMap {\n 'stop': {\n kind: 'stop';\n };\n 'tool-calls': {\n kind: 'tool-calls';\n };\n 'max-tokens': {\n kind: 'max-tokens';\n };\n 'aborted': {\n kind: 'aborted';\n failure: LlmFailure;\n };\n 'error': {\n kind: 'error';\n failure: LlmFailure;\n };\n }\n export interface GenericCallView {\n card: 'generic';\n title: string;\n kind?: ToolCallKind;\n rawInput?: unknown;\n content?: ContentBlock[];\n locations?: FileLocation[];\n }\n export interface GenericResultView {\n card: 'generic';\n title?: string;\n content?: ContentBlock[];\n }\n export type InboxAction = {\n readonly kind: 'edit';\n readonly content: ContentBlock[];\n } | {\n readonly kind: 'remove';\n };\n export type InboxActionResult = 'applied' | 'not-found';\n export type InboxItemId = Branded<'InboxItemId'>;\n export interface JsonSchemaNode {\n type?: JsonSchemaType;\n oneOf?: JsonSchemaNode[];\n properties?: Record;\n required?: string[];\n additionalProperties?: boolean;\n items?: JsonSchemaNode;\n enum?: JsonSchemaScalar[];\n const?: JsonSchemaScalar;\n description?: string;\n title?: string;\n default?: JsonValue;\n examples?: JsonValue;\n }\n export type JsonSchemaScalar = string | number | boolean | null;\n export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n export type JsonValue = null | boolean | number | string | JsonValue[] | {\n [key: string]: JsonValue;\n };\n export interface LlmCallConfig {\n provider: string;\n model: string;\n reasoningEffort?: ReasoningEffortId;\n temperature?: number;\n maxTokens?: number;\n stop?: string[];\n }\n export interface LlmCallConfigAdapterDefaults {\n reasoningEffort?: true;\n maxTokens?: true;\n }\n export interface LlmFailure {\n readonly message: string;\n readonly code: string;\n readonly status?: number;\n readonly providerRetryAfterMs?: number;\n readonly requestId?: ProviderRequestId;\n }\n export interface Message {\n readonly id: MessageId;\n readonly role: 'system' | 'user' | 'assistant';\n readonly content: ContentBlock[];\n readonly source: MessageSource;\n }\n export type MessageId = Branded<'MessageId'>;\n export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n export interface MessageSourceMap {\n user: {\n kind: 'user';\n };\n plugin: {\n kind: 'plugin';\n plugin: string;\n };\n model: ModelMessageSource;\n tool: ToolMessageSource;\n }\n export interface ModelMessageSource extends AssistantProvenance {\n kind: 'model';\n }\n export type ProviderRequestId = Branded<'ProviderRequestId'>;\n export interface ReadFileLine {\n number: number;\n text: string;\n }\n export interface ReadResultView {\n card: 'read';\n title?: string;\n path: string;\n offset: number;\n lines: ReadFileLine[];\n totalLines: number;\n lang?: string;\n content?: ContentBlock[];\n }\n export interface ReasoningBlock {\n type: 'reasoning';\n text: string;\n }\n export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n export interface RequestContext {\n provider: string;\n model: string;\n contextWindow?: number;\n }\n export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n export type ScopeKey = object;\n export interface SearchFileMatches {\n path: string;\n matches: SearchLineMatch[];\n }\n export interface SearchLineMatch {\n lineNumber: number;\n line: string;\n }\n export interface SearchMatchesResultView {\n card: 'search';\n shape: 'matches';\n title?: string;\n files: SearchFileMatches[];\n truncated: boolean;\n total: number;\n }\n export interface SearchPathsResultView {\n card: 'search';\n shape: 'paths';\n title?: string;\n paths: string[];\n truncated: boolean;\n total: number;\n }\n export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\n export interface SendOptions {\n target: SendTarget;\n wakeup: boolean;\n }\n export type SendTarget = 'next-turn' | 'next-step';\n export class Session {\n get surface(): SessionSurface;\n readonly header: SessionHeader;\n get id(): SessionId;\n readonly firstLiveSeq: number;\n constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\n get events(): readonly SessionEvent[];\n get seq(): number;\n append(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n opts: SurfaceIntent\n ] : [\n ]): SessionEvent;\n requestHeader(): EpochHeader | undefined;\n requestContext(): RequestContext | undefined;\n deriveMessages(): Message[];\n deriveEventMessage(event: SessionEvent): Message | null;\n }\n export type SessionEvent = {\n [K in SessionEventType]: {\n type: K;\n seq: number;\n time: number;\n data: SessionEventMap[K];\n } & (K extends SurfaceEventType ? {\n sourceEventSeqs?: number[];\n surfaceOp?: SurfaceOp;\n } : object);\n }[T];\n export interface SessionEventMap {\n 'turn/start': {\n turn: number;\n trigger: TurnTrigger;\n };\n 'turn/end': {\n turn: number;\n reason: TurnEndReason;\n };\n 'step/start': {\n turn: number;\n step: number;\n };\n 'step/end': {\n turn: number;\n step: number;\n };\n 'user/message': UserMessage;\n 'assistant/chunk': {\n turn: number;\n step: number;\n chunk: StreamChunk;\n };\n 'assistant/message': {\n turn: number;\n step: number;\n message: AssistantMessage;\n usage?: TokenUsage;\n };\n 'tool/call': {\n turn: number;\n step: number;\n callId: CallId;\n name: string;\n arguments: string;\n };\n 'tool/result': {\n turn: number;\n step: number;\n message: ToolResultMessage;\n error?: {\n name: string;\n code: string;\n };\n meta?: JsonValue;\n };\n 'steering/message': {\n turn: number;\n message: UserMessage;\n };\n 'todo/write': {\n todos: TodoItem[];\n };\n 'request/header': {\n header: EpochHeader;\n reason: RequestHeaderReason;\n };\n 'request/context': RequestContext;\n 'session/end-seed': Record;\n }\n export type SessionEventType = keyof SessionEventMap;\n export interface SessionHeader {\n readonly version: number;\n readonly id: SessionId;\n readonly createdAt: number;\n readonly cwd?: string;\n readonly parentSession?: SessionId;\n readonly seedLength?: number;\n readonly delegationDepth?: number;\n }\n export type SessionId = Branded<'SessionId'>;\n export interface SessionSurface {\n readonly nodes: readonly number[];\n readonly replaceGeneration: number;\n }\n export type StreamChunk = {\n type: 'block-start';\n index: number;\n blockType: ContentBlockType;\n } | {\n type: 'text-delta';\n index: number;\n text: string;\n } | {\n type: 'reasoning-delta';\n index: number;\n text: string;\n } | {\n type: 'tool-call-delta';\n index: number;\n id: CallId;\n name?: string;\n argumentsDelta: string;\n } | {\n type: 'block-end';\n index: number;\n block: ContentBlock;\n } | {\n type: 'usage';\n usage: TokenUsage;\n } | {\n type: 'finish';\n reason: FinishReason;\n replayState?: unknown;\n };\n export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result' | 'steering/message';\n export interface SurfaceIntent {\n surfaceOp: SurfaceOp;\n sourceEventSeqs?: number[];\n }\n export type SurfaceOp = 'append' | {\n op: 'replace';\n start: number;\n end: number;\n };\n export interface TerminalCallView {\n card: 'terminal';\n title: string;\n description?: string;\n cwd?: string;\n }\n export interface TerminalResultView {\n card: 'terminal';\n title?: string;\n output?: string;\n exitCode?: number;\n signal?: string;\n }\n export interface TodoItem {\n content: string;\n status: 'pending' | 'in_progress' | 'completed';\n }\n export interface TokenUsage {\n inputTokens: number;\n outputTokens: number;\n cacheReadTokens?: number;\n cacheWriteTokens?: number;\n reasoningTokens?: number;\n }\n export interface ToolCallBlock {\n type: 'tool-call';\n id: CallId;\n name: string;\n arguments: string;\n }\n export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n export interface ToolDefinition extends ToolSchema {\n readonly output: ToolOutputDefinition;\n execute(args: unknown, exec: ToolRunContext): Promise;\n finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\n timeoutMs?: number;\n isConcurrencySafe?(args: unknown): boolean;\n presentCall?(args: unknown): ToolCallView | undefined;\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n }\n export interface ToolErrorInfo {\n name: string;\n code: string;\n }\n export interface ToolExecution extends ToolExecutionInput {\n readonly token: ToolExecutionToken;\n }\n export interface ToolExecutionFailure {\n readonly isError: true;\n readonly error: ToolFailure;\n readonly value?: never;\n readonly content: ContentBlock[];\n readonly meta?: JsonValue;\n readonly additionalContexts?: UserMessage[];\n readonly concludesTurn?: never;\n }\n export interface ToolExecutionInput {\n readonly callId: CallId;\n readonly name: string;\n readonly arguments: unknown;\n readonly agent?: Agent;\n readonly parent?: ToolExecutionToken;\n readonly signal: AbortSignal;\n }\n export type ToolExecutionMode = {\n kind: 'parallel';\n } | {\n kind: 'exclusive';\n };\n export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n export interface ToolExecutionSuccess {\n readonly isError: false;\n readonly value: JsonValue;\n readonly content: ContentBlock[];\n readonly error?: never;\n readonly meta?: JsonValue;\n readonly additionalContexts?: UserMessage[];\n readonly concludesTurn?: true;\n }\n export type ToolExecutionToken = symbol & {\n readonly [toolExecutionTokenBrand]: true;\n };\n export interface ToolFailure {\n message: string;\n info?: ToolErrorInfo;\n }\n export type ToolGuard = (execution: Readonly) => string | undefined;\n export interface ToolMessageSource {\n kind: 'tool';\n callId: CallId;\n }\n export interface ToolOutputDefinition {\n readonly schema: JsonSchemaNode;\n render(args: unknown, value: JsonValue): ContentBlock[];\n presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n }\n export interface ToolRestriction {\n readonly allow?: readonly string[];\n readonly deny?: readonly string[];\n }\n export interface ToolResult {\n content: ContentBlock[];\n isError: boolean;\n meta?: JsonValue;\n }\n export interface ToolResultBlock {\n type: 'tool-result';\n toolCallId: CallId;\n content: ContentBlock[];\n isError?: boolean;\n }\n export interface ToolResultMessage extends Message {\n readonly role: 'user';\n readonly content: [\n ToolResultBlock\n ];\n readonly source: ToolMessageSource;\n }\n export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\n export interface ToolRunContext extends ToolExecution {\n deferContext(context: UserMessage): void;\n concludeTurn(): void;\n }\n export interface ToolSchema {\n name: string;\n description: string;\n parameters: Record;\n }\n export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n export interface TurnEndReasonMap {\n completed: {\n kind: 'completed';\n };\n aborted: {\n kind: 'aborted';\n };\n error: {\n kind: 'error';\n step: number;\n } & ({\n failure: LlmFailure;\n message?: never;\n code?: never;\n } | {\n message: string;\n code?: string;\n failure?: never;\n });\n disposed: {\n kind: 'disposed';\n };\n 'max-tokens': {\n kind: 'max-tokens';\n };\n interrupted: {\n kind: 'interrupted';\n };\n }\n export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];\n export interface TurnTriggerMap {\n message: {\n kind: 'message';\n source: MessageSource;\n };\n retry: {\n kind: 'retry';\n };\n injection: {\n kind: 'injection';\n source: MessageSource;\n };\n }\n export interface UserMessage extends Message {\n readonly role: 'user';\n }\n export interface WebFetchResultView {\n card: 'web';\n kind: 'fetch';\n title?: string;\n url: string;\n statusCode: number;\n truncated: boolean;\n }\n export type WebResultView = WebSearchResultView | WebFetchResultView;\n export interface WebSearchResultView {\n card: 'web';\n kind: 'search';\n title?: string;\n sources: WebSource[];\n answer?: string;\n truncated: boolean;\n }\n export interface WebSource {\n url: string;\n title?: string;\n snippet?: string;\n publishedAt?: string;\n }"}],"isError":false}],"role":"user","id":"a4ec9786-5e3f-45b2-a6de-efdf953287f9"}},"sourceEventSeqs":[13],"surfaceOp":"append"} +{"type":"tool/result","seq":14,"time":1785487622726,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n /**\n * Register globally or in the calling agent scope. Scoped tools shadow\n * globals; duplicates within one layer and the reserved `run_code` name fail.\n * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n * @returns the exact disposer that unregisters the tool.\n */\n register(definition: ToolDefinition): () => void\n /**\n * Restrict global tools for the calling agent scope. Empty filters, unknown\n * names, scope-local names, and reserved transport names fail. Restrictions\n * intersect; scoped registrations remain visible.\n * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n * @returns the exact disposer that lifts this restriction.\n */\n restrict(filter: ToolRestriction): () => void\n /**\n * Register a monotonic guard after the extensible `tools/pre-execute`\n * waterfall. A plain-context guard applies globally; one registered through\n * `agent.ctx` applies only to that agent. Any matching guard may deny by\n * returning a reason, while no guard can force-allow a call another guard\n * denied. The exact effect disposer is returned for ordered ownership and\n * HMR cleanup.\n * @param guard - synchronous check; a returned string denies the execution.\n * @returns the exact disposer that unregisters the guard.\n */\n guard(guard: ToolGuard): () => void\n /**\n * Look up a tool as one scope sees it (scoped\n * shadows global; a restricted-away global reads as absent). Presenters pass\n * the calling agent so the rendered card matches the definition that\n * actually executed.\n * @param name - the tool name as registered.\n * @param scope - the viewing scope (the agent); omitted = the global view.\n * @returns the definition the scope resolves, or undefined when none is visible.\n */\n get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n /**\n * Project visible definitions onto the allowlisted model-facing schema fields,\n * excluding execution and presentation callbacks.\n * @param scope - the viewing scope (the agent); omitted = the global view.\n * @returns one deep-cloned schema per visible tool.\n */\n schemas(scope?: ScopeKey): ToolSchema[]\n /**\n * Classify a pending call through the caller's visible tool definition. Only\n * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n * throwing classifiers are exclusive.\n * @param exec - call name, parsed arguments, and optional agent scope.\n * @returns the fail-closed scheduling mode.\n */\n executionMode(exec: ToolExecutionInput): ToolExecutionMode\n /**\n * Execute through pre-policy, guards, around-dispatch, post-policy,\n * definition-owned content finalization, and final notification. Tool and\n * listener failures resolve as materialized error results; an invisible tool\n * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n * snapshot final observers receive. Cancellation\n * arriving after entry and before final result materialization skips a\n * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n * successful started outcome with `ABORTED`; already-started work is still\n * drained and may retain a tool-owned structured error.\n * @param exec - the typed same-process call input. The registry assigns its\n * correlation token before policy begins.\n * @returns the materialized final result.\n */\n async execute(exec: ToolExecutionInput): Promise\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n export interface Agent {\n readonly id: SessionId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly status: AgentStatus;\n readonly acceptsNextStep: boolean;\n readonly ctx: Context;\n send(message: UserMessage, options: SendOptions): void;\n reserveTurnAdmission(): (() => void) | undefined;\n updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult;\n cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n whenIdle(): Promise;\n followup(message: UserMessage): void;\n steer(message: UserMessage): void;\n inject(message: UserMessage): void;\n }\n export type AgentCancelCause = {\n readonly kind: 'user';\n } | {\n readonly kind: 'parent';\n };\n export interface AgentOptions {\n provider?: string;\n model?: string;\n maxTokens?: number;\n }\n export type AgentStatus = 'idle' | 'running';\n export interface AssistantMessage extends Message {\n readonly role: 'assistant';\n readonly source: ModelMessageSource;\n }\n export interface AssistantProvenance {\n provider: string;\n model: string;\n replayState?: unknown;\n }\n export type Branded = string & {\n readonly [BRAND]: B;\n };\n export type CallId = Branded<'CallId'>;\n export interface CancelOptions {\n keepInbox?: boolean;\n }\n export interface ContentBlockMap {\n 'text': TextBlock;\n 'reasoning': ReasoningBlock;\n 'tool-call': ToolCallBlock;\n 'tool-result': ToolResultBlock;\n }\n export type ContentBlockType = keyof ContentBlockMap;\n export interface DiffCallView {\n card: 'diff';\n title: string;\n diffs: FileDiff[];\n locations?: FileLocation[];\n }\n export interface DiffResultView {\n card: 'diff';\n title?: string;\n diffs: FileDiff[];\n }\n export interface EpochHeader {\n config: LlmCallConfig;\n adapterDefaults?: LlmCallConfigAdapterDefaults;\n system?: string;\n tools?: ToolSchema[];\n }\n export interface FileDiff {\n path: string;\n oldText: string | null;\n newText: string;\n }\n export interface FileLocation {\n path: string;\n line?: number;\n }\n export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n export interface FinishReasonMap {\n 'stop': {\n kind: 'stop';\n };\n 'tool-calls': {\n kind: 'tool-calls';\n };\n 'max-tokens': {\n kind: 'max-tokens';\n };\n 'aborted': {\n kind: 'aborted';\n failure: LlmFailure;\n };\n 'error': {\n kind: 'error';\n failure: LlmFailure;\n };\n }\n export interface GenericCallView {\n card: 'generic';\n title: string;\n kind?: ToolCallKind;\n rawInput?: unknown;\n content?: ContentBlock[];\n locations?: FileLocation[];\n }\n export interface GenericResultView {\n card: 'generic';\n title?: string;\n content?: ContentBlock[];\n }\n export type InboxAction = {\n readonly kind: 'edit';\n readonly content: ContentBlock[];\n } | {\n readonly kind: 'remove';\n };\n export type InboxActionResult = 'applied' | 'not-found';\n export type InboxItemId = Branded<'InboxItemId'>;\n export interface JsonSchemaNode {\n type?: JsonSchemaType;\n oneOf?: JsonSchemaNode[];\n properties?: Record;\n required?: string[];\n additionalProperties?: boolean;\n items?: JsonSchemaNode;\n enum?: JsonSchemaScalar[];\n const?: JsonSchemaScalar;\n description?: string;\n title?: string;\n default?: JsonValue;\n examples?: JsonValue;\n }\n export type JsonSchemaScalar = string | number | boolean | null;\n export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n export type JsonValue = null | boolean | number | string | JsonValue[] | {\n [key: string]: JsonValue;\n };\n export interface LlmCallConfig {\n provider: string;\n model: string;\n reasoningEffort?: ReasoningEffortId;\n temperature?: number;\n maxTokens?: number;\n stop?: string[];\n }\n export interface LlmCallConfigAdapterDefaults {\n reasoningEffort?: true;\n maxTokens?: true;\n }\n export interface LlmFailure {\n readonly message: string;\n readonly code: string;\n readonly status?: number;\n readonly providerRetryAfterMs?: number;\n readonly requestId?: ProviderRequestId;\n }\n export interface Message {\n readonly id: MessageId;\n readonly role: 'system' | 'user' | 'assistant';\n readonly content: ContentBlock[];\n readonly source: MessageSource;\n }\n export type MessageId = Branded<'MessageId'>;\n export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n export interface MessageSourceMap {\n user: {\n kind: 'user';\n };\n plugin: {\n kind: 'plugin';\n plugin: string;\n };\n model: ModelMessageSource;\n tool: ToolMessageSource;\n }\n export interface ModelMessageSource extends AssistantProvenance {\n kind: 'model';\n }\n export type ProviderRequestId = Branded<'ProviderRequestId'>;\n export interface ReadFileLine {\n number: number;\n text: string;\n }\n export interface ReadResultView {\n card: 'read';\n title?: string;\n path: string;\n offset: number;\n lines: ReadFileLine[];\n totalLines: number;\n lang?: string;\n content?: ContentBlock[];\n }\n export interface ReasoningBlock {\n type: 'reasoning';\n text: string;\n }\n export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n export interface RequestContext {\n provider: string;\n model: string;\n contextWindow?: number;\n }\n export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n export type ScopeKey = object;\n export interface SearchFileMatches {\n path: string;\n matches: SearchLineMatch[];\n }\n export interface SearchLineMatch {\n lineNumber: number;\n line: string;\n }\n export interface SearchMatchesResultView {\n card: 'search';\n shape: 'matches';\n title?: string;\n files: SearchFileMatches[];\n truncated: boolean;\n total: number;\n }\n export interface SearchPathsResultView {\n card: 'search';\n shape: 'paths';\n title?: string;\n paths: string[];\n truncated: boolean;\n total: number;\n }\n export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\n export interface SendOptions {\n target: SendTarget;\n wakeup: boolean;\n }\n export type SendTarget = 'next-turn' | 'next-step';\n export class Session {\n get surface(): SessionSurface;\n readonly header: SessionHeader;\n get id(): SessionId;\n readonly firstLiveSeq: number;\n constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\n get events(): readonly SessionEvent[];\n get seq(): number;\n append(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n opts: SurfaceIntent\n ] : [\n ]): SessionEvent;\n requestHeader(): EpochHeader | undefined;\n requestContext(): RequestContext | undefined;\n deriveMessages(): Message[];\n deriveEventMessage(event: SessionEvent): Message | null;\n }\n export type SessionEvent = {\n [K in SessionEventType]: {\n type: K;\n seq: number;\n time: number;\n data: SessionEventMap[K];\n } & (K extends SurfaceEventType ? {\n sourceEventSeqs?: number[];\n surfaceOp?: SurfaceOp;\n } : object);\n }[T];\n export interface SessionEventMap {\n 'turn/start': {\n turn: number;\n trigger: TurnTrigger;\n };\n 'turn/end': {\n turn: number;\n reason: TurnEndReason;\n };\n 'step/start': {\n turn: number;\n step: number;\n };\n 'step/end': {\n turn: number;\n step: number;\n };\n 'user/message': UserMessage;\n 'assistant/chunk': {\n turn: number;\n step: number;\n chunk: StreamChunk;\n };\n 'assistant/message': {\n turn: number;\n step: number;\n message: AssistantMessage;\n usage?: TokenUsage;\n };\n 'tool/call': {\n turn: number;\n step: number;\n callId: CallId;\n name: string;\n arguments: string;\n };\n 'tool/result': {\n turn: number;\n step: number;\n message: ToolResultMessage;\n error?: {\n name: string;\n code: string;\n };\n meta?: JsonValue;\n };\n 'steering/message': {\n turn: number;\n message: UserMessage;\n };\n 'todo/write': {\n todos: TodoItem[];\n };\n 'request/header': {\n header: EpochHeader;\n reason: RequestHeaderReason;\n };\n 'request/context': RequestContext;\n 'session/end-seed': Record;\n }\n export type SessionEventType = keyof SessionEventMap;\n export interface SessionHeader {\n readonly version: number;\n readonly id: SessionId;\n readonly createdAt: number;\n readonly cwd?: string;\n readonly parentSession?: SessionId;\n readonly seedLength?: number;\n readonly delegationDepth?: number;\n }\n export type SessionId = Branded<'SessionId'>;\n export interface SessionSurface {\n readonly nodes: readonly number[];\n readonly replaceGeneration: number;\n }\n export type StreamChunk = {\n type: 'block-start';\n index: number;\n blockType: ContentBlockType;\n } | {\n type: 'text-delta';\n index: number;\n text: string;\n } | {\n type: 'reasoning-delta';\n index: number;\n text: string;\n } | {\n type: 'tool-call-delta';\n index: number;\n id: CallId;\n name?: string;\n argumentsDelta: string;\n } | {\n type: 'block-end';\n index: number;\n block: ContentBlock;\n } | {\n type: 'usage';\n usage: TokenUsage;\n } | {\n type: 'finish';\n reason: FinishReason;\n replayState?: unknown;\n };\n export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result' | 'steering/message';\n export interface SurfaceIntent {\n surfaceOp: SurfaceOp;\n sourceEventSeqs?: number[];\n }\n export type SurfaceOp = 'append' | {\n op: 'replace';\n start: number;\n end: number;\n };\n export interface TerminalCallView {\n card: 'terminal';\n title: string;\n description?: string;\n cwd?: string;\n }\n export interface TerminalResultView {\n card: 'terminal';\n title?: string;\n output?: string;\n exitCode?: number;\n signal?: string;\n }\n export interface TodoItem {\n content: string;\n status: 'pending' | 'in_progress' | 'completed';\n }\n export interface TokenUsage {\n inputTokens: number;\n outputTokens: number;\n cacheReadTokens?: number;\n cacheWriteTokens?: number;\n reasoningTokens?: number;\n }\n export interface ToolCallBlock {\n type: 'tool-call';\n id: CallId;\n name: string;\n arguments: string;\n }\n export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n export interface ToolDefinition extends ToolSchema {\n readonly output: ToolOutputDefinition;\n execute(args: unknown, exec: ToolRunContext): Promise;\n finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\n timeoutMs?: number;\n isConcurrencySafe?(args: unknown): boolean;\n presentCall?(args: unknown): ToolCallView | undefined;\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n }\n export interface ToolErrorInfo {\n name: string;\n code: string;\n }\n export interface ToolExecution extends ToolExecutionInput {\n readonly token: ToolExecutionToken;\n }\n export interface ToolExecutionFailure {\n readonly isError: true;\n readonly error: ToolFailure;\n readonly value?: never;\n readonly content: ContentBlock[];\n readonly meta?: JsonValue;\n readonly additionalContexts?: UserMessage[];\n readonly concludesTurn?: never;\n }\n export interface ToolExecutionInput {\n readonly callId: CallId;\n readonly name: string;\n readonly arguments: unknown;\n readonly agent?: Agent;\n readonly parent?: ToolExecutionToken;\n readonly signal: AbortSignal;\n }\n export type ToolExecutionMode = {\n kind: 'parallel';\n } | {\n kind: 'exclusive';\n };\n export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n export interface ToolExecutionSuccess {\n readonly isError: false;\n readonly value: JsonValue;\n readonly content: ContentBlock[];\n readonly error?: never;\n readonly meta?: JsonValue;\n readonly additionalContexts?: UserMessage[];\n readonly concludesTurn?: true;\n }\n export type ToolExecutionToken = symbol & {\n readonly [toolExecutionTokenBrand]: true;\n };\n export interface ToolFailure {\n message: string;\n info?: ToolErrorInfo;\n }\n export type ToolGuard = (execution: Readonly) => string | undefined;\n export interface ToolMessageSource {\n kind: 'tool';\n callId: CallId;\n }\n export interface ToolOutputDefinition {\n readonly schema: JsonSchemaNode;\n render(args: unknown, value: JsonValue): ContentBlock[];\n presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n }\n export interface ToolRestriction {\n readonly allow?: readonly string[];\n readonly deny?: readonly string[];\n }\n export interface ToolResult {\n content: ContentBlock[];\n isError: boolean;\n meta?: JsonValue;\n }\n export interface ToolResultBlock {\n type: 'tool-result';\n toolCallId: CallId;\n content: ContentBlock[];\n isError?: boolean;\n }\n export interface ToolResultMessage extends Message {\n readonly role: 'user';\n readonly content: [\n ToolResultBlock\n ];\n readonly source: ToolMessageSource;\n }\n export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\n export interface ToolRunContext extends ToolExecution {\n deferContext(context: UserMessage): void;\n concludeTurn(): void;\n }\n export interface ToolSchema {\n name: string;\n description: string;\n parameters: Record;\n }\n export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n export interface TurnEndReasonMap {\n completed: {\n kind: 'completed';\n };\n aborted: {\n kind: 'aborted';\n };\n error: {\n kind: 'error';\n step: number;\n } & ({\n failure: LlmFailure;\n message?: never;\n code?: never;\n } | {\n message: string;\n code?: string;\n failure?: never;\n });\n disposed: {\n kind: 'disposed';\n };\n 'max-tokens': {\n kind: 'max-tokens';\n };\n interrupted: {\n kind: 'interrupted';\n };\n }\n export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];\n export interface TurnTriggerMap {\n message: {\n kind: 'message';\n source: MessageSource;\n };\n retry: {\n kind: 'retry';\n };\n injection: {\n kind: 'injection';\n source: MessageSource;\n };\n }\n export interface UserMessage extends Message {\n readonly role: 'user';\n }\n export interface WebFetchResultView {\n card: 'web';\n kind: 'fetch';\n title?: string;\n url: string;\n statusCode: number;\n truncated: boolean;\n }\n export type WebResultView = WebSearchResultView | WebFetchResultView;\n export interface WebSearchResultView {\n card: 'web';\n kind: 'search';\n title?: string;\n sources: WebSource[];\n answer?: string;\n truncated: boolean;\n }\n export interface WebSource {\n url: string;\n title?: string;\n snippet?: string;\n publishedAt?: string;\n }"}],"isError":false}],"role":"user","id":"a4ec9786-5e3f-45b2-a6de-efdf953287f9"}},"sourceEventSeqs":[13],"surfaceOp":"append"} {"type":"step/end","seq":15,"time":1785487622726,"data":{"turn":1,"step":1}} {"type":"step/start","seq":16,"time":1785487622735,"data":{"turn":1,"step":2}} {"type":"assistant/chunk","seq":17,"time":1784449176734,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} diff --git a/knip.json b/knip.json index f5379c8c6e..99b152738d 100644 --- a/knip.json +++ b/knip.json @@ -622,7 +622,9 @@ "tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/**/*.snapshot.ts", - "tests/fixtures/tui-scripted-llm.ts" + "tests/fixtures/tui-scripted-llm.ts", + "tests/fixtures/composition-echo-llm.ts", + "tests/fixtures/composition-settled.ts" ], "project": [ "src/**/*.ts", diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml index e3d86bb196..0783d0662f 100644 --- a/packages/client/runtime/README.i18n.yaml +++ b/packages/client/runtime/README.i18n.yaml @@ -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 packages/client/runtime/README.md -README.md: e8ba80790307e7123406934c1ab11b86dfc0faf3 -README.zh.md: 6eb69d9cf10959b007f3759378612dbc013a8904 +README.md: 0ae71ff17b13be67c16786ff69a0e1626437913a +README.zh.md: 52a443d9df753ba01650b6cbf189c39633f6a461 diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md index e8ba807903..0ae71ff17b 100644 --- a/packages/client/runtime/README.md +++ b/packages/client/runtime/README.md @@ -30,6 +30,10 @@ SlotsService gives the renderer separate bare observables for `useSessions` and Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text comes from the checkpoint's `compact/summary` provenance; a window cut that left the provenance outside makes the row non-expandable rather than empty, and a later page that supplies it resolves the text. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity. +## Request inspection + +`SessionHistoryInspection.requests` is one chronological, purpose-discriminated provider-request stream. Assistant requests always carry their numeric `turn` and `step`; compaction requests carry `step: 0` and a `turn` owner that may be `null`. That null owner means a manual compaction ran standalone between turns, not that it belongs to either adjacent turn. A `session/end-seed` boundary closes an unmatched compaction request as an error at the boundary time with `Compaction was interrupted before completion.`; a later start projects as an independent request instead of overwriting the orphan. + ## Code Mode sub-dispatch index `ConversationSnapshot.codeDispatches` groups a `run_code` call's sub-dispatches under their parent callId, in start order, using the native call-block shapes: a `tool/code-dispatch-start` event lands the `RunningToolCall` form (rows derive the running ring from the shape) and its `tool/code-dispatch` settlement replaces it in place with the `ToolResultNode` form, `callTime` carrying the paired start's time. A settle whose start fell outside the replay window appends directly with `callTime: null` (duration unknown — never a fabricated zero). Live mux frames and history replay build the identical index; sub-calls never join the transcript `nodes` flow; per-parent array and map references are memo-stable across unrelated snapshot swaps. @@ -40,7 +44,7 @@ Because the projection is log-ordered, the node array is seq-monotonic by constr ## Model retry projection -The Session object validates plugin-owned, provider-routed `llm/retry` payloads at the event wire boundary against the producer's complete field contract, including timer, integer, status, provider-delay, and non-empty diagnostic bounds. A valid event removes the matching failed step's streaming partial and inserts a durable retry notice at the event's sequence position. The notice is `scheduled` until a following retry turn starts; an aborted or disposed source turn marks it `cancelled`, while the retry turn marks it `started`. Normal-mode notices carry their finite maximum; always-mode notices remain explicitly unbounded. Window rebuild and history replay apply the same projection, so logged chunks from the discarded attempt never reappear as an interrupted reply after refresh. A terminal turn without `llm/retry` retains the existing behavior: visible unfinalized output is frozen as an interrupted assistant node. +The Session object validates plugin-owned, provider-routed `llm/retry` payloads at the event wire boundary against the producer's complete field contract, including timer, integer, status, provider-delay, and non-empty diagnostic bounds. A valid event removes the matching failed step's streaming partial and inserts a durable retry notice at the event's sequence position. The notice is `scheduled` until a following retry turn starts; an aborted or disposed source turn marks it `cancelled`, while the retry turn marks it `started`. Normal-mode notices carry their finite maximum; always-mode notices remain explicitly unbounded. A terminal `turn/end` error without a retry projects one `turn-error` node from its durable message and optional code; AUTH projections replace provider copy that may echo credential fragments with `API key is invalid`, while the raw diagnostic remains in the session log. A retried failure keeps only the retry notice for that attempt. Window rebuild and history replay apply the same projection, so refresh neither resurrects discarded chunks nor loses terminal failure feedback. Visible unfinalized output is frozen as an interrupted assistant node beside the terminal error. ## Session forking diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md index 6eb69d9cf1..52a443d9df 100644 --- a/packages/client/runtime/README.zh.md +++ b/packages/client/runtime/README.zh.md @@ -30,6 +30,10 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时该行不可展开而非空白，后续补上溯源的分页会解析出文本。性能契约：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。 +## 请求检查 + +`SessionHistoryInspection.requests` 是一条按时间顺序排列、以用途为判别字段的提供方请求流。助手请求始终携带数值型 `turn` 与 `step`；压缩请求携带 `step: 0`，其 `turn` 所有者可以是 `null`。这个 null 所有者表示手动压缩独立运行在两个轮次之间，并不表示它属于任一相邻轮次。`session/end-seed` 边界会在边界时刻将未匹配的压缩请求以错误状态结束，错误固定为 `Compaction was interrupted before completion.`；后续 start 会投影为独立请求，而不会覆盖这项遗留的未匹配请求。 + ## Code Mode 子调用索引 `ConversationSnapshot.codeDispatches` 按父调用的 callId 和启动顺序，用原生调用块形状组织一个 `run_code` 调用的子调用：`tool/code-dispatch-start` 事件落成 `RunningToolCall` 形状（行组件从该形状推导运行中的转圈状态），其 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode` 形状，`callTime` 携带成对 start 事件的时间。start 落在回放窗口之外的完结事件则直接追加，`callTime: null`（耗时未知——绝不伪造零耗时）。live mux 帧与历史回放构建相同的索引；子调用永不进入 transcript 的 `nodes` 流；无关快照交换不会改变每个父调用对应的数组引用和映射引用，两者均保持 memo 稳定。 @@ -40,7 +44,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 ## 模型重试投影 -Session 对象会在事件 wire 边界依据生产方的完整字段契约，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括计时器、整数、状态、提供方延迟和非空诊断字段的边界。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或被 dispose（资源释放）时，会将该提示标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。窗口重建与历史回放应用相同的投影，因此刷新后，来自已丢弃尝试的日志分片绝不会重新显示为中断回复。没有 `llm/retry` 的终止轮次保留现有行为：可见但尚未定稿的输出会冻结为中断的 assistant 节点。 +Session 对象会在事件 wire 边界依据生产方的完整字段契约，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括计时器、整数、状态、提供方延迟和非空诊断字段的边界。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或被 dispose（资源释放）时，会将该提示标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败则只保留该次尝试的重试提示。窗口重建与历史回放应用相同的投影，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 assistant 节点。 ## 会话 fork diff --git a/packages/client/runtime/src/client/contract/session.ts b/packages/client/runtime/src/client/contract/session.ts index 82bde108b4..f2c7d4183d 100644 --- a/packages/client/runtime/src/client/contract/session.ts +++ b/packages/client/runtime/src/client/contract/session.ts @@ -46,7 +46,8 @@ export interface ISession { */ updateQueue(itemId: InboxItemId, action: QueueAction): Promise> /** - * Cancel the running turn. + * Cancel the running turn. Pending queued work remains and resumes in FIFO + * order after the Host reaches cancellation quiescence. * @returns acceptance, or the business error. */ cancel(): Promise> diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts index ef923c9226..2e9b131c77 100644 --- a/packages/client/runtime/src/client/index.ts +++ b/packages/client/runtime/src/client/index.ts @@ -47,7 +47,7 @@ export type { AssistantTiming, CodeSubCall, CommandNode, CompactionSummaryNode, ComposerPhase, ContextMessageNode, ConversationNode, ConversationSnapshot, ModelRetryNode, QueuedMessage, RunningToolCall, - SteeringMessageNode, TodoItem, ToolResultNode, UnknownSurfaceNode, UserMessageNode, + SteeringMessageNode, TodoItem, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode, } from './sessions/conversation.ts' export type { ConversationContext, ConversationContextOriginKind, diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts index 615ac27e77..f34c83689a 100644 --- a/packages/client/runtime/src/client/sessions/conversation.ts +++ b/packages/client/runtime/src/client/sessions/conversation.ts @@ -135,6 +135,19 @@ export type ModelRetryNode = LlmRetryEventData & { retryState: 'scheduled' | 'started' | 'cancelled' } +/** Durable terminal failure for a turn that has no scheduled retry. */ +export interface TurnErrorNode { + kind: 'turn-error' + /** Seq of the owning turn/end event. */ + seq: number + /** Unix epoch ms from the turn/end event. */ + time: number + turn: number + step: number + message: string + code?: string +} + /** A tool result paired (when in-window) with its call head. */ export interface ToolResultNode { kind: 'tool-result' @@ -223,6 +236,7 @@ export type ConversationNode = | SteeringMessageNode | ContextMessageNode | ModelRetryNode + | TurnErrorNode | ToolResultNode | CommandNode | CompactionSummaryNode diff --git a/packages/client/runtime/src/client/sessions/failure-display.ts b/packages/client/runtime/src/client/sessions/failure-display.ts new file mode 100644 index 0000000000..637329772b --- /dev/null +++ b/packages/client/runtime/src/client/sessions/failure-display.ts @@ -0,0 +1,10 @@ +/** + * Convert a durable failure into copy that is safe to expose in the GUI. + * @param failure - Structured failure preserved by the session event. + * @returns Display-safe copy for client projections. + */ +export function displayFailureMessage(failure: { code?: string; message: string }): string { + // Provider AUTH messages may echo a masked or partially preserved credential. + // Keep the raw diagnostic in the session log, but never project it into UI state. + return failure.code === 'AUTH' ? 'API key is invalid' : failure.message +} diff --git a/packages/client/runtime/src/client/sessions/request-inspection.ts b/packages/client/runtime/src/client/sessions/request-inspection.ts index e15ad55c8b..49ff8d974f 100644 --- a/packages/client/runtime/src/client/sessions/request-inspection.ts +++ b/packages/client/runtime/src/client/sessions/request-inspection.ts @@ -8,6 +8,7 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session/types' import type { AssistantProvenanceView, AssistantRequestConfig, } from './conversation.ts' +import { displayFailureMessage } from './failure-display.ts' export type { AssistantProvenanceView, AssistantRequestConfig, @@ -35,40 +36,55 @@ export interface RequestPromptChange { previous?: ConversationPromptSnapshot } -/** One provider request reconstructed from durable request lifecycle events. */ -export interface RequestView { - /** Request category; compaction is a purpose, not a separate projection. */ - purpose: 'assistant' | 'compaction' +/** Lifecycle fields shared by ordinary generation and compaction requests. */ +interface RequestViewBase { /** Sequence that opened the operation represented by this request. */ startSeq: number - turn: number - /** Agent-loop step, or zero for a direct compaction request. */ - step: number startedAt: number completedAt: number | null status: 'running' | 'complete' | 'error' error?: string - /** Effective ordinary request input, inherited until a later header changes it. */ - prompt?: ConversationPromptSnapshot - /** Prompt change logged while preparing this request. */ - promptChange?: RequestPromptChange provenance?: AssistantProvenanceView requestConfig?: AssistantRequestConfig usage?: unknown /** Assistant message or compaction summary sequence produced by this request. */ resultSeq?: number +} + +/** One ordinary assistant generation reconstructed from durable request events. */ +interface AssistantRequestView extends RequestViewBase { + purpose: 'assistant' + turn: number + /** Agent-loop step that issued this request. */ + step: number + /** Effective ordinary request input, inherited until a later header changes it. */ + prompt?: ConversationPromptSnapshot + /** Prompt change logged while preparing this request. */ + promptChange?: RequestPromptChange + /** Retry ordinal scheduled after a failed ordinary request. */ + retry?: number + maxRetries?: number + retryDelayMs?: number +} + +/** One compaction provider request, either turn-owned or standalone between turns. */ +interface CompactionRequestView extends RequestViewBase { + purpose: 'compaction' + /** Owning turn, or `null` when manual compaction ran between turns. */ + turn: number | null + /** Direct compaction requests do not consume an agent-loop step. */ + step: 0 /** Compaction replacement message sequence, when one was committed. */ replacementSeq?: number /** Safe compaction summary projection. */ summary?: readonly ContentBlock[] /** Complete compaction provider output before the safe projection. */ rawOutput?: readonly ContentBlock[] - /** Retry ordinal scheduled after a failed ordinary request. */ - retry?: number - maxRetries?: number - retryDelayMs?: number } +/** One provider request reconstructed from durable request lifecycle events. */ +export type RequestView = AssistantRequestView | CompactionRequestView + /** Immutable request-centric projection derived from one history window. */ export interface RequestInspectionSnapshot { requests: readonly RequestView[] @@ -110,7 +126,7 @@ interface CompactionStartEvent { type: 'compact/start' seq: number time: number - data: { turn: number } + data: { turn: number | null } } interface CompactionSummaryEvent { @@ -131,7 +147,7 @@ interface CompactionEndEvent { type: 'compact/end' seq: number time: number - data: { turn: number; error?: string } + data: { turn: number | null; error?: string } } function requestKey(turn: number, step: number): string { @@ -228,10 +244,21 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[] let activePrompt: ConversationPromptSnapshot | undefined let activeCompaction: number | undefined - const update = (index: number | undefined, change: Partial): void => { + const updateAssistant = ( + index: number | undefined, + change: Partial>, + ): void => { if (index === undefined) return const request = requests[index] - if (request !== undefined) requests[index] = { ...request, ...change } + if (request?.purpose === 'assistant') requests[index] = { ...request, ...change } + } + const updateCompaction = ( + index: number | undefined, + change: Partial>, + ): void => { + if (index === undefined) return + const request = requests[index] + if (request?.purpose === 'compaction') requests[index] = { ...request, ...change } } for (const sourceEvent of events) { @@ -263,7 +290,7 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[] } const change = promptChange(activePrompt, prompt, sourceEvent) activePrompt = prompt - update(activeStep === undefined ? undefined : ordinaryByStep.get(activeStep), { + updateAssistant(activeStep === undefined ? undefined : ordinaryByStep.get(activeStep), { prompt, requestConfig: prompt.config, ...(change === undefined ? {} : { promptChange: change }), @@ -278,8 +305,11 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[] requestKey(sourceEvent.data.turn, sourceEvent.data.step), ) const request = index === undefined ? undefined : requests[index] - update(index, { - usage: addTokenUsage(request?.usage, sourceEvent.data.chunk.usage), + updateAssistant(index, { + usage: addTokenUsage( + request?.purpose === 'assistant' ? request.usage : undefined, + sourceEvent.data.chunk.usage, + ), }) continue } @@ -288,7 +318,7 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[] requestKey(sourceEvent.data.turn, sourceEvent.data.step), ) const request = index === undefined ? undefined : requests[index] - update(index, { + updateAssistant(index, { completedAt: sourceEvent.time, status: 'complete', resultSeq: sourceEvent.seq, @@ -296,7 +326,9 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[] provider: sourceEvent.data.message.source.provider, model: sourceEvent.data.message.source.model, }, - ...(request?.usage !== undefined || sourceEvent.data.usage === undefined + ...(request?.purpose === 'assistant' + && request.usage !== undefined + || sourceEvent.data.usage === undefined ? {} : { usage: sourceEvent.data.usage }), }) @@ -306,8 +338,8 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[] const key = requestKey(sourceEvent.data.turn, sourceEvent.data.step) const index = ordinaryByStep.get(key) const request = index === undefined ? undefined : requests[index] - if (request?.status === 'running') { - update(index, { + if (request?.purpose === 'assistant' && request.status === 'running') { + updateAssistant(index, { completedAt: sourceEvent.time, status: 'error', }) @@ -317,9 +349,9 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[] } if ((sourceEvent.type as string) === 'llm/retry') { const event = sourceEvent as unknown as RetryEvent - update(ordinaryByStep.get(requestKey(event.data.turn, event.data.step)), { + updateAssistant(ordinaryByStep.get(requestKey(event.data.turn, event.data.step)), { status: 'error', - error: event.data.failure.message, + error: displayFailureMessage(event.data.failure), retry: event.data.retry, maxRetries: event.data.maxRetries, retryDelayMs: event.data.delayMs, @@ -328,14 +360,23 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[] } if (sourceEvent.type === 'turn/end' && sourceEvent.data.reason.kind === 'error') { const reason = sourceEvent.data.reason - update(ordinaryByStep.get(requestKey(sourceEvent.data.turn, reason.step)), { + updateAssistant(ordinaryByStep.get(requestKey(sourceEvent.data.turn, reason.step)), { status: 'error', - error: 'failure' in reason ? reason.failure.message : reason.message, + error: displayFailureMessage('failure' in reason ? reason.failure : reason), }) continue } const type = sourceEvent.type as string + if (type === 'session/end-seed' && activeCompaction !== undefined) { + updateCompaction(activeCompaction, { + completedAt: sourceEvent.time, + status: 'error', + error: 'Compaction was interrupted before completion.', + }) + activeCompaction = undefined + continue + } if (type === 'compact/start') { const event = sourceEvent as unknown as CompactionStartEvent activeCompaction = requests.length @@ -352,7 +393,7 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[] } if (type === 'compact/summary' && activeCompaction !== undefined) { const event = sourceEvent as unknown as CompactionSummaryEvent - update(activeCompaction, { + updateCompaction(activeCompaction, { resultSeq: event.seq, summary: event.data.summary, ...(event.data.rawOutput === undefined ? {} : { rawOutput: event.data.rawOutput }), @@ -375,12 +416,12 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[] && activeCompaction !== undefined && isCompactionSource(sourceEvent.data.source) ) { - update(activeCompaction, { replacementSeq: sourceEvent.seq }) + updateCompaction(activeCompaction, { replacementSeq: sourceEvent.seq }) continue } if (type !== 'compact/end' || activeCompaction === undefined) continue const event = sourceEvent as unknown as CompactionEndEvent - update(activeCompaction, { + updateCompaction(activeCompaction, { completedAt: event.time, status: event.data.error === undefined ? 'complete' : 'error', ...(event.data.error === undefined ? {} : { error: event.data.error }), diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts index 1e2bc04d9a..53a69215ac 100644 --- a/packages/client/runtime/src/client/sessions/session.ts +++ b/packages/client/runtime/src/client/sessions/session.ts @@ -19,6 +19,7 @@ import type { import type { PendingInteraction } from './pending.ts' import { PendingWait } from './pending.ts' import { TranscriptAdapter } from './transcript-adapter.ts' +import { displayFailureMessage } from './failure-display.ts' import { Notifier } from './notifier.ts' import { PartialAccumulator } from './partial.ts' import { ProjectionValueStore } from './projection-store.ts' @@ -247,7 +248,8 @@ export class Session implements SessionFace { } /** - * Stop: contract session.cancel 1:1; failures land in promptError (same error-strip display slot). + * Stop the active turn while the Host preserves pending inbox work; failures + * land in promptError (same error-strip display slot). * @returns the cancel result. */ async cancel(): Promise> { @@ -749,6 +751,22 @@ export class Session implements SessionFace { if (event.data.reason.kind === 'aborted' || event.data.reason.kind === 'disposed') { this.settleScheduledRetry('cancelled', event.data.turn) } + if ( + event.data.reason.kind === 'error' + && !this.derivedNodes.some(node => node.kind === 'model-retry' && node.turn === event.data.turn) + ) { + const failure = 'failure' in event.data.reason ? event.data.reason.failure : event.data.reason + this.derivedNodes.push({ + kind: 'turn-error', + seq: event.seq, + time: event.time, + turn: event.data.turn, + step: event.data.reason.step, + message: displayFailureMessage(failure), + ...(failure.code === undefined ? {} : { code: failure.code }), + }) + this.derivedRev++ + } // Aborted turns never finalize. The accumulated partial is VALUE, not residue: freeze it // into an interrupted terminal node (pulse stops, text survives) instead of deleting it. // Shared by live and window-replay paths, so a refresh reconstructs the same frozen node diff --git a/packages/client/runtime/tests/request-inspection.spec.ts b/packages/client/runtime/tests/request-inspection.spec.ts index a76036c076..f354d14654 100644 --- a/packages/client/runtime/tests/request-inspection.spec.ts +++ b/packages/client/runtime/tests/request-inspection.spec.ts @@ -85,6 +85,68 @@ describe('inspectRequests', () => { expect(snapshot.callSchemas.get('call-1')?.name).toBe('read') }) + it('preserves a standalone compaction owner without widening assistant turns', () => { + const snapshot = inspectRequests(entriesOf([ + at(0, 'compact/start', { turn: null }), + at(1, 'compact/summary', { + summary: [{ type: 'text', text: 'standalone summary' }], + provider: 'fake', + model: 'compact-model', + }), + at(2, 'compact/end', { turn: null }), + at(3, 'step/start', { turn: 2, step: 1 }), + ])) + + const [compaction, assistant] = snapshot.requests + expect(compaction).toMatchObject({ + purpose: 'compaction', + turn: null, + step: 0, + status: 'complete', + }) + expect(assistant).toMatchObject({ + purpose: 'assistant', + turn: 2, + step: 1, + status: 'running', + }) + if (assistant?.purpose === 'assistant') { + const turn: number = assistant.turn + expect(turn).toBe(2) + } + }) + + it('interrupts an orphaned compaction at end-seed before projecting a new attempt', () => { + const snapshot = inspectRequests(entriesOf([ + at(0, 'compact/start', { turn: null }), + at(1, 'session/end-seed', {}), + at(2, 'compact/start', { turn: null }), + at(3, 'compact/summary', { + summary: [{ type: 'text', text: 'replacement summary' }], + provider: 'fake', + model: 'compact-model', + }), + at(4, 'compact/end', { turn: null }), + ])) + + expect(snapshot.requests).toMatchObject([ + { + purpose: 'compaction', + startSeq: 0, + status: 'error', + completedAt: 1_700_000_000_001, + error: 'Compaction was interrupted before completion.', + }, + { + purpose: 'compaction', + startSeq: 2, + status: 'complete', + completedAt: 1_700_000_000_004, + summary: [{ type: 'text', text: 'replacement summary' }], + }, + ]) + }) + it('captures schemas for nested tool dispatches from the active request header', () => { const snapshot = inspectRequests(entriesOf([ at(0, 'request/header', { @@ -159,6 +221,33 @@ describe('inspectRequests', () => { }) }) + it('keeps provider credential fragments out of projected request errors', () => { + const snapshot = inspectRequests(entriesOf([ + at(0, 'step/start', { turn: 1, step: 1 }), + at(1, 'turn/end', { + turn: 1, + reason: { + kind: 'error', + step: 1, + failure: { + code: 'AUTH', + message: 'Authentication Fails, Your api key: sk-preview-secret is invalid', + }, + }, + }), + at(2, 'step/start', { turn: 2, step: 1 }), + at(3, 'turn/end', { + turn: 2, + reason: { kind: 'error', step: 1, message: 'plugin exploded' }, + }), + ])) + + expect(snapshot.requests).toMatchObject([ + { status: 'error', error: 'API key is invalid' }, + { status: 'error', error: 'plugin exploded' }, + ]) + }) + it('treats a scrubbed durable-fixture tool catalog as unavailable', () => { const snapshot = inspectRequests(entriesOf([ at(0, 'step/start', { turn: 1, step: 1 }), @@ -179,6 +268,7 @@ describe('inspectRequests', () => { ])) expect(snapshot.callSchemas).toEqual(new Map()) - expect(snapshot.requests[0]?.prompt?.tools).toEqual([]) + const [request] = snapshot.requests + expect(request?.purpose === 'assistant' ? request.prompt?.tools : undefined).toEqual([]) }) }) diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts index fdb961d6f2..73bf901234 100644 --- a/packages/client/runtime/tests/session.spec.ts +++ b/packages/client/runtime/tests/session.spec.ts @@ -211,6 +211,7 @@ describe('live event path', () => { for (const event of retryTurn.slice(7)) feed(event) snapshot = session.getSnapshot() expect(snapshot.nodes.slice(-2).map(node => node.kind)).toEqual(['model-retry', 'assistant']) + expect(snapshot.nodes.some(node => node.kind === 'turn-error')).toBe(false) expect(snapshot.nodes.at(-2)).toMatchObject({ kind: 'model-retry', retryState: 'started' }) expect(snapshot.nodes.at(-1)).toMatchObject({ kind: 'assistant', blocks: [{ kind: 'text', text: '完整回复' }] }) @@ -221,6 +222,50 @@ describe('live event path', () => { expect(replay.session.getSnapshot().partial).toBeNull() }) + it('projects unretried terminal failures at turn/end and reproduces them from history', async () => { + const { session } = await opened() + const feed = (event: SessionEvent) => { + session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) + } + const failedTurns = [ + ev.turnStart(6, 1), + ev.user(7, '鉴权失败'), + at(8, { + type: 'turn/end', + data: { + turn: 1, + reason: { + kind: 'error', + step: 0, + failure: { + code: 'AUTH', + message: 'Authentication Fails, Your api key: sk-preview-secret is invalid', + }, + }, + }, + }), + ev.turnStart(9, 2), + ev.user(10, '内部失败'), + at(11, { + type: 'turn/end', + data: { turn: 2, reason: { kind: 'error', step: 1, message: 'plugin exploded' } }, + }), + ] + for (const event of failedTurns) feed(event) + + const errors = session.getSnapshot().nodes.filter(node => node.kind === 'turn-error') + expect(errors).toMatchObject([ + { seq: 8, turn: 1, step: 0, code: 'AUTH', message: 'API key is invalid' }, + { seq: 11, turn: 2, step: 1, message: 'plugin exploded' }, + ]) + expect('code' in errors[1]!).toBe(false) + + const replay = makeSession() + replay.api.onHistory = () => histResponse([...plainTurn(0, 0, 'a', 'b'), ...failedTurns]) + await replay.session.open() + expect(replay.session.getSnapshot().nodes).toEqual(session.getSnapshot().nodes) + }) + it('rejects retry payloads outside the producer contract without retracting the current partial', async () => { const { session } = await opened() const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) } diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index ac0bd88de1..505d693bb6 100644 --- a/packages/client/ui-conversation/README.i18n.yaml +++ b/packages/client/ui-conversation/README.i18n.yaml @@ -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 packages/client/ui-conversation/README.md -README.md: f7279d2c640d447609c4e9804af633d026b35ed9 -README.zh.md: 2e8f3483c160689cdf5ff283f2955a5c0be4fd8e +README.md: b61a70fb079eb6a1bc2a67b682a337ffdf708b79 +README.zh.md: 0bb1740b166cfacc2bc79fe2f49793796f66c365 diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index f7279d2c64..b61a70fb07 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -6,13 +6,13 @@ Conversation domain: skeleton (header/tabs/composer/empty state), chat view (gro Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. The disclosure renders the checkpoint's `compact/summary` provenance; when that event is outside the loaded window, the row remains visible but non-expandable. The framed checkpoint payload is model-facing and never renders. -The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header occupies the top as ordinary column chrome; beneath it a scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host. +The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it a scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host. The view ring IS a slot: the conversation registration declares the `'conversation.view'` list slot (session scope) in its `children` table, ConversationRoot renders the active entry through its renderSlot share (`only: `), and view tabs project from the ring ledger's registration options (`id`/`order`/`label`). The chat view is this package's own ring entry; other plugins (ui-trajectory) contribute tabs through plain `ctx.slots.register` — the former package-local view registry (`registerView`/`ViewEntry`/`ConversationViewMap` and the chrome attachment table) is retired, with per-view chrome dissolved into the view components themselves. Approvals take over the composer through the chain this package declares: `ApprovalPanel` registers as a selector-routed `'conversation.composer'` entry (the ui-question pattern) and occupies the composer in place of the InputBar while an approval wait is pending (amber strip, justification headline, paired command line from the running call's args, one-shot refuse/allow). The `PendingApproval` domain face in `contract/slots.ts` owns the wire encoding — the `ApprovalResponsePayload` value with the audit correlation — over the runtime's `PendingWait` carrier; the broadcast `approval/resolved` frame settles the wait and restores the composer. The sidebar mirrors the blocked state through the manager-tracked `waitingApproval` list bit (lit for uninstantiated sessions too), which outranks the running ring until the question resolves. Pending waits leave the message flow entirely: questions (ui-question) and approvals (ApprovalPanel) both answer through the composer takeover, so no display-only placeholder card remains. The composer's bottom-row Access seat mounts `PermissionSelect`, fed by the host-computed `permissions` projection through the standard-kit `useProjection` (key absence hides the chip); the chip opens a Menu-primitive dropdown whose kebab-case preset names render as title-case labels. Safe preset picks submit `/permission ` immediately through the bar's injected `command` callback, while `danger-full-access` is presented as `Full access` and first opens an in-page Modal risk confirmation. The enabling action stays disabled until the user checks the acknowledgement; cancel, Escape, close, and mask click submit nothing. -Logged non-user messages render as a default-collapsed `上下文注入` disclosure. It shares the Tool calls header geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded 141px scrollport shows bounded inline JSON for both `content` and `source`, and no tool state, summary, or keyed toolview dispatch is synthesized ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)). +Logged non-user messages render as a default-collapsed `上下文注入` disclosure. It shares the Tool calls header geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap, shows inline JSON for both `content` and `source`, and synthesizes no tool state, summary, or keyed toolview dispatch ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)). Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is a hover-underline link that opens the file with the host OS default application (`host.openPath`, relative paths resolve against the session cwd). Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering. @@ -24,7 +24,7 @@ A `read` call declaring the `read` render intent renders the returned file windo A tool call declaring the `diff` render intent (the `write`/`edit` tools) renders its applied change inline through ui-primitives' `DiffBlock`, the same four-layer shape. `contract/diff-card-model.ts` is the single derivation from the `callView`/`resultView` pair; the settled result's hunks replace the call-time diff, and it yields null — the generic path — for any other card tag or a generic result view (write/edit's execution errors). The keyed `FileMutationRow` (registered under both `write` and `edit`) composes the shared `ToolRow`, feeding the diff as ToolRow's `diff` body, so it is the row's collapsed-by-default expanded card; the summary path link still opens the file through the host, and an errored mutation (no diff card) surfaces its error text through ToolRow's Output section with the first line in the collapsed summary. The render-site fallback and the details panel are diff-aware too. Rows cap at `CHAT_DIFF_MAX_LINES` (8) against the panel's 16 ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)). -The chat flow projects consecutive model-retry nodes across retry turns into one stable, muted status row updated to the latest attempt; every retry event remains in the runtime snapshot and session log. Its frontend countdown anchors the scheduled delay to client receipt, avoiding host/browser clock skew, rounds remaining time up to seconds, and has a one-second floor. The latest unresolved retry uses a left-to-right text shimmer. Subsequent turn facts distinguish an attempt that started from one cancelled during backoff, while the Host running bit only controls the live animation; the row then shows a static completed or cancelled label. Normal policy rows show the finite retry maximum; always policy rows show `∞`. Activating the row reveals the latest exact retry delay and failure message. The client runtime removes each failed step's streaming tail before its retry node arrives, while the status remains visible after a later attempt succeeds. +The chat flow projects consecutive model-retry nodes across retry turns into one stable, muted status row updated to the latest attempt; every retry event remains in the runtime snapshot and session log. Its frontend countdown anchors the scheduled delay to client receipt, avoiding host/browser clock skew, rounds remaining time up to seconds, and has a one-second floor. The latest unresolved retry uses a left-to-right text shimmer. Subsequent turn facts distinguish an attempt that started from one cancelled during backoff, while the Host running bit only controls the live animation; the row then shows a static completed or cancelled label. Normal policy rows show the finite retry maximum; always policy rows show `∞`. Activating the row reveals the latest exact retry delay and failure message. The client runtime removes each failed step's streaming tail before its retry node arrives, while the status remains visible after a later attempt succeeds. An unretried terminal failure renders as a persistent inline status at its turn boundary, showing the display-safe durable message and optional error code without offering an action the Host cannot fulfill; AUTH copy never echoes provider-supplied credential fragments. A `grep`/`glob` call declaring the `search` render intent renders its result inline, at the same render sites, through ui-primitives' `SearchBlock` — grep's matches grouped by file (each a collapsible header of `lineNumber: line` rows), glob's flat path list. `contract/search-card-model.ts` is the single derivation from the snapshot's `resultView`; unlike the terminal card it reads no `callView`, since a search has no matches or paths before `execute`, so a running search shows its summary alone. It yields null — the generic path — for any non-search result view, a `card` or `kind` this client version does not compile, and (because those ride the untrusted wire frame) a known kind whose `files`/`paths` is malformed. The keyed `SearchRow`, registered under both `grep` and `glob` since the derived `kind` decides the shape, composes the shared `ToolRow`, feeding the card as ToolRow's `search` body, so it is the row's collapsed-by-default expanded card; the render-site fallback routes it the same way. Both cap at `CHAT_SEARCH_MAX_LINES` (8) against the panel's 16. A capped search drops rows from the card, but the locator to the rest — grep/glob's `Full … stored at …` footer — lives only in the result text, so the derivation surfaces that as a recovery footer below the card when (and only when) the result was truncated; a settled call with no card at all (an errored search, a nested `run_code` sub-dispatch, a legacy generic result) surfaces its flattened result text through ToolRow's Output section so nothing is lost behind a bare summary ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md)). @@ -61,4 +61,4 @@ None; this package neither assembles nor sends a provider request. - **The approval panel's "Always allow this type" is deferred** — durable grants need a grant-storage design; only allow-once/reject answer today. - **TodoPanel truncates long item text to one ellipsized line** — the figma strip has no wrap or expand affordance; full text is not readable inline. - **Queue edit is text-only** — rows containing non-text blocks still show a flattened preview, but their edit control is disabled because the inline editor cannot preserve those blocks. A text row's edit mode replaces delete with save and cancel; Enter saves and Escape cancels. QueueDock exposes no send-now control. -- **Web exposes pending Queue only** — the Host omits pending steering from the Queue snapshot until steering has its own interaction. A consumed `steering/message` still renders in the durable transcript so external steering remains truthful on replay. +- **Web exposes pending Queue only** — the composer and `conversation.send` never submit `mode:'steer'`. The Host omits pending steering from the Queue snapshot. A consumed `steering/message` still folds into the durable transcript as a plain bubble (no interjection chrome) so external/host steering remains truthful on replay. diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index 2e8f3483c1..0bb1740b16 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -6,11 +6,11 @@ 压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。展开内容来自检查点溯源的 `compact/summary`；该事件位于已加载窗口之外时，标记仍然可见但不可展开。面向模型的带框检查点载荷绝不渲染。 -常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段会话标题栏以普通列 chrome 占据顶部；其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。 +常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。 视图环本身就是 slot：会话注册声明 `'conversation.view'` 列表 slot（Session scope），并将其列在 `children` 表中；ConversationRoot 通过 renderSlot share 渲染活跃配置项（`only: `）；视图标签页从环账本的注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包（package）自身的环配置项；其他插件（ui-trajectory）通过普通的 `ctx.slots.register` 贡献标签页。先前包内的视图注册表（`registerView`／`ViewEntry`／`ConversationViewMap` 及 chrome 附加表）已退役，逐视图 chrome 则被拆入视图组件自身。 -已记录的非用户消息渲染为默认折叠的 `上下文注入` 展开项。它通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 标题栏的几何与交互，同时保留上下文语义：展开后的 141px 滚动区会以内联 JSON 的形式有界展示 `content` 和 `source`，且不会合成工具状态、摘要或键控 toolview 分发（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)）。 +已记录的非用户消息渲染为默认折叠的 `上下文注入` 展开项。它通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 标题栏的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，并以内联 JSON 展示 `content` 和 `source`，且不会合成工具状态、摘要或键控 toolview 分发（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)）。 通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是悬停下划线链接，点击后通过宿主操作系统的默认应用打开文件（`host.openPath`，相对路径相对会话 cwd 解析）。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。 @@ -22,7 +22,7 @@ 声明 `diff` 渲染意图的工具调用（`write`／`edit` 工具），通过 ui-primitives 的 `DiffBlock` 内联渲染其已应用的改动，采用同一套四层结构。`contract/diff-card-model.ts` 是从 `callView`／`resultView` 对推导的唯一位置；已结算 result 的 hunk 替换 call 时 diff，对任何其他 card 标签或 generic result view（write/edit 的执行错误）它返回 null，落回通用路径。键控的 `FileMutationRow`（在 `write` 与 `edit` 下都注册）组合共享的 `ToolRow`，把 diff 作为 ToolRow 的 `diff` body 传入，因此它是该行默认折叠的展开卡片；摘要路径链接仍经 host 打开文件，而出错的改动（没有 diff 卡片）经 ToolRow 的 Output 区呈现其错误文本，首行进入折叠摘要。渲染点兜底行与详情面板同样感知 diff。行的上限是 `CHAT_DIFF_MAX_LINES`（8），面板为 16（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)）。 -聊天流会将跨重试轮次连续出现的模型重试节点投影为一个稳定的弱化状态行，并用最新一次尝试更新该行；每个重试事件仍保留在运行时快照与会话日志中。前端倒计时以客户端收到事件的时刻为计划延迟的起点，避免 Host 与浏览器的时钟偏差；剩余时间向上取整到秒，且下限为 1 秒。最近一次尚未完成的重试会显示从左到右的文字渐变动画。后续轮次事实用于区分已开始的尝试与在退避期间取消的尝试，Host 的 running 位只控制实时动画；随后该行会显示静态的已完成或已取消标签。normal 策略行显示有限重试上限；always 策略行显示 `∞`。激活该行会显示最近一次重试的精确延迟和失败消息。客户端运行时会在相应重试节点到达前移除每个失败步骤的流式输出尾部；后续某次尝试成功后，该状态仍保持可见。 +聊天流会将跨重试轮次连续出现的模型重试节点投影为一个稳定的弱化状态行，并用最新一次尝试更新该行；每个重试事件仍保留在运行时快照与会话日志中。前端倒计时以客户端收到事件的时刻为计划延迟的起点，避免 Host 与浏览器的时钟偏差；剩余时间向上取整到秒，且下限为 1 秒。最近一次尚未完成的重试会显示从左到右的文字渐变动画。后续轮次事实用于区分已开始的尝试与在退避期间取消的尝试，Host 的 running 位只控制实时动画；随后该行会显示静态的已完成或已取消标签。normal 策略行显示有限重试上限；always 策略行显示 `∞`。激活该行会显示最近一次重试的精确延迟和失败消息。客户端运行时会在相应重试节点到达前移除每个失败步骤的流式输出尾部；后续某次尝试成功后，该状态仍保持可见。未进入重试的终态失败会在其轮次边界渲染为持久的内联状态，展示适合显示的持久消息与可选错误码，但不会提供 Host 无法兑现的操作；AUTH 文案绝不会回显提供方给出的凭据片段。 声明 `search` 渲染意图的 `grep`／`glob` 调用，会在同样的渲染点上通过 ui-primitives 的 `SearchBlock` 内联渲染其结果——grep 的匹配按文件分组（每个是一个可折叠的头，下辖 `lineNumber: line` 行），glob 是扁平路径列表。`contract/search-card-model.ts` 是从快照的 `resultView` 推导的唯一位置；与终端卡片不同，它不读 `callView`，因为搜索在 `execute` 前没有匹配或路径，所以运行中的搜索只显示摘要。对任何非搜索的结果视图、当前客户端版本无法编译的 `card` 或 `kind`、以及（因为这些都与不可信的 wire 帧同行）一个 `files`／`paths` 格式错误的已知 kind，它都返回 null，落回通用路径。键控的 `SearchRow` 因推导出的 `kind` 决定形态而同时注册在 `grep` 与 `glob` 下，组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `search` body 传入，因此它是该行默认折叠的展开卡片；渲染点兜底行以同样方式渲染它。两者上限都是 `CHAT_SEARCH_MAX_LINES`（8），面板为 16。被截断的搜索会从卡片里丢掉一些行，但通往其余部分的定位符——grep/glob 的 `Full … stored at …` 脚注——只存在于结果文本里，因此推导在（且仅在）结果被截断时把它作为恢复脚注画在卡片下方；一个完全没有卡片的已结算调用（出错的搜索、嵌套 `run_code` 子派发、旧日志的 generic 结果）则经 ToolRow 的 Output 区呈现其压平后的结果文本，从而不让任何内容丢失在一个光秃秃的摘要之后（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md)）。 @@ -61,4 +61,4 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插 - **审批面板的「始终允许此类」暂缓**：持久授权需要授权存储设计；今天只能回答允许一次／拒绝。 - **TodoPanel 将过长条目截成单行省略号**：figma 条没有换行或展开入口，完整文本无法在行内读完。 - **Queue 编辑仅支持文本**：包含非文本块的行仍显示扁平化预览，但由于内联编辑器无法保留这些块，其编辑控件会被禁用。文本行进入编辑模式后，删除会替换为保存和取消；Enter 保存，Escape 取消。QueueDock 不提供立即发送控件。 -- **Web 仅暴露待处理 Queue**：在 steering（中途引导）拥有专用交互之前，Host 不会把待处理 steering 纳入 Queue 快照。已消费的 `steering/message` 仍会渲染到持久 transcript 中，因此从外部提交的 steering 在回放时仍能如实呈现。 +- **Web 仅暴露待处理 Queue**：composer 与 `conversation.send` 从不提交 `mode:'steer'`。Host 不会把待处理 steering（中途引导）纳入 Queue 快照。已消费的 `steering/message` 仍会折叠进持久 transcript（文本记录），并以无「插话」徽章的普通气泡呈现，因此从外部／Host 提交的 steering 在回放时仍能如实呈现。 diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts index 489ad34e3f..c67431e409 100644 --- a/packages/client/ui-conversation/src/client/apply.ts +++ b/packages/client/ui-conversation/src/client/apply.ts @@ -165,7 +165,6 @@ export function apply(ctx: Context): void { // the resident parent keeps Hero and composer layout identity stable. slots.register({ name: 'conversation.session', - locale: NS, children: { 'conversation.view': { kind: 'list', scope: 'session' } }, store: chatStore, inject: (sessionId: SessionId, _actions: BoundActions): ConversationSessionInjected => ({ @@ -175,7 +174,6 @@ export function apply(ctx: Context): void { version: () => slots.getVersion('conversation.view'), }, bindDraftMirror: write => inputHub.shell(sessionId).bindMirror(write), - open: (id) => { sessions.open(id) }, }), }, ConversationSession) diff --git a/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.module.css b/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.module.css index 7ffdfca5bd..e603931a27 100644 --- a/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.module.css +++ b/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.module.css @@ -1,4 +1,4 @@ -/* Figma 10:2482: 24px Tool calls header, 4px gap, 141px clipped code block. */ +/* Figma 10:2482: 24px Tool calls header, 4px gap, 141px code block cap. */ .root { min-width: 0; @@ -15,7 +15,7 @@ .body { box-sizing: border-box; width: calc(100% - 22px); - height: 141px; + max-height: 141px; margin: 4px 0 0 22px; overflow: auto; padding: 10px 16px 12px 12px; diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.module.css b/packages/client/ui-conversation/src/client/chat/MessageItem.module.css index 308101f3c8..323c5a5769 100644 --- a/packages/client/ui-conversation/src/client/chat/MessageItem.module.css +++ b/packages/client/ui-conversation/src/client/chat/MessageItem.module.css @@ -20,16 +20,6 @@ color: var(--dsw-alias-label-primary); } -.badge { - display: inline-block; - margin-bottom: 4px; - padding: 1px 6px; - border-radius: 6px; - background: var(--dsw-alias-state-warn-primary); - color: var(--dsw-alias-label-primary-foreground); - font-size: 11px; -} - .contextRow { padding: 2px 0; } @@ -191,6 +181,40 @@ color: var(--dsw-alias-label-secondary); } +.turnErrorRow { + display: grid; + grid-template-columns: 10px minmax(0, 1fr) auto; + gap: 8px; + align-items: start; + padding: 2px 0; + font-size: 13px; + line-height: 20px; +} + +.turnErrorDot { + margin-top: 5px; +} + +.turnErrorCopy { + min-width: 0; + overflow-wrap: anywhere; +} + +.turnErrorTitle { + margin-right: 6px; + color: var(--dsw-alias-state-error-primary); + font-weight: 600; +} + +.turnErrorMessage { + color: var(--dsw-alias-label-secondary); +} + +.turnErrorCode { + color: var(--dsw-alias-label-tertiary); + font: var(--dsw-font-markdown-code-block-small); +} + @keyframes retry-shimmer { from { background-position: 100% 50%; diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx index 6f55cd3d01..b54604060a 100644 --- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx +++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx @@ -1,14 +1,15 @@ // MessageItem: simple chat nodes — user bubble (right-aligned, with -// clock + copy / branch IconActions), steering (badged bubble), context -// injection, compaction marker, retry disclosure, and unknown-surface JSON rows. +// clock + copy / branch IconActions), steering (same bubble, no actions), +// context injection, compaction marker, retry disclosure, and +// unknown-surface JSON rows. import { memo, useEffect, useMemo, useState } from 'react' import type { ReactNode } from 'react' import type { CompactionSummaryNode, ContextMessageNode, ModelRetryNode, SteeringMessageNode, - UnknownSurfaceNode, UserMessageNode, + TurnErrorNode, UnknownSurfaceNode, UserMessageNode, } from '@deepseek-ai/dsh-client-runtime/client' -import { JsonBlock, MessageText } from '@deepseek-ai/dsh-client-ui-primitives' +import { JsonBlock, MessageText, StateDot } from '@deepseek-ai/dsh-client-ui-primitives' import type { ChatViewSlotProps } from '../contract/slots.ts' import { CompactionItem } from './CompactionItem.tsx' import { ContextInjectionRow } from './ContextInjectionRow.tsx' @@ -16,7 +17,14 @@ import { MessageIconActions } from './MessageIconActions.tsx' import css from './MessageItem.module.css' export interface MessageItemProps { - node: UserMessageNode | SteeringMessageNode | ContextMessageNode | CompactionSummaryNode | ModelRetryNode | UnknownSurfaceNode + node: + | UserMessageNode + | SteeringMessageNode + | ContextMessageNode + | CompactionSummaryNode + | ModelRetryNode + | TurnErrorNode + | UnknownSurfaceNode retryActive?: boolean /** Fork the session through the turn containing this message (user-bubble branch action). */ onFork?: (seq: number) => void @@ -109,6 +117,24 @@ function ModelRetryItem({ node, active, t }: { ) } + +/** Persistent, turn-positioned feedback for a terminal failure. */ +function TurnErrorItem({ node, t }: { + node: TurnErrorNode + t: ChatViewSlotProps['t'] +}) { + return ( +
+ +
+ {t('message.turnError')} + {node.message} +
+ {node.code !== undefined && {node.code}} +
+ ) +} + /** * Display projection of reference forms in a user bubble (free geometry — no * textarea alignment constraint here); everything else stays plain text. The @@ -141,42 +167,52 @@ function projectUserText(text: string): ReactNode { return <>{parts} } +/** Right-aligned bubble shared by user and steering rows (steering has no actions). */ +function UserStyleBubble({ + content, actions, t, +}: { + content: readonly unknown[] + /** Optional IconActions (or similar) below the bubble; receives the joined text. */ + actions?: (text: string) => ReactNode + t: ChatViewSlotProps['t'] +}): ReactNode { + const { text, rest } = contentText(content) + const truncated = (total: number): string => t('json.truncated', { total }) + return ( +
+
+ {projectUserText(text)} + {rest.map((block, i) => )} +
+ {actions?.(text)} +
+ ) +} + export const MessageItem = memo(function MessageItem({ node, retryActive = false, onFork, t, }: MessageItemProps) { const truncated = (total: number): string => t('json.truncated', { total }) switch (node.kind) { - case 'user': { - const { text, rest } = contentText(node.content) + case 'user': return ( -
-
- {projectUserText(text)} - {rest.map((block, i) => )} -
- { onFork(node.seq) }} - className={css.actions} - t={t} - /> -
+ ( + { onFork(node.seq) }} + className={css.actions} + t={t} + /> + )} + /> ) - } - case 'steering': { - const { text, rest } = contentText(node.content) - return ( -
-
- {t('message.steering')} - {projectUserText(text)} - {rest.map((block, i) => )} -
-
- ) - } + case 'steering': + return case 'context': return ( @@ -185,6 +221,8 @@ export const MessageItem = memo(function MessageItem({ return case 'model-retry': return + case 'turn-error': + return default: return (
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts index b909b6e979..555a6b8e4f 100644 --- a/packages/client/ui-conversation/src/client/contract/slots.ts +++ b/packages/client/ui-conversation/src/client/contract/slots.ts @@ -3,7 +3,7 @@ import type { ReactNode, RefObject } from 'react' import type { InjectFace, MaybeSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SnapshotSelectorHook, } from '@deepseek-ai/dsh-client-ui-slots' -import type { CommandNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client' +import type { CommandNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client' import type {} from '@deepseek-ai/dsh-client-ui-layout/client' import type { ComposerKeyboard, EditSelection, InputActions, InputNotice, InputState } from '../input/contract.ts' import type { createChatStore } from '../stores.ts' @@ -244,8 +244,6 @@ export interface ConversationSessionInjected { } /** Bind the input machine's draft persistence mirror to the session store. */ bindDraftMirror: (write: (text: string) => void) => () => void - /** Select a real Session through the runtime navigation owner. */ - open: (sessionId: SessionId) => void } /** @@ -355,7 +353,6 @@ export type ConversationSessionSlotProps = & PropsRenderSlots<'conversation.view'> & PropsStore & ConversationSessionInjected - & PropsLocale<'conversation'> /** The pending approval carrier the owner dispatches into the composer chain. */ export type ApprovalWait = PendingWait<'approval'> diff --git a/packages/client/ui-conversation/src/client/input/contract.ts b/packages/client/ui-conversation/src/client/input/contract.ts index 317adc0ec5..f503381bbb 100644 --- a/packages/client/ui-conversation/src/client/input/contract.ts +++ b/packages/client/ui-conversation/src/client/input/contract.ts @@ -29,7 +29,7 @@ export interface SessionInput extends InputTarget { /** Single write path for draft text (all mutation rides machine events). */ setDraft(text: string): void /** THE complexity sink: enter adjudication, submit transaction, and the default sink live inside. */ - submit(mode?: 'queue' | 'steer'): void + submit(): void /** * Surface a notice outside the machine's own effect stream: detached * command results and business notifications render through here. @@ -60,7 +60,7 @@ export interface InputActions { /** Single public draft write path (full next draft; occurrence math via diff scan). */ setDraft(text: string): void /** Enter submission (adjudication / claim transaction / default sink inside). */ - submit(mode?: 'queue' | 'steer'): void + submit(): void } /** One surfaced notice (command results, adjudication failures). seq keys re-render of repeats. */ @@ -239,7 +239,7 @@ export type InputEvent = | { readonly type: 'paste-upgrade'; readonly attemptId: number; readonly span: TokenSpan; readonly reference: ReferenceInsert } /** Shell-observed attempt killers the machine cannot see itself (caret/selection ops, Slash interaction updates). */ | { readonly type: 'invalidate-paste' } - | { readonly type: 'enter'; readonly mode: 'queue' | 'steer' } + | { readonly type: 'enter' } | { readonly type: 'adjudicated'; readonly attempt: SubmitAttempt; readonly outcome: PickOutcome } | { readonly type: 'adjudication-failed'; readonly attempt: SubmitAttempt; readonly message: string } | { readonly type: 'submit-settled'; readonly attempt: SubmitAttempt; readonly ok: boolean; readonly outcome?: SubmitOutcome; readonly message?: string } @@ -258,5 +258,5 @@ export type InputEvent = export type InputEffect = | { readonly type: 'adjudicate'; readonly attempt: SubmitAttempt; readonly draft: string } | { readonly type: 'begin-submit'; readonly attempt: SubmitAttempt; readonly claim: CommandClaim; readonly args: string } - | { readonly type: 'default-sink'; readonly draft: string; readonly mode: 'queue' | 'steer' } + | { readonly type: 'default-sink'; readonly draft: string } | { readonly type: 'notice'; readonly level: 'info' | 'error'; readonly text: string } diff --git a/packages/client/ui-conversation/src/client/input/facade.ts b/packages/client/ui-conversation/src/client/input/facade.ts index d6b2fde80a..79a223a43e 100644 --- a/packages/client/ui-conversation/src/client/input/facade.ts +++ b/packages/client/ui-conversation/src/client/input/facade.ts @@ -39,7 +39,7 @@ export interface SessionInputDeps { /** Queue read face; overlaid onto InputState.queue (absent = empty). */ queue?: ObservableSnapshot | undefined /** The plain-message sink (send choreography / materialize fork — the hub owns it). */ - defaultSink(text: string, mode: 'queue' | 'steer'): void + defaultSink(text: string): void } /** Guard tier from the machine phase. */ @@ -68,7 +68,7 @@ export class SessionInputShell implements SessionInput { /** The public provide-channel action face (one stable identity per session — decision 20). */ readonly actions: InputActions = { setDraft: (text) => { this.setDraft(text) }, - submit: (mode) => { this.submit(mode) }, + submit: () => { this.submit() }, } // Real wall clock: the typing-run merge window must actually expire in @@ -151,10 +151,9 @@ export class SessionInputShell implements SessionInput { * from the machine; this method only feeds the event. Lock entry * (adjudicating/submitting) force-closes the transient layers: the popup * dismisses and the menu tracks frozen. - * @param mode - default-sink mode (queue appends; steer interrupts). */ - submit(mode: 'queue' | 'steer' = 'queue'): void { - this.run(this.core.dispatch({ type: 'enter', mode })) + submit(): void { + this.run(this.core.dispatch({ type: 'enter' })) const phase = this.snapshot.phase if (phase === 'adjudicating' || phase === 'submitting') { this.deps.popup?.()?.dismiss() @@ -339,7 +338,7 @@ export class SessionInputShell implements SessionInput { return } case 'default-sink': { - this.sinkSerialized(fx.draft, fx.mode) + this.sinkSerialized(fx.draft) return } default: @@ -354,10 +353,10 @@ export class SessionInputShell implements SessionInput { * send — notice + draft and chips retained, never a silent downgrade to * the clipboard text. Chip-free drafts skip the async detour. */ - private sinkSerialized(draft: string, mode: 'queue' | 'steer'): void { + private sinkSerialized(draft: string): void { const occurrences = this.core.state.occurrences if (occurrences.length === 0) { - this.deps.defaultSink(draft.trim(), mode) + this.deps.defaultSink(draft.trim()) return } const slash = this.deps.slash?.() @@ -377,7 +376,7 @@ export class SessionInputShell implements SessionInput { cursor = part.offset + 1 } out += draft.slice(cursor) - this.deps.defaultSink(out.trim(), mode) + this.deps.defaultSink(out.trim()) }, (error: unknown) => { controller.abort() diff --git a/packages/client/ui-conversation/src/client/input/hub.ts b/packages/client/ui-conversation/src/client/input/hub.ts index 7b8fa344d6..1fe2f95e7f 100644 --- a/packages/client/ui-conversation/src/client/input/hub.ts +++ b/packages/client/ui-conversation/src/client/input/hub.ts @@ -56,7 +56,7 @@ export class InputHub implements InputService { slash: () => this.controller(actx), popup: () => this.popup(actx), queue: queueReadFaceOf(session), - defaultSink: (text, mode) => { this.sink(session, text, mode) }, + defaultSink: (text) => { this.sink(session, text) }, }) this.shells.set(id, shell) // The one teardown axis: listeners, shell, and map entries all ride the @@ -123,12 +123,12 @@ export class InputHub implements InputService { * exactly one path; a failed first prompt is an ordinary prompt failure * (error strip via promptError, draft restored only while untouched). */ - private sink(session: SessionFace, text: string, mode: 'queue' | 'steer'): void { + private sink(session: SessionFace, text: string): void { if (text === '') return const shell = this.shells.get(session.sessionId) // Commit, not an editable clear: undo must not resurrect sent content. shell?.commitSend() - void session.prompt([{ type: 'text', text }], mode).then( + void session.prompt([{ type: 'text', text }], 'queue').then( (result) => { if (!result.ok && shell?.snapshot.draft === '') shell.setDraft(text) }, diff --git a/packages/client/ui-conversation/src/client/input/machine.ts b/packages/client/ui-conversation/src/client/input/machine.ts index 48f6ddd872..f32d9e11d7 100644 --- a/packages/client/ui-conversation/src/client/input/machine.ts +++ b/packages/client/ui-conversation/src/client/input/machine.ts @@ -112,7 +112,6 @@ export class InputMachine { private inflight: { readonly attempt: SubmitAttempt readonly controller: AbortController - readonly mode: 'queue' | 'steer' } | undefined private log: Transaction[] = [] private redoStack: Transaction[] = [] @@ -163,7 +162,7 @@ export class InputMachine { this.paste = undefined return [] } - case 'enter': return this.onEnter(ev.mode) + case 'enter': return this.onEnter() case 'adjudicated': return this.onAdjudicated(ev.attempt, ev.outcome) case 'adjudication-failed': return this.onAdjudicationFailed(ev.attempt, ev.message) case 'submit-settled': return this.onSubmitSettled(ev) @@ -462,18 +461,18 @@ export class InputMachine { // ---- submit plane ---- /** Mint the next SubmitAttempt and take the in-flight slot. */ - private beginAttempt(mode: 'queue' | 'steer'): SubmitAttempt { + private beginAttempt(): SubmitAttempt { const controller = new AbortController() this.seq += 1 const attempt: SubmitAttempt = { seq: this.seq, signal: controller.signal, draftSnapshot: this.draft } - this.inflight = { attempt, controller, mode } + this.inflight = { attempt, controller } return attempt } - private onEnter(mode: 'queue' | 'steer'): InputEffect[] { + private onEnter(): InputEffect[] { if (this.phase === 'adjudicating' || this.phase === 'submitting') return [] if (this.phase === 'claimed' && this.claim !== undefined) { - const attempt = this.beginAttempt(mode) + const attempt = this.beginAttempt() this.phase = 'submitting' this.paste = undefined return [{ type: 'begin-submit', attempt, claim: this.claim, args: argsAfter(this.draft, this.claim.token) }] @@ -482,11 +481,11 @@ export class InputMachine { if (trimmed === '') return [] this.paste = undefined if (trimmed.startsWith('/')) { - const attempt = this.beginAttempt(mode) + const attempt = this.beginAttempt() this.phase = 'adjudicating' return [{ type: 'adjudicate', attempt, draft: this.draft }] } - return [{ type: 'default-sink', draft: this.draft, mode }] + return [{ type: 'default-sink', draft: this.draft }] } private onAdjudicated(attempt: SubmitAttempt, outcome: Extract['outcome']): InputEffect[] { @@ -507,7 +506,7 @@ export class InputMachine { this.inflight = undefined this.phase = 'plain' return outcome === undefined - ? [{ type: 'default-sink', draft: attempt.draftSnapshot, mode: flight.mode }] + ? [{ type: 'default-sink', draft: attempt.draftSnapshot }] : [] } diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts index 9263c5d93c..1bda57660d 100644 --- a/packages/client/ui-conversation/src/client/locales.ts +++ b/packages/client/ui-conversation/src/client/locales.ts @@ -30,7 +30,6 @@ export const zh = { 'access.confirm.enable': '启用 Full access', 'hero.headline': '开始构建吧', 'hero.chooseWorkspace': '选择工作区', - 'session.hierarchy': '会话层级', 'details.title': '详情', 'details.close': '关闭详情', 'details.empty': '点击消息流中的工具行查看详情', @@ -47,7 +46,6 @@ export const zh = { 'chat.loadOlder': '加载更早', 'chat.toBottom': '回到底部', 'message.extraBlock': '附加内容块', - 'message.steering': '插话', 'message.contextInjection': '上下文注入', 'message.compaction': '上下文已压缩', 'message.compaction.expand': '点击查看压缩摘要', @@ -63,6 +61,7 @@ export const zh = { 'message.retry.status': '{label}（{retry}/{maximum}） · {seconds}s', 'message.retry.delay': '重试延迟：', 'message.retry.failure': '失败原因：', + 'message.turnError': '本轮运行失败', 'command.running': '执行中…', 'command.failed': '命令失败', 'command.done': '已完成', @@ -130,7 +129,6 @@ export const en = { 'access.confirm.enable': 'Enable Full access', 'hero.headline': 'Let\'s start building', 'hero.chooseWorkspace': 'Choose workspace', - 'session.hierarchy': 'Session hierarchy', 'details.title': 'Details', 'details.close': 'Close details', 'details.empty': 'Click a tool row in the message flow to view its details', @@ -147,7 +145,6 @@ export const en = { 'chat.loadOlder': 'Load earlier', 'chat.toBottom': 'Back to bottom', 'message.extraBlock': 'Extra content block', - 'message.steering': 'Interjection', 'message.contextInjection': 'Context injection', 'message.compaction': 'Context compacted', 'message.compaction.expand': 'View compaction summary', @@ -163,6 +160,7 @@ export const en = { 'message.retry.status': '{label} ({retry}/{maximum}) · {seconds}s', 'message.retry.delay': 'Retry delay: ', 'message.retry.failure': 'Failure reason: ', + 'message.turnError': 'This turn failed', 'command.running': 'Running…', 'command.failed': 'Command failed', 'command.done': 'Completed', diff --git a/packages/client/ui-conversation/src/client/service.ts b/packages/client/ui-conversation/src/client/service.ts index 939073d22a..9a7d8fd5bb 100644 --- a/packages/client/ui-conversation/src/client/service.ts +++ b/packages/client/ui-conversation/src/client/service.ts @@ -25,12 +25,11 @@ export interface IConversation { /** The per-session input machine registry (InputService face). */ readonly input: InputService /** - * Send a prompt into the caller scope's session. + * Send a prompt into the caller scope's session (queued turn). * @param text - prompt text, sent verbatim as one text block. - * @param mode - queue after the current turn, or steer into it. * @returns completion; business failures reject (and land in promptError). */ - send(text: string, mode: 'queue' | 'steer'): Promise + send(text: string): Promise /** * Apply one operation to a pending queue occurrence. * @param itemId - agent-owned inbox occurrence identity. @@ -39,7 +38,7 @@ export interface IConversation { */ updateQueue(itemId: QueueItemId, action: QueueAction): Promise /** - * Cancel the scoped session's in-flight turn. + * Cancel the scoped session's in-flight turn while preserving its pending Queue. * @returns completion; failures reject as in send. */ cancel(): Promise @@ -71,11 +70,10 @@ export class ConversationService extends Service implements IConversation { * session snapshot's promptError (object-layer surface); the rejection here * exists for caller choreography (the composer restores the draft on it). * @param text - prompt text, sent verbatim as one text block. - * @param mode - queue after the current turn, or steer into it. */ - async send(text: string, mode: 'queue' | 'steer'): Promise { + async send(text: string): Promise { const session = this.scopedSession('send') - const result = await session.prompt([{ type: 'text', text }], mode) + const result = await session.prompt([{ type: 'text', text }], 'queue') if (!result.ok) throw new Error(`conversation.send failed: ${result.error.code}: ${result.error.message}`) } @@ -88,7 +86,7 @@ export class ConversationService extends Service implements IConversation { } } - /** Cancel the scoped session's in-flight turn (failures land in promptError and reject, as in send). */ + /** Cancel the scoped session's in-flight turn while preserving Queue (failures land in promptError and reject, as in send). */ async cancel(): Promise { const session = this.scopedSession('cancel') const result = await session.cancel() diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css index 38e9e03d3c..1f32d844a6 100644 --- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css +++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css @@ -1,4 +1,4 @@ -/* Conversation column skeleton: header (breadcrumb row + tabs) over the view +/* Conversation column skeleton: header (session title + tabs) over the view area, composer InputBar at the bottom. Column width/squeeze is layout's; this fills its cell. Figma: Header 39:27730 (83px two-row), tabs 13px with a 3px active bar. */ @@ -23,59 +23,24 @@ display: none; } -.crumbRow { +.titleRow { display: flex; align-items: center; - justify-content: space-between; min-height: 32px; } -.crumbs { - display: flex; - align-items: center; - gap: 4px; +.sessionTitle { min-width: 0; + max-width: 100%; overflow: hidden; - white-space: nowrap; -} - -.crumbSeg { - display: inline-flex; - align-items: center; - gap: 4px; - min-width: 0; -} - -.crumbSep { - /* figma: "/" separators are 14px caption gray (75:7903), one tint lighter than crumb text. */ - color: var(--dsw-alias-label-caption); - font-size: 14px; - line-height: 20px; -} - -.crumb { - max-width: 220px; - overflow: hidden; + margin: 0; padding: 4px 8px; - border: none; - border-radius: 12px; - background: transparent; font-size: 14px; line-height: 20px; - color: var(--dsw-alias-label-tertiary); - text-overflow: ellipsis; - white-space: nowrap; - cursor: pointer; -} - -.crumb:hover:not(:disabled) { - background: var(--dsw-alias-interactive-bg-hover); -} - -.crumbCurrent { font-weight: 500; color: var(--dsw-alias-label-primary); - cursor: default; + text-overflow: ellipsis; + white-space: nowrap; } /* figma Tab_Group 34:11441: 35px strip, gap 36, pad-left 8, tabs bottom-aligned. */ diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx index c52ba0b6b3..5d8a1d36cf 100644 --- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx +++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx @@ -22,6 +22,7 @@ export function ConversationRoot({ const session = useSession(s => s) const inputState = useInput(s => s) const cwd = useSessions(s => sessionId === undefined ? undefined : s.byId[sessionId]?.cwd) + const summaryBlank = useSessions(s => sessionId === undefined ? undefined : s.byId[sessionId]?.blank) const workspaces = useWorkspaces(s => s) const [pickerOpen, setPickerOpen] = useState(false) @@ -65,8 +66,16 @@ export function ConversationRoot({ // While a session is still replaying (loading + blank) the hero/docked // choice is unknowable — render the composer hidden instead of flashing // the centered hero and snapping to the docked bar (or vice versa). + // Exemption: a session the list summary already proves blank can only + // land on the hero, so hiding would blank the column for the whole + // history round-trip (the startup auto-selection flash) for nothing. + // The exemption is deliberately open-state-wide, not loading-only: a + // summary-blank session is the hero before its open starts (`cold`) and + // after one fails (`error`) for the same reason — there is no history. const settling = sessionId !== undefined && composerPhase === 'blank' && openState === 'loading' - const hero = sessionId === undefined || (composerPhase === 'blank' && openState === 'open') + && summaryBlank !== true + const hero = sessionId === undefined + || (composerPhase === 'blank' && (openState === 'open' || summaryBlank === true)) const zone: InputZone | undefined = session === undefined || inputState === undefined ? undefined : { session, input: inputState } diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx b/packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx index 677f33f46a..6b696e9e9d 100644 --- a/packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx +++ b/packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx @@ -2,35 +2,21 @@ import { useEffect, useSyncExternalStore, type ReactNode } from 'react' import clsx from 'clsx' -import { shallowEqual } from '@deepseek-ai/dsh-client-runtime/client' -import type { SessionId, SessionListState, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client' import type { ConversationSessionSlotProps } from '../contract/slots.ts' import css from './ConversationRoot.module.css' /** Full props composed from the strict session slot contract. */ export type ConversationSessionProps = ConversationSessionSlotProps -function deriveAncestry(list: SessionListState, id: SessionId): readonly SessionSummary[] { - const chain: SessionSummary[] = [] - let cursor: SessionId | undefined = id - while (cursor !== undefined) { - const summary: SessionSummary | undefined = list.byId[cursor] - if (summary === undefined || chain.includes(summary)) break - chain.unshift(summary) - cursor = summary.parentId - } - return chain -} - export function ConversationSession({ sessionId, useSession, useSessions, useInput, inputActions, useStore, actions, - renderSlot, views, bindDraftMirror, open, wrapActiveBody, t, + renderSlot, views, bindDraftMirror, wrapActiveBody, }: ConversationSessionProps) { useSyncExternalStore(views.subscribe, views.version) const tabs = views.list() const activeId = useStore(s => s.view) ?? 'chat' const active = tabs.find(view => view.id === activeId) ?? tabs[0] - const ancestry = useSessions(s => deriveAncestry(s, sessionId), shallowEqual) + const title = useSessions(s => s.byId[sessionId]?.displayTitle ?? sessionId) const composerPhase = useSession(s => s.composerPhase) const blank = useSession(s => s.blank) const inputState = useInput(s => s) @@ -69,26 +55,8 @@ export function ConversationSession({ > {!hideChrome && ( <> -
- +
+

{title}

{tabs.length > 1 && (
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx index bc762ab7f3..9759aa130f 100644 --- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx +++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx @@ -193,7 +193,7 @@ export function InputBar({ e.preventDefault() if (e.repeat) return // held-down Enter must not machine-gun sends if (locked || machineBusy) return - inputActions.submit('queue') + inputActions.submit() } const onChange = (e: ChangeEvent): void => { @@ -291,7 +291,7 @@ export function InputBar({ return } /* v8 ignore next -- defensive: the primary button is disabled while empty||disabled, so a click cannot reach the false arm. */ - if (!empty && !disabled && !machineBusy) inputActions.submit('queue') + if (!empty && !disabled && !machineBusy) inputActions.submit() } // The Access seat: the projection-fed permission chip (renders nothing diff --git a/packages/client/ui-conversation/tests/apply-inject.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.spec.tsx index 45a944b393..cfbb0fdcbe 100644 --- a/packages/client/ui-conversation/tests/apply-inject.spec.tsx +++ b/packages/client/ui-conversation/tests/apply-inject.spec.tsx @@ -105,7 +105,7 @@ async function bench() { } const actions = info.props['inputActions'] as { setDraft: (text: string) => void - submit: (mode?: 'queue' | 'steer') => void + submit: () => void } return { state, actions } } @@ -144,25 +144,25 @@ describe('conversation slot inject surface', () => { const { state, actions } = b.inputSurface(ROOT) // Whitespace-only: the machine treats it as empty — no prompt, draft kept. actions.setDraft(' ') - actions.submit('queue') + actions.submit() expect(b.sessionFake.prompt).not.toHaveBeenCalled() expect(state.getSnapshot().draft).toBe(' ') // Success: cleared and stays cleared. actions.setDraft('hello') - actions.submit('queue') + actions.submit() expect(state.getSnapshot().draft).toBe('') await Promise.resolve() expect(b.sessionFake.prompt).toHaveBeenCalledWith([{ type: 'text', text: 'hello' }], 'queue') // Failure: restored (draft still empty when the rejection lands). b.sessionFake.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'b', details: { reason: 'b' } } }) actions.setDraft('retry me') - actions.submit('queue') + actions.submit() await vi.waitFor(() => { expect(state.getSnapshot().draft).toBe('retry me') }) // Failure landing after new typing: no clobber (restore fills empty only). b.sessionFake.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'b', details: { reason: 'b' } } }) - actions.submit('queue') + actions.submit() actions.setDraft('typed during flight') await new Promise(r => setTimeout(r, 0)) expect(state.getSnapshot().draft).toBe('typed during flight') @@ -228,12 +228,9 @@ describe('conversation slot inject surface', () => { await b.runtime.dispose() }) - it('routes navigation and workspace switching through the runtime owners, carrying the draft', async () => { + it('routes workspace switching through the runtime owner, carrying the draft', async () => { const b = await bench() - const { injected } = b.conversationSurface(ROOT) const resident = b.residentSurface(ROOT) - injected.open(ROOT) - expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [ROOT] }) // Same-session connect (the picked workspace resolves to this session): // no draft movement, plain re-open. b.runtime.workspaces.stub('connectWorkspace', () => Promise.resolve(ROOT)) @@ -241,7 +238,7 @@ describe('conversation slot inject surface', () => { actions.setDraft('carry me') void resident.selectWorkspace('workspace-1' as never) await vi.waitFor(() => { - expect(b.runtime.sessions.calls.filter(c => c.method === 'open')).toHaveLength(2) + expect(b.runtime.sessions.calls.filter(c => c.method === 'open')).toHaveLength(1) }) expect(b.runtime.workspaces.calls).toContainEqual({ method: 'connectWorkspace', args: ['workspace-1'] }) expect(state.getSnapshot().draft).toBe('carry me') diff --git a/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx b/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx index 3ddaef873e..8e66dd7541 100644 --- a/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx +++ b/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx @@ -20,7 +20,7 @@ * suite only proves the assembled wiring. */ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' -import { cleanup, fireEvent, waitFor, within } from '@testing-library/react' +import { cleanup, fireEvent, waitFor } from '@testing-library/react' import { LocaleService } from '@deepseek-ai/dsh-client-locale/client' import type { ISession, SessionId, TodoItem, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client' import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots' @@ -256,16 +256,14 @@ describe('prompt rejection through the assembled composer', () => { }) describe('title projection across assembled surfaces', () => { - it('one summary update re-labels the breadcrumb and document.title consumers together', async () => { + it('one summary update re-labels the current-session heading', async () => { const runtime = await bench([]) const view = runtime.renderRoot() - // The strict session header breadcrumb reads useSessions ancestry. - const crumb = within(view.container.querySelector('[aria-label="会话层级"]') as HTMLElement) - expect(crumb.getByText('S')).toBeTruthy() + expect(view.getByRole('heading', { name: 'S', level: 1 })).toBeTruthy() await runtime.sessions.updateSummary(SID, { displayTitle: '修订标题', title: '修订标题' }) - await waitFor(() => { expect(crumb.getByText('修订标题')).toBeTruthy() }) - expect(crumb.queryByText('S')).toBeNull() + await waitFor(() => { expect(view.getByRole('heading', { name: '修订标题', level: 1 })).toBeTruthy() }) + expect(view.queryByRole('heading', { name: 'S', level: 1 })).toBeNull() await runtime.dispose() }) }) diff --git a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx index 9bc17bff67..a829f6f04a 100644 --- a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx +++ b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx @@ -102,7 +102,7 @@ describe('MessageItem arms', () => { fireEvent.click(screen.getByRole('button', { name: '复制' })) }) - it('steering bubbles carry the interjection badge and non-text rest blocks, without user actions', () => { + it('steering bubbles render text and non-text rest blocks, without user actions or a badge', () => { const view = render( { } as never} />, ) - expect(view.getByText('插话')).toBeTruthy() + expect(view.queryByText('插话')).toBeNull() expect(view.getByText('steer!')).toBeTruthy() expect(view.getByText(/附加内容块/)).toBeTruthy() expect(view.queryByRole('button', { name: '复制' })).toBeNull() diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx index 09affc53e8..110ab6a991 100644 --- a/packages/client/ui-conversation/tests/chat-view.spec.tsx +++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx @@ -8,7 +8,7 @@ import { Profiler } from 'react' import { act, cleanup, fireEvent, render, within } from '@testing-library/react' import type { AssistantMessageNode, CommandNode, ConversationNode, ConversationSnapshot, - ModelRetryNode, RunningToolCall, SessionId, SessionListState, ToolResultNode, + ModelRetryNode, RunningToolCall, SessionId, SessionListState, ToolResultNode, TurnErrorNode, UserMessageNode, WorkspaceListState, } from '@deepseek-ai/dsh-client-runtime/client' import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react' @@ -75,6 +75,11 @@ const retry = (seq: number): ModelRetryNode => ({ retry: 1, maxRetries: 2, delayMs: 450, failure: { code: 'TRANSPORT', message: '连接被重置' }, }) +const turnError = (seq: number, code?: string): TurnErrorNode => ({ + kind: 'turn-error', seq, time: seq * 1_000, turn: 1, step: 0, + message: seq === 2 ? 'API key is invalid' : 'plugin exploded', + ...(code === undefined ? {} : { code }), +}) const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode => ({ kind: 'tool-result', seq, time: seq * 1_000, callId, call: { name, argsRaw: `{"command":"cmd-${callId}","description":"run ${callId}"}` }, @@ -288,6 +293,16 @@ describe('ChatView', () => { expect(within(cancelledDisclosure).getByRole('status').textContent).toContain('重试已取消') }) + it('renders terminal turn failures inline with their durable message and optional code', () => { + const h = makeHarness({ nodes: [user(1, 'try'), turnError(2, 'AUTH'), turnError(3)] }) + const view = render() + const statuses = view.getAllByRole('status') + expect(statuses.map(status => status.textContent)).toEqual([ + '本轮运行失败API key is invalidAUTH', + '本轮运行失败plugin exploded', + ]) + }) + it('the expanded row Inspect pill hands the call id to inspectCall', () => { const h = makeHarness({ nodes: [toolResult(3, 'a')], diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx index 801fcf8bf1..cf9955a85b 100644 --- a/packages/client/ui-conversation/tests/input-bar.spec.tsx +++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx @@ -133,7 +133,7 @@ describe('Enter semantics', () => { it('plain Enter submits queue mode through the machine; repeat and empty are suppressed', () => { const { textarea, sink } = bench({ draft: 'hello' }) fireEvent.keyDown(textarea, { key: 'Enter' }) - expect(sink).toHaveBeenCalledWith('hello', 'queue') + expect(sink).toHaveBeenCalledWith('hello') fireEvent.keyDown(textarea, { key: 'Enter', repeat: true }) expect(sink).toHaveBeenCalledTimes(1) const empty = bench({ draft: ' ' }) @@ -201,7 +201,7 @@ describe('running and lock semantics (queue cut 1)', () => { expect(textarea.disabled).toBe(false) // running no longer locks fireEvent.change(textarea, { target: { value: '排队消息2' } }) fireEvent.keyDown(textarea, { key: 'Enter' }) - expect(sink).toHaveBeenCalledWith('排队消息2', 'queue') + expect(sink).toHaveBeenCalledWith('排队消息2') expect(button.getAttribute('aria-label')).toBe('停止生成') fireEvent.click(button) expect(stop).toHaveBeenCalledTimes(1) @@ -217,7 +217,7 @@ describe('running and lock semantics (queue cut 1)', () => { it('idle primary sends and disables on empty draft', () => { const { button, sink } = bench({ draft: 'go' }) fireEvent.click(button) - expect(sink).toHaveBeenCalledWith('go', 'queue') + expect(sink).toHaveBeenCalledWith('go') const empty = bench() expect(empty.button.disabled).toBe(true) }) @@ -357,7 +357,7 @@ describe('machine pending lock', () => { }, { start: 0, end: 6, draftRev: shell.snapshot.draftRev }, ) - shell.submit('queue') + shell.submit() }) expect(shell.snapshot.phase).toBe('submitting') const textarea = view.container.querySelector('textarea')! diff --git a/packages/client/ui-conversation/tests/input-machine.spec.ts b/packages/client/ui-conversation/tests/input-machine.spec.ts index 9ce23c4a10..510cb28076 100644 --- a/packages/client/ui-conversation/tests/input-machine.spec.ts +++ b/packages/client/ui-conversation/tests/input-machine.spec.ts @@ -40,9 +40,9 @@ function effectAt( } /** Drive plain → adjudicating and hand back the minted attempt. */ -function enterAdjudicating(m: InputMachine, draft: string, mode: 'queue' | 'steer' = 'queue'): SubmitAttempt { +function enterAdjudicating(m: InputMachine, draft: string): SubmitAttempt { m.dispatch({ type: 'draft-changed', draft }) - const fx = m.dispatch({ type: 'enter', mode }) + const fx = m.dispatch({ type: 'enter' }) return effectAt(fx, 0, 'adjudicate').attempt } @@ -52,7 +52,7 @@ function enterSubmitting(m: InputMachine, name: string, args: string): { attempt m.dispatch({ type: 'draft-changed', draft: `/${name.slice(0, 2)}` }) m.dispatch({ type: 'begin-command', claim, span: spanOf(m, 0, m.state.draft.length) }) m.dispatch({ type: 'draft-changed', draft: claim.token + args }) - const fx = m.dispatch({ type: 'enter', mode: 'queue' }) + const fx = m.dispatch({ type: 'enter' }) return { attempt: effectAt(fx, 0, 'begin-submit').attempt, claim } } @@ -63,24 +63,24 @@ function staleAttempt(): SubmitAttempt { describe('input-machine: plain × enter', () => { it('empty and whitespace-only drafts produce nothing', () => { const m = new InputMachine() - expect(m.dispatch({ type: 'enter', mode: 'queue' })).toEqual([]) + expect(m.dispatch({ type: 'enter' })).toEqual([]) m.dispatch({ type: 'draft-changed', draft: ' \n ' }) - expect(m.dispatch({ type: 'enter', mode: 'queue' })).toEqual([]) + expect(m.dispatch({ type: 'enter' })).toEqual([]) expect(m.state.phase).toBe('plain') }) - it('non-command text falls to the default sink with the given mode', () => { + it('non-command text falls to the default sink', () => { const m = new InputMachine() m.dispatch({ type: 'draft-changed', draft: 'hello world' }) - expect(m.dispatch({ type: 'enter', mode: 'steer' })) - .toEqual([{ type: 'default-sink', draft: 'hello world', mode: 'steer' }]) + expect(m.dispatch({ type: 'enter' })) + .toEqual([{ type: 'default-sink', draft: 'hello world' }]) expect(m.state.phase).toBe('plain') }) it('leading "/" enters adjudicating with a minted attempt carrying the draft snapshot', () => { const m = new InputMachine() m.dispatch({ type: 'draft-changed', draft: '/goal x' }) - const fx = m.dispatch({ type: 'enter', mode: 'queue' }) + const fx = m.dispatch({ type: 'enter' }) const eff = effectAt(fx, 0, 'adjudicate') expect(eff.draft).toBe('/goal x') expect(eff.attempt.draftSnapshot).toBe('/goal x') @@ -91,14 +91,14 @@ describe('input-machine: plain × enter', () => { it('leading is judged after trim including newlines', () => { const m = new InputMachine() m.dispatch({ type: 'draft-changed', draft: '\n\n/goal x' }) - expect(m.dispatch({ type: 'enter', mode: 'queue' })[0]?.type).toBe('adjudicate') + expect(m.dispatch({ type: 'enter' })[0]?.type).toBe('adjudicate') }) it('a non-whitespace prefix before "/" is not leading — default sink', () => { const m = new InputMachine() m.dispatch({ type: 'draft-changed', draft: '第一行\n/goal x' }) - expect(m.dispatch({ type: 'enter', mode: 'queue' })) - .toEqual([{ type: 'default-sink', draft: '第一行\n/goal x', mode: 'queue' }]) + expect(m.dispatch({ type: 'enter' })) + .toEqual([{ type: 'default-sink', draft: '第一行\n/goal x' }]) }) }) @@ -124,11 +124,11 @@ describe('input-machine: adjudication outcomes', () => { expect(effectAt(b.dispatch({ type: 'adjudicated', attempt: attemptB, outcome: { claim: claimOf('goal') } }), 0, 'begin-submit').args).toBe('x') }) - it('undefined outcome falls back to the default sink preserving the enter mode', () => { + it('undefined outcome falls back to the default sink', () => { const m = new InputMachine() - const attempt = enterAdjudicating(m, '/unknown thing', 'steer') + const attempt = enterAdjudicating(m, '/unknown thing') expect(m.dispatch({ type: 'adjudicated', attempt, outcome: undefined })) - .toEqual([{ type: 'default-sink', draft: '/unknown thing', mode: 'steer' }]) + .toEqual([{ type: 'default-sink', draft: '/unknown thing' }]) expect(m.state.phase).toBe('plain') }) @@ -152,7 +152,7 @@ describe('input-machine: adjudication outcomes', () => { it('enter is a no-op while adjudicating (pending lock)', () => { const m = new InputMachine() enterAdjudicating(m, '/goal x') - expect(m.dispatch({ type: 'enter', mode: 'queue' })).toEqual([]) + expect(m.dispatch({ type: 'enter' })).toEqual([]) expect(m.state.phase).toBe('adjudicating') }) @@ -587,7 +587,7 @@ describe('input-machine: paste plane', () => { const b = new InputMachine() b.dispatch({ type: 'paste-begin', text: 'plain text', selection: { start: 0, end: 0 } }) - b.dispatch({ type: 'enter', mode: 'queue' }) + b.dispatch({ type: 'enter' }) expect(b.state.paste).toBeUndefined() }) @@ -755,7 +755,7 @@ describe('input-machine: submitting transaction', () => { it('enter and begin-command are locked; draft-changed is recorded without leaving submitting', () => { const m = new InputMachine() enterSubmitting(m, 'goal', 'x') - expect(m.dispatch({ type: 'enter', mode: 'queue' })).toEqual([]) + expect(m.dispatch({ type: 'enter' })).toEqual([]) expect(m.dispatch({ type: 'draft-changed', draft: '/goal y' })).toEqual([]) expect(m.state).toMatchObject({ phase: 'submitting', draft: '/goal y' }) }) @@ -768,7 +768,7 @@ describe('input-machine: submitting transaction', () => { m.dispatch({ type: 'draft-changed', draft: '/go', editRange: { start: 0, end: 1, insertedLength: 0 } }) m.dispatch({ type: 'begin-command', claim: claimOf('goal'), span: spanOf(m, 0, 3) }) m.dispatch({ type: 'draft-changed', draft: '/goal go' }) - const attempt = effectAt(m.dispatch({ type: 'enter', mode: 'queue' }), 0, 'begin-submit').attempt + const attempt = effectAt(m.dispatch({ type: 'enter' }), 0, 'begin-submit').attempt const fx = m.dispatch({ type: 'submit-settled', attempt, ok: true, outcome: { kind: 'success', text: 'goal set' } }) expect(fx).toEqual([{ type: 'notice', level: 'info', text: 'goal set' }]) expect(m.state).toMatchObject({ phase: 'plain', draft: '', occurrences: [] }) @@ -809,7 +809,7 @@ describe('input-machine: submitting transaction', () => { const m = new InputMachine() const { attempt: first } = enterSubmitting(m, 'goal', 'x') m.dispatch({ type: 'submit-settled', attempt: first, ok: false, message: 'retry' }) - const second = effectAt(m.dispatch({ type: 'enter', mode: 'queue' }), 0, 'begin-submit').attempt + const second = effectAt(m.dispatch({ type: 'enter' }), 0, 'begin-submit').attempt expect(second.seq).not.toBe(first.seq) expect(m.dispatch({ type: 'submit-settled', attempt: first, ok: true })).toEqual([]) expect(m.state.phase).toBe('submitting') diff --git a/packages/client/ui-conversation/tests/input-matrix.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.spec.tsx index e8cf82a845..b406b58da5 100644 --- a/packages/client/ui-conversation/tests/input-matrix.spec.tsx +++ b/packages/client/ui-conversation/tests/input-matrix.spec.tsx @@ -87,7 +87,7 @@ describe('matrix row: plain', () => { fireEvent.change(textarea, { target: { value: '普通消息' } }) expect(shell.snapshot.claim).toBeUndefined() fireEvent.keyDown(textarea, { key: 'Enter' }) - expect(sink).toHaveBeenCalledWith('普通消息', 'queue') + expect(sink).toHaveBeenCalledWith('普通消息') expect(shell.snapshot.phase).toBe('plain') }) }) @@ -186,7 +186,7 @@ describe('matrix row: locked (session disabled)', () => { expect((textarea).disabled).toBe(false) fireEvent.change(textarea, { target: { value: '排队' } }) fireEvent.keyDown(textarea, { key: 'Enter' }) - expect(sink).toHaveBeenCalledWith('排队', 'queue') + expect(sink).toHaveBeenCalledWith('排队') }) }) diff --git a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx index 797dc6e4a6..2498ed93a4 100644 --- a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx +++ b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx @@ -234,7 +234,7 @@ describe('scenario D: execute-kind /compact', () => { act(() => { b2.shell.setDraft('/compact 现在') }) fireEvent.keyDown(b2.textarea, { key: 'Enter' }) // execute with trailing → matchEnter answers undefined → default sink. - await vi.waitFor(() => { expect(b2.sink).toHaveBeenCalledWith('/compact 现在', 'queue') }) + await vi.waitFor(() => { expect(b2.sink).toHaveBeenCalledWith('/compact 现在') }) expect(b2.executed).toHaveLength(0) }) }) @@ -288,7 +288,7 @@ describe('scenario I: unknown /xyz + enter', () => { const b = await bench() act(() => { b.shell.setDraft('/xyz 干点啥') }) fireEvent.keyDown(b.textarea, { key: 'Enter' }) - await vi.waitFor(() => { expect(b.sink).toHaveBeenCalledWith('/xyz 干点啥', 'queue') }) + await vi.waitFor(() => { expect(b.sink).toHaveBeenCalledWith('/xyz 干点啥') }) expect(b.shell.snapshot.phase).toBe('plain') expect(b.execute).not.toHaveBeenCalled() }) diff --git a/packages/client/ui-conversation/tests/service-orchestration.spec.ts b/packages/client/ui-conversation/tests/service-orchestration.spec.ts index 209cdee212..41a21b86e3 100644 --- a/packages/client/ui-conversation/tests/service-orchestration.spec.ts +++ b/packages/client/ui-conversation/tests/service-orchestration.spec.ts @@ -33,11 +33,11 @@ async function bench() { describe('ConversationService', () => { it('routes operations through the public Session binding', async () => { const b = await bench() - await b.scoped.send('hello', 'steer') + await b.scoped.send('hello') await b.scoped.updateQueue('item-1' as never, { kind: 'remove' }) await b.scoped.cancel() await b.scoped.loadOlder() - expect(b.prompt).toHaveBeenCalledWith([{ type: 'text', text: 'hello' }], 'steer') + expect(b.prompt).toHaveBeenCalledWith([{ type: 'text', text: 'hello' }], 'queue') expect(b.updateQueue).toHaveBeenCalledWith('item-1', { kind: 'remove' }) expect(b.cancel).toHaveBeenCalledOnce() expect(b.loadOlder).toHaveBeenCalledOnce() @@ -47,7 +47,7 @@ describe('ConversationService', () => { it('folds Session business failures into callback rejections', async () => { const b = await bench() b.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'busy', details: {} } } as never) - await expect(b.scoped.send('x', 'queue')).rejects.toThrow('conversation.send failed: agent-busy: busy') + await expect(b.scoped.send('x')).rejects.toThrow('conversation.send failed: agent-busy: busy') b.cancel.mockResolvedValueOnce({ ok: false, error: { code: 'internal', message: 'nope', details: {} } } as never) await expect(b.scoped.cancel()).rejects.toThrow('conversation.cancel failed: internal: nope') await b.runtime.dispose() @@ -55,9 +55,9 @@ describe('ConversationService', () => { it('fails loudly from the root scope, on an unbound session, or without SessionsService', async () => { const b = await bench() - await expect(b.root.send('x', 'queue')).rejects.toThrow(/requires a session scope/) + await expect(b.root.send('x')).rejects.toThrow(/requires a session scope/) await b.runtime.sessions.remove('s1') - await expect(b.scoped.send('x', 'queue')).rejects.toThrow(/resolved no binding/) + await expect(b.scoped.send('x')).rejects.toThrow(/resolved no binding/) await b.runtime.dispose() // No SessionsService at all: a bare context (the runtime always provides one). const bare = new Context() @@ -65,6 +65,6 @@ describe('ConversationService', () => { input: new InputHub(bare), }).await() const orphan = bare.get('conversation') as ConversationService - await expect(orphan.send('x', 'queue')).rejects.toThrow(/sessions service unavailable/) + await expect(orphan.send('x')).rejects.toThrow(/sessions service unavailable/) }) }) diff --git a/packages/client/ui-conversation/tests/skeleton.spec.tsx b/packages/client/ui-conversation/tests/skeleton.spec.tsx index eeb8404fd5..35afd759f1 100644 --- a/packages/client/ui-conversation/tests/skeleton.spec.tsx +++ b/packages/client/ui-conversation/tests/skeleton.spec.tsx @@ -80,16 +80,25 @@ function mount( snapshot: ConversationSnapshot, workspaceRows: WorkspaceView[] = [{ ...workspace('one'), sessionIds: [SID] }], retargetWorkspace = vi.fn(async (_workspaceId: WorkspaceId) => {}), - /** When true, mimic overlay:true chain siblings (hidden fallback + takeover). */ - overlayTakeover = false, + options: { + /** When true, mimic overlay:true chain siblings (hidden fallback + takeover). */ + overlayTakeover?: boolean + /** The session list summary's `blank` flag — independent of the snapshot's. */ + summaryBlank?: boolean + /** Drop the session's summary row entirely (a session the list has not caught up with). */ + omitSummaryRow?: boolean + } = {}, ) { const root = sid('root') + const rootRow = { id: root, displayTitle: 'Root', running: false, waitingApproval: false, blank: false, updatedAt: 1 } + const childRow = { + id: SID, displayTitle: 'Child', parentId: root, cwd: '/projects/one', + running: false, waitingApproval: false, blank: options.summaryBlank ?? false, updatedAt: 2, + } + const listed = options.omitSummaryRow !== true const sessions = createSnapshotStore({ - ids: [root, SID], - byId: { - [root]: { id: root, displayTitle: 'Root', running: false, waitingApproval: false, blank: false, updatedAt: 1 }, - [SID]: { id: SID, displayTitle: 'Child', parentId: root, cwd: '/projects/one', running: false, waitingApproval: false, blank: false, updatedAt: 2 }, - }, + ids: listed ? [root, SID] : [root], + byId: { [root]: rootRow, ...listed && { [SID]: childRow } }, current: SID, phase: 'ready', }) @@ -102,7 +111,6 @@ function mount( const useInput = bindSnapshotSelector(wiring.state) const inputActions = wiring.actions const stop = vi.fn() - const open = vi.fn() const slotCalls: string[] = [] let pickerOwner: unknown const renderSlot = ((key: string, owner: object, opts?: { only?: string }) => { @@ -131,8 +139,6 @@ function mount( version: () => 1, }} bindDraftMirror={write => wiring.bindMirror(write)} - open={open} - t={t} {...owner} /> ) @@ -167,7 +173,7 @@ function mount( return
}) as ConversationRootProps['renderSlot'] const renderSlotChain = ((_key, _owner, opts) => ( - overlayTakeover + options.overlayTakeover === true ? ( <>
@@ -194,7 +200,7 @@ function mount( } const view = render() return { - view, chat, sink, open, retargetWorkspace, session, slotCalls, + view, chat, sink, retargetWorkspace, session, slotCalls, pickerOwner: () => pickerOwner, rerender: () => { view.rerender() }, } @@ -208,9 +214,9 @@ describe('ConversationRoot resident composer', () => { fireEvent.change(box, { target: { value: 'ordinary revised' } }) expect(b.chat.store.getSnapshot().draft).toBe('ordinary revised') fireEvent.keyDown(box, { key: 'Enter' }) - expect(b.sink).toHaveBeenCalledWith('ordinary revised', 'queue') - fireEvent.click(b.view.getByRole('button', { name: 'Root' })) - expect(b.open).toHaveBeenCalledWith(sid('root')) + expect(b.sink).toHaveBeenCalledWith('ordinary revised') + expect(b.view.getByRole('heading', { name: 'Child', level: 1 })).toBeTruthy() + expect(b.view.queryByText('Root')).toBeNull() }) it('active phase: fixed header outside the scrollport; sticky composer seat inside it', () => { @@ -229,7 +235,7 @@ describe('ConversationRoot resident composer', () => { }) it('sticky composer seat wraps the whole overlay chain, not only the fallback stack', () => { - const b = mount(conversationSnapshot(), undefined, undefined, true) + const b = mount(conversationSnapshot(), undefined, undefined, { overlayTakeover: true }) const seat = b.view.container.querySelector('[data-composer-seat]') const takeover = b.view.getByTestId('composer-takeover') const fallback = b.view.container.querySelector('[data-chain-overlay-fallback="conversation.composer"]') @@ -270,6 +276,39 @@ describe('ConversationRoot resident composer', () => { expect(b.view.getByText('Selected Folder')).toBeTruthy() }) + it('settling phase: a summary that does not prove the session blank hides the composer while it opens', () => { + const b = mount(conversationSnapshot({ composerPhase: 'blank', blank: true, openState: 'loading' })) + const root = b.view.container.querySelector('[data-phase]') + expect(root?.getAttribute('data-phase')).toBe('settling') + expect(b.view.queryByText('开始构建吧')).toBeNull() + }) + + it('settling phase: a session the list has no row for settles conservatively', () => { + const b = mount( + conversationSnapshot({ composerPhase: 'blank', blank: true, openState: 'loading' }), + undefined, + undefined, + { omitSummaryRow: true }, + ) + const root = b.view.container.querySelector('[data-phase]') + expect(root?.getAttribute('data-phase')).toBe('settling') + }) + + it('startup auto-selection: a summary-proven blank session opens straight into the hero', () => { + const b = mount( + conversationSnapshot({ composerPhase: 'blank', blank: true, openState: 'loading' }), + undefined, + undefined, + { summaryBlank: true }, + ) + // The summary already proves the outcome, so the settling hide would only + // blank the column for the history round-trip. + const root = b.view.container.querySelector('[data-phase]') + expect(root?.getAttribute('data-phase')).toBe('hero') + expect(b.view.getByText('开始构建吧')).toBeTruthy() + expect(b.view.getByRole('textbox')).toBeTruthy() + }) + it('same textarea DOM node survives the hero → active flip into the sticky scrollport', () => { const b = mount(conversationSnapshot({ composerPhase: 'blank', blank: true })) const before = b.view.getByRole('textbox') diff --git a/packages/client/ui-trajectory/README.i18n.yaml b/packages/client/ui-trajectory/README.i18n.yaml index 51ff03c8af..41c954adc0 100644 --- a/packages/client/ui-trajectory/README.i18n.yaml +++ b/packages/client/ui-trajectory/README.i18n.yaml @@ -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 packages/client/ui-trajectory/README.md -README.md: b9c8b849b3454fe46e1fc37713d9d3b9449734cf -README.zh.md: 6ddc32f2f27c93f8ccc80b3d9b31d56d3cf4dd94 +README.md: a65c11aed9dd74f9b0b60795441f876c1d64b3ad +README.zh.md: 6e25d24c6b65673b3d003e624b6e0727be60c0e1 diff --git a/packages/client/ui-trajectory/README.md b/packages/client/ui-trajectory/README.md index b9c8b849b3..a65c11aed9 100644 --- a/packages/client/ui-trajectory/README.md +++ b/packages/client/ui-trajectory/README.md @@ -2,7 +2,7 @@ English | [中文](README.zh.md) -Trajectory renders a turn-aware event ledger with selectable User, Assistant, Tool, and nested Subtool records. Thick rules mark Turn boundaries, compact inline markers identify Steps, and the main ledger keeps only index, event, and content; selection opens a local inspector for token usage, duration, Input, Output, and Timing. A fixed Overview above the ledger projects real record start/duration timing from left to right; dragging an interval focuses the ledger on every record active at any point in that inclusive range, while clearing the selection restores the full branch. The runtime's independent history source supplies raw context lineage and projects cancellation-frozen Assistant and Tool records, so Trajectory neither reads nor changes the Chat conversation snapshot. The package remains a pure-consumer plugin (registers one view tab into the conversation's `'conversation.view'` slot ring, provides no service, declares no Context merge). Contract: api-contracts v3 §8. +Trajectory renders a turn-aware event ledger with selectable User, Assistant, Tool, and nested Subtool records. Thick rules mark Turn boundaries, compact inline markers identify Steps, and the main ledger keeps only index, event, and content; selection opens a local inspector for token usage, duration, Input, Output, and Timing. A standalone compaction request appears chronologically in its own `Between turns` section, while a numbered compaction remains inside its owning turn. A fixed Overview above the ledger projects real record start/duration timing from left to right; dragging an interval focuses the ledger on every record active at any point in that inclusive range, while clearing the selection restores the full branch. The runtime's independent history source supplies raw context lineage and projects cancellation-frozen Assistant and Tool records, so Trajectory neither reads nor changes the Chat conversation snapshot. The package remains a pure-consumer plugin (registers one view tab into the conversation's `'conversation.view'` slot ring, provides no service, declares no Context merge). Contract: api-contracts v3 §8. ## Model Experience diff --git a/packages/client/ui-trajectory/README.zh.md b/packages/client/ui-trajectory/README.zh.md index 6ddc32f2f2..6e25d24c6b 100644 --- a/packages/client/ui-trajectory/README.zh.md +++ b/packages/client/ui-trajectory/README.zh.md @@ -2,7 +2,7 @@ [English](README.md) | 中文 -Trajectory 渲染按轮次组织的事件记录表，其中可选择用户、助手、工具和嵌套子工具记录。较粗的分割线标示轮次边界，紧凑的行内标记标识步骤，主记录表仅保留索引、事件和内容；选择记录则会打开局部检查器，查看 token 用量、耗时、输入、输出和计时。固定在记录表上方的 Overview 区域从左到右投影记录的真实开始时间与耗时；拖选一个区间会将记录表聚焦到活动区间与该闭区间有重叠的所有记录，清除选择则恢复完整分支。运行时的独立历史数据源提供原始上下文谱系，并投影因取消而冻结的助手和工具记录，因此 Trajectory 既不读取也不改变 Chat 会话快照。该包（package）保持为纯消费方插件（向会话的 `'conversation.view'` slot 环注册一个视图标签页，不提供服务，也不声明 Context 合并）。契约：api-contracts v3 §8。 +Trajectory 渲染按轮次组织的事件记录表，其中可选择用户、助手、工具和嵌套子工具记录。较粗的分割线标示轮次边界，紧凑的行内标记标识步骤，主记录表仅保留索引、事件和内容；选择记录则会打开局部检查器，查看 token 用量、耗时、输入、输出和计时。独立运行的压缩（compaction）请求会按时间顺序显示在自己的 `Between turns` 区段中，而带数值所有者的压缩仍位于其所属轮次内。固定在记录表上方的 Overview 区域从左到右投影记录的真实开始时间与耗时；拖选一个区间会将记录表聚焦到活动区间与该闭区间有重叠的所有记录，清除选择则恢复完整分支。运行时的独立历史数据源提供原始上下文谱系，并投影因取消而冻结的助手和工具记录，因此 Trajectory 既不读取也不改变 Chat 会话快照。该包（package）保持为纯消费方插件（向会话的 `'conversation.view'` slot 环注册一个视图标签页，不提供服务，也不声明 Context 合并）。契约：api-contracts v3 §8。 ## 模型体验 diff --git a/packages/client/ui-trajectory/package.json b/packages/client/ui-trajectory/package.json index fc853d19d1..8da6559866 100644 --- a/packages/client/ui-trajectory/package.json +++ b/packages/client/ui-trajectory/package.json @@ -24,6 +24,7 @@ }, "dshClient": { "inject": [ + "@deepseek-ai/dsh-client-runtime", "@deepseek-ai/dsh-client-ui-conversation" ], "platform": "web" @@ -37,6 +38,7 @@ "diff": "^9.0.0" }, "peerDependencies": { + "@deepseek-ai/dsh-client-runtime": "^0.0.1", "@deepseek-ai/dsh-invariants": "^0.0.1", "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1", "cordis": "^4.0.0-rc.7", diff --git a/packages/client/ui-trajectory/src/client/TrajectoryTable.module.css b/packages/client/ui-trajectory/src/client/TrajectoryTable.module.css index c7b7948845..86cc8dfd8b 100644 --- a/packages/client/ui-trajectory/src/client/TrajectoryTable.module.css +++ b/packages/client/ui-trajectory/src/client/TrajectoryTable.module.css @@ -321,6 +321,13 @@ width: 76px; } +.kindSlot :global([role='tooltip']) { + border: 1px solid var(--dsw-alias-border-l2); + background: var(--dsw-alias-bg-layer-2); + box-shadow: var(--dsw-shadow-lv2); + color: var(--dsw-alias-label-primary); +} + .content { padding-left: 4px !important; color: var(--dsw-alias-label-primary); @@ -828,6 +835,7 @@ flex: 1; min-height: 0; overflow: auto; + scrollbar-gutter: stable; } .detailBodySummary { @@ -989,7 +997,7 @@ margin: 0; padding: 0 0 3px 14px; color: var(--dsw-alias-label-secondary); - background: var(--dsw-alias-bg-base); + background: var(--dsw-alias-bg-layer-1); font: var(--dsw-font-xs-strong-13); user-select: none; } diff --git a/packages/client/ui-trajectory/src/client/TrajectoryTable.tsx b/packages/client/ui-trajectory/src/client/TrajectoryTable.tsx index 5a78e95a40..4f88bf0bca 100644 --- a/packages/client/ui-trajectory/src/client/TrajectoryTable.tsx +++ b/packages/client/ui-trajectory/src/client/TrajectoryTable.tsx @@ -104,7 +104,8 @@ const KIND_ICON: Record = { } interface TableRecord { - turn: number + turn: number | null + section: number group: string groupStart: boolean turnStart: boolean @@ -146,7 +147,8 @@ interface ToolCallTextParts { } interface SelectedRequest { - turn: number + turn: number | null + section: number number: number group: string } @@ -320,15 +322,12 @@ export interface TrajectoryTableProps { onInspectApplied?: (() => void) | undefined } -/** One request identity paired with its session-global number. */ -export interface TrajectoryRequestNumber { +/** Request-inspector fields shared by ordinary generation and compaction. */ +interface TrajectoryRequestNumberBase { /** Request anchor event sequence; absent for the currently streaming ordinary request. */ seq?: number - turn: number - step: number group: string number: number - purpose?: 'compaction' status?: 'complete' | 'running' | 'error' startedAt?: number completedAt?: number | null @@ -344,6 +343,20 @@ export interface TrajectoryRequestNumber { cumulativeUsage?: TrajectoryUsage } +/** One purpose-discriminated request identity paired with its session-global number. */ +export type TrajectoryRequestNumber = TrajectoryRequestNumberBase & ( + | { + purpose?: 'assistant' + turn: number + step: number + } + | { + purpose: 'compaction' + turn: number | null + step: 0 + } +) + /** Disjoint provider token buckets for one request or a session prefix. */ export interface TrajectoryUsage { input?: number @@ -354,17 +367,18 @@ export interface TrajectoryUsage { } function flattenRecords(turns: readonly TrajectoryTurnModel[]): TableRecord[] { - return turns.flatMap((turn) => { - let firstInTurn = true + return turns.flatMap((turn, section) => { + let firstInSection = true const records = turn.groups.flatMap((group) => { return group.cells.map((cell, index) => { - const turnStart = firstInTurn + const turnStart = firstInSection && cell.requestOnly !== true && cell.kind !== 'system' - && cell.kind !== 'compacted' - if (turnStart) firstInTurn = false + && (cell.kind !== 'compacted' || turn.turn === null) + if (turnStart) firstInSection = false return { turn: turn.turn, + section, group: group.title, groupStart: index === 0, turnStart, @@ -388,18 +402,18 @@ function filterRecords( record.cell.requestOnly !== true && matches.has(record.cell.index), ) .map(record => ({ ...record, groupStart: false, turnStart: false, turnEnd: false })) - const startedTurns = new Set() + const startedSections = new Set() for (const [index, record] of filtered.entries()) { const previous = filtered[index - 1] const next = filtered[index + 1] record.groupStart = previous === undefined - || previous.turn !== record.turn + || previous.section !== record.section || previous.group !== record.group - record.turnStart = !startedTurns.has(record.turn) + record.turnStart = !startedSections.has(record.section) && record.cell.kind !== 'system' - && record.cell.kind !== 'compacted' - if (record.turnStart) startedTurns.add(record.turn) - record.turnEnd = next === undefined || next.turn !== record.turn + && (record.cell.kind !== 'compacted' || record.turn === null) + if (record.turnStart) startedSections.add(record.section) + record.turnEnd = next === undefined || next.section !== record.section } return filtered } @@ -410,10 +424,14 @@ function requestStep(group: string): number | undefined { return Number.isInteger(value) && value > 0 ? value : undefined } -function requestKey(turn: number, group: string): string { +function requestKey(turn: number | null, group: string): string { return `${turn}\u0000${group}` } +function sectionLabel(turn: number | null): string { + return turn === null ? 'Between turns' : `Turn ${turn}` +} + function indexRequestNumbers( records: readonly TableRecord[], sessionNumbers: readonly TrajectoryRequestNumber[] | undefined, @@ -455,12 +473,13 @@ function collapseTurnRecords( if (collapsedTurns.size === 0) return [...records] const recordsByTurn = new Map() for (const record of records) { + if (record.turn === null) continue const turnRecords = recordsByTurn.get(record.turn) ?? [] turnRecords.push(record) recordsByTurn.set(record.turn, turnRecords) } return records.flatMap((record) => { - if (!collapsedTurns.has(record.turn)) return [record] + if (record.turn === null || !collapsedTurns.has(record.turn)) return [record] const turnRecords = recordsByTurn.get(record.turn) ?? [record] if (record.cell.requestOnly === true || record.cell.kind === 'system') return [record] const contentRecords = turnRecords.filter(candidate => @@ -1537,6 +1556,7 @@ export function TrajectoryTable({ ? [] : allRecords.filter(record => record.turn === selectedRequest.turn + && record.section === selectedRequest.section && record.group === selectedRequest.group, ) const selectedRequestAssistant = selectedRequestRecords.find( @@ -1588,7 +1608,8 @@ export function TrajectoryTable({ const selectedRequestCumulativeUsage = selectedRequestInfo?.cumulativeUsage ?? selectedRequestUsage const selectedRequestOptions = selectedRequestInfo?.requestConfig - const activeTurn = selectedRequest?.turn ?? selected?.turn + const activeTurn = selectedRequest === null ? selected?.turn : selectedRequest.turn + const activeSection = selectedRequest === null ? selected?.section : selectedRequest.section const selectedTabs = selectedRequest !== null ? REQUEST_TABS.filter(tab => tab.id !== 'options' || selectedRequestOptions !== undefined) : selected === undefined ? [] : detailTabs(selected) @@ -1604,6 +1625,7 @@ export function TrajectoryTable({ selected !== undefined && selectedAssistantRequest !== undefined ? { turn: selected.turn, + section: selected.section, number: selectedAssistantRequest, group: selected.group, } @@ -1664,7 +1686,7 @@ export function TrajectoryTable({ const openRecordSummary = (target: TableRecord) => { const targetAt = allRecords.findIndex(record => record.cell.index === target.cell.index) - if (collapsedTurns.has(target.turn)) onToggleTurn(target.turn) + if (target.turn !== null && collapsedTurns.has(target.turn)) onToggleTurn(target.turn) if (target.cell.kind === 'tool' || target.cell.kind === 'subtool') { for (let i = targetAt - 1; i >= 0; i--) { const candidate = allRecords[i] @@ -1739,7 +1761,7 @@ export function TrajectoryTable({ && record.cell.index === allRecords[0]?.cell.index const request = record.groupStart && !isCollapsedSummary - && !collapsedTurns.has(record.turn) + && (record.turn === null || !collapsedTurns.has(record.turn)) ? requestNumbers.get(requestKey(record.turn, record.group)) : undefined const requestInfo = request === undefined @@ -1750,7 +1772,11 @@ export function TrajectoryTable({ : `Request #${request}${requestInfo?.purpose === 'compaction' ? ' · Compaction' : ''}` const requestSelected = request !== undefined && selectedRequest?.turn === record.turn + && selectedRequest.section === record.section && selectedRequest.number === request + const sectionActive = record.turn === null + ? activeSection === record.section + : activeTurn === record.turn return ( { - if (record.collapsedSummaryKind === 'turn') onToggleTurn(record.turn) - else onToggleAssistant(record.cell.index) + if (record.collapsedSummaryKind === 'turn' && record.turn !== null) { + onToggleTurn(record.turn) + } else onToggleAssistant(record.cell.index) } : () => { selectRecord(record.cell.index) }} onDoubleClick={(event) => { if (isCollapsedSummary || isRequestOnly) return - if (collapsedTurns.has(record.turn)) { + if (record.turn !== null && collapsedTurns.has(record.turn)) { event.preventDefault() onToggleTurn(record.turn) return @@ -1800,6 +1827,7 @@ export function TrajectoryTable({ return } if (!record.turnStart) return + if (record.turn === null) return if (allRecords.filter(candidate => candidate.turn === record.turn && candidate.cell.requestOnly !== true @@ -1812,8 +1840,9 @@ export function TrajectoryTable({ if (event.key !== 'Enter' && event.key !== ' ') return event.preventDefault() if (isCollapsedSummary) { - if (record.collapsedSummaryKind === 'turn') onToggleTurn(record.turn) - else onToggleAssistant(record.cell.index) + if (record.collapsedSummaryKind === 'turn' && record.turn !== null) { + onToggleTurn(record.turn) + } else onToggleAssistant(record.cell.index) return } selectRecord(record.cell.index) @@ -1833,6 +1862,7 @@ export function TrajectoryTable({ event.stopPropagation() selectRequest({ turn: record.turn, + section: record.section, number: request, group: record.group, }) @@ -1840,7 +1870,9 @@ export function TrajectoryTable({ onDoubleClick={(event) => { event.stopPropagation() }} /> )} - {activeTurn === record.turn && !isInitialSystem && ( + {record.turn !== null + && activeTurn === record.turn + && !isInitialSystem && (