From 8e5c792b50fd73030591535a338664b1947d2c38 Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Thu, 30 Jul 2026 10:18:24 +0800 Subject: [PATCH 01/50] round 1: project the web transcript from append-origin events Replace the surface-ordered fold with a log-ordered human transcript: append-origin surface events at their own log positions plus one marker per landed compaction checkpoint. Command folding, the tool-call index, and the rev-keyed memo carry over unchanged. Removes foldDegraded, the padding sentinels, baseSeq, and degradedSeqs() -- they existed only to satisfy the core fold's seq === index assertion. That also closes the pagination hole A1 exposed: a page can carry a checkpoint whose shadowed range fell outside the window, and nothing resolves surfaceOp.start anymore. --- ...7-19-gui-web-client-architecture.i18n.yaml | 6 +- .../2026-07-19-gui-web-client-architecture.md | 10 +- ...26-07-19-gui-web-client-architecture.zh.md | 6 +- ...9-human-transcript-append-origin.i18n.yaml | 4 +- ...26-07-29-human-transcript-append-origin.md | 4 +- ...07-29-human-transcript-append-origin.zh.md | 4 +- ...ranscript-log-ordered-projection.i18n.yaml | 6 + ...0-web-transcript-log-ordered-projection.md | 66 +++ ...eb-transcript-log-ordered-projection.zh.md | 66 +++ apps/web/tests/seeded-history.e2e.ts | 97 +++- .../snapshots/seeded-history/ui.expected.md | 6 +- packages/client/runtime/README.i18n.yaml | 4 +- packages/client/runtime/README.md | 8 +- packages/client/runtime/README.zh.md | 8 +- packages/client/runtime/package.json | 1 + packages/client/runtime/src/client/index.ts | 4 +- .../src/client/sessions/conversation.ts | 27 +- .../src/client/sessions/fold-adapter.ts | 275 ------------ .../runtime/src/client/sessions/session.ts | 37 +- .../src/client/sessions/transcript-adapter.ts | 325 ++++++++++++++ .../tests/compact-checkpoint-pin.spec.ts | 52 +++ packages/client/runtime/tests/event-script.ts | 21 + .../client/runtime/tests/fold-adapter.spec.ts | 251 ----------- packages/client/runtime/tests/session.spec.ts | 63 +++ .../runtime/tests/transcript-adapter.spec.ts | 415 ++++++++++++++++++ packages/client/test-runtime/src/fixtures.ts | 1 - .../src/client/chat/CompactionItem.tsx | 49 +++ .../src/client/chat/MessageItem.module.css | 75 ++++ .../src/client/chat/MessageItem.tsx | 15 +- .../src/client/chat/chat-flow.ts | 2 +- .../tests/chat-branch-tails.spec.tsx | 28 ++ .../tests/chat-code-subcalls.spec.tsx | 2 +- .../tests/chat-stats-bash-sample.spec.tsx | 2 +- .../ui-conversation/tests/chat-view.spec.tsx | 2 +- .../tests/gate-branch-tails.spec.tsx | 2 +- .../ui-conversation/tests/input-bar.spec.tsx | 2 +- .../tests/input-matrix.spec.tsx | 2 +- .../tests/input-scenarios.spec.tsx | 2 +- .../ui-conversation/tests/queue-dock.spec.tsx | 2 +- .../ui-conversation/tests/skeleton.spec.tsx | 2 +- .../client/ui-trajectory/src/client/layout.ts | 4 +- .../client/ui-trajectory/src/client/spans.ts | 2 +- .../ui-trajectory/tests/layout.spec.tsx | 18 +- pnpm-lock.yaml | 3 + tsconfig.client.json | 6 + 45 files changed, 1385 insertions(+), 602 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md create mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md delete mode 100644 packages/client/runtime/src/client/sessions/fold-adapter.ts create mode 100644 packages/client/runtime/src/client/sessions/transcript-adapter.ts create mode 100644 packages/client/runtime/tests/compact-checkpoint-pin.spec.ts delete mode 100644 packages/client/runtime/tests/fold-adapter.spec.ts create mode 100644 packages/client/runtime/tests/transcript-adapter.spec.ts create mode 100644 packages/client/ui-conversation/src/client/chat/CompactionItem.tsx diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml index e4b0447cdd..6e1b952682 100644 --- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.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-19-gui-web-client-architecture.md: cfc2a7e62358e6282148b2d024ef3b162a903642 -2026-07-19-gui-web-client-architecture.zh.md: b5b082c25f664cfcb0ddd3fcc6c4cd3d58472218 +# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md +2026-07-19-gui-web-client-architecture.md: abe28b00638b4f01c7a50efe9ece5148e959a5ee +2026-07-19-gui-web-client-architecture.zh.md: 560015191fd8d99e2983a19d0b23aeb4dedff837 diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md index cfc2a7e623..abe28b0063 100644 --- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md +++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md @@ -50,7 +50,7 @@ There is no registration model besides slots — the former view and tool rings ## The data object layer (`packages/client/runtime/src/client/sessions/`) -Frames enter, snapshots exit, the fold sits between — React-free (zero React imports, grep-assertable): +Frames enter, snapshots exit, the projection sits between — React-free (zero React imports, grep-assertable): ``` mux/host 帧（ConnectionController 泵入，sinks 注入） @@ -62,17 +62,17 @@ SessionManager.handleMuxEnvelope / handleHostEnvelope Session.handleMuxEnvelope ──► events 窗口（seq 连续升序） │ │ 定稿事件 │ chunk │ ▼ ▼ - │ FoldAdapter PartialAccumulator + │ TranscriptAdapter PartialAccumulator │ （→ nodes） （→ partial） ▼ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──► 组件 ``` -- **Session** (session.ts): lazily built, resident — once created it keeps eating frames in the background, so switching away and back renders instantly. Operations: `prompt`/`cancel` (RPC passthrough; failures land in the snapshot's `promptError`), `open` (pull the tail history page, idempotent), `loadOlder` (upward paging, reentry-guarded), `resync` (reconnect = clear the window and rerun open). Subscription: `subscribe`/`getSnapshot` (always the cached reference) — `implements ObservableSnapshot`, with `useSelector = bindSnapshotSelector(this)` attached at construction, so a Session is directly a uSES source. Frame dispatch is one switch: `session/event` frames dedup by seq (the only dedup key), buffer while open is in flight, otherwise append + incremental fold; open/stitch merges the live buffer by seq and backfills once if `subscribed.lastSeq` outruns the window tail. -- **ConversationSnapshot** (conversation.ts): the immutable snapshot contract — `nodes` (folded, surface-ordered), `partial`, `runningCalls`, `pending`, `running`, `removed`, `openState`, `hasMore`, `promptError` and kin. **Reference discipline** (the premise of memo and uSES): the top-level object is fresh on every change; the nodes array is rebuilt but element references come from the cache; unchanged substructures reuse the previous snapshot's references. +- **Session** (session.ts): lazily built, resident — once created it keeps eating frames in the background, so switching away and back renders instantly. Operations: `prompt`/`cancel` (RPC passthrough; failures land in the snapshot's `promptError`), `open` (pull the tail history page, idempotent), `loadOlder` (upward paging, reentry-guarded), `resync` (reconnect = clear the window and rerun open). Subscription: `subscribe`/`getSnapshot` (always the cached reference) — `implements ObservableSnapshot`, with `useSelector = bindSnapshotSelector(this)` attached at construction, so a Session is directly a uSES source. Frame dispatch is one switch: `session/event` frames dedup by seq (the only dedup key), buffer while open is in flight, otherwise append + incremental projection; open/stitch merges the live buffer by seq and backfills once if `subscribed.lastSeq` outruns the window tail. +- **ConversationSnapshot** (conversation.ts): the immutable snapshot contract — `nodes` (the human transcript, log-ordered), `partial`, `runningCalls`, `pending`, `running`, `removed`, `openState`, `hasMore`, `promptError` and kin. **Reference discipline** (the premise of memo and uSES): the top-level object is fresh on every change; the nodes array is rebuilt but element references come from the cache; unchanged substructures reuse the previous snapshot's references. - **SessionManager** (manager.ts): instance cluster + frame entry + the session list. sessionId-bearing frames go only to existing instances (a mux broadcast must not instantiate every session); approval/question `requested` frames are the exception — they never land in history, so they buffer in `pendingBuffers` and replay on instantiation. - **Notifier** (notifier.ts): two channels chosen by change source. `markDirty()` (default; frame-driven changes always) batches per microtask — N changes, one notification, one re-render; the flush rebuilds the snapshot cache before notifying. `notifyNow()` (only direct echoes of user gestures) rebuilds and notifies in the same tick — controlled inputs roll the DOM back and jump the caret if their echo defers to a microtask. Frame-driven code using notifyNow collapses batching back to per-frame renders; banned. -- **FoldAdapter / PartialAccumulator**: the fold reuses the core SurfaceManager (`@deepseek-ai/dsh-session/surface`), padding sentinel events so a paged window starting at seq > 0 satisfies the core's `seq === index` assertion; a cross-window replace degrades to a tolerant linear scan and sets `foldDegraded`. Chunks stay out of the fold entirely (O(1) skip): the accumulator folds StreamChunks into `AssistantBlock[]`, a delta swapping only that block's reference, and the finalizing message discards the accumulator in the same batch (no flicker on promotion). Cost model: one chunk = one string concatenation + a dirty mark; an unsubscribed Session under a frame storm costs only the mark. +- **TranscriptAdapter / PartialAccumulator**: the transcript is the append-origin surface projected in log order (`isAppendSurfaceEvent` from `@deepseek-ai/dsh-session/surface`) plus one marker per landed compaction checkpoint — never the model surface, which shadows replaced ranges and would erase conversation the reader already saw. Node order is seq-monotonic by construction, so there is no core `seq === index` assertion to satisfy and no degradation branch. Chunks contribute no node (O(1) skip): the accumulator folds StreamChunks into `AssistantBlock[]`, a delta swapping only that block's reference, and the finalizing message discards the accumulator in the same batch (no flicker on promotion). Cost model: one chunk = one string concatenation + a dirty mark; an unsubscribed Session under a frame storm costs only the mark. - **ConnectionController** (in `packages/client/connection`): opens the mux/host streams, pumps with for-await, reconnects with exponential backoff (500ms doubling to 10s, jitter, unlimited) behind a generation fence; sinks are injected one-way (the Controller does not know Session). Reconnect = rebuild: `onConnected` → list refresh + per-open-session resync. The object layer faces only `IApiClient`; the Web carriage (HTTP POST for the two client→server quadrants, SSE for the two server→client) and the client class family are the layering RFC's territory. ## The React face (`packages/client/web-react`) diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md index b5b082c25f..560015191f 100644 --- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md @@ -62,17 +62,17 @@ SessionManager.handleMuxEnvelope / handleHostEnvelope Session.handleMuxEnvelope ──► events 窗口（seq 连续升序） │ │ 定稿事件 │ chunk │ ▼ ▼ - │ FoldAdapter PartialAccumulator + │ TranscriptAdapter PartialAccumulator │ （→ nodes） （→ partial） ▼ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──► 组件 ``` - **Session**（session.ts）：懒建、常驻——建成后在后台持续吃帧，切走切回秒显。操作面：`prompt`/`cancel`（RPC 透传；失败落进快照的 `promptError`）、`open`（拉尾页 history，幂等）、`loadOlder`（向上翻页，防重入）、`resync`（重连 = 清窗口重跑 open）。订阅面：`subscribe`/`getSnapshot`（恒返缓存引用）——`implements ObservableSnapshot`，构造时挂 `useSelector = bindSnapshotSelector(this)`，Session 本身就是 uSES 源。帧分发是一个 switch：`session/event` 帧按 seq 去重（唯一去重键），open 在途时缓冲，否则追加 + 增量 fold；open/缝合按 seq 合并 live 缓冲并去重，`subscribed.lastSeq` 超出窗口尾则回补一次。 -- **ConversationSnapshot**（conversation.ts）：不可变快照契约——`nodes`（fold 产物，surface 序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；nodes 数组重建但元素引用来自缓存；未变的子结构复用上一快照的引用。 +- **ConversationSnapshot**（conversation.ts）：不可变快照契约——`nodes`（人类对话记录，日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；nodes 数组重建但元素引用来自缓存；未变的子结构复用上一快照的引用。 - **SessionManager**（manager.ts）：实例簇 + 帧总入口 + 会话列表。带 sessionId 的帧只投已存在实例（mux 广播不得把每个会话都实例化）；例外是审批/问答 `requested` 帧——它们不落 history、open 无法回补，故缓冲进 `pendingBuffers`，实例化时回放。 - **Notifier**（notifier.ts）：两条通知通道，按变更来源取用。`markDirty()`（默认；帧驱动一律用它）按微任务合批——N 次变更、一次通知、一次重渲染；flush 先重建快照缓存再通知。`notifyNow()`（仅用户手势的直接回响）同 tick 重建并通知——受控输入的回响若延到微任务，DOM 会回滚、光标跳尾。帧驱动代码用 notifyNow 会让合批塌回逐帧渲染；禁。 -- **FoldAdapter / PartialAccumulator**：fold 复用核心 SurfaceManager（`@deepseek-ai/dsh-session/surface`），垫哨兵事件使 seq > 0 起头的分页窗口满足核心的 `seq === index` 断言；跨窗口 replace 时降级为容错线性扫描并置 `foldDegraded`。分片完全不进 fold（O(1) 跳过）：累积器把 StreamChunk 折叠成 `AssistantBlock[]`，一次增量只换该块引用；定稿消息到达即在同一批内弃掉累积器（提升无闪烁）。成本模型：一个分片 = 一次字符串拼接 + 一个脏标记；帧风暴下未订阅的 Session 只花那个标记。 +- **TranscriptAdapter / PartialAccumulator**：对话记录是按日志顺序投影的 append 来源 surface（`@deepseek-ai/dsh-session/surface` 的 `isAppendSurfaceEvent`），外加每次落地的压缩检查点一个标记——绝不用模型 surface，后者遮蔽被替换的范围，会抹掉读者已经看过的对话。节点顺序天然按 seq 单调，因此既无核心 `seq === index` 断言需要满足，也没有降级分支。分片不贡献任何节点（O(1) 跳过）：累积器把 StreamChunk 折叠成 `AssistantBlock[]`，一次增量只换该块引用；定稿消息到达即在同一批内弃掉累积器（提升无闪烁）。成本模型：一个分片 = 一次字符串拼接 + 一个脏标记；帧风暴下未订阅的 Session 只花那个标记。 - **ConnectionController**（在 `packages/client/connection`）：开 mux/host 双流、for-await 泵入，代际围栏之内指数退避重连（500ms 翻倍至 10s 封顶、抖动、无限重试）；sinks 单向注入（Controller 不认识 Session）。重连 = 重建：`onConnected` → 列表刷新 + 各已打开会话 resync。对象层只面向 `IApiClient`；Web 承载（HTTP POST 载两个 client→server 象限、SSE 载两个 server→client 象限）与客户端类族归分层 RFC 属地。 ## React 面（`packages/client/web-react`） 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 edb6ac6e4a..7ee4b1fac8 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: a296b93d538d9c28bd61ee8fd0530863b4bfd878 -2026-07-29-human-transcript-append-origin.zh.md: 96e0cd1038fe8904dfd4c1eceaae9b25339c5dca +2026-07-29-human-transcript-append-origin.md: dcc4a786c6f1926f06dce03124ec1d8ca805d7ae +2026-07-29-human-transcript-append-origin.zh.md: 0fefc52afa52e99cdec2bcea1a86b9c28711dd67 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 a296b93d53..dcc4a786c6 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 @@ -24,9 +24,9 @@ No persisted event, RPC envelope, compaction transaction, or model-visible surfa ## Deferred -The browser client still builds its conversation from the model surface through `FoldAdapter`, so compaction still collapses web history to a single context row. The same predicate is the fix there, together with an append-order transcript projection and a marker component; that work is a separate change against `packages/client/runtime` and `packages/client/ui-conversation`. +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. -That work must handle a page whose checkpoint cites a `surfaceOp.start` outside the window: pagination no longer spends quota on the checkpoint, so it never cuts on the checkpoint's provenance group, and `FoldAdapter` pads absent events with a non-surface sentinel — so `SurfaceManager` rejects the range and `nodes()` falls back to `degradedSeqs()` with a logged error. The 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. `degradedSeqs()` — every surface-eligible event in append order — is already close to the transcript projection A2 needs, which is the shape to build deliberately rather than reach as a degradation. Rendering compaction *progress* — a terminal indicator while a compaction runs — needs the bracket-first ordering that the queued manual `/compact` work introduces, and is likewise 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. +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. ## 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 96e0cd1038..0fefc52afa 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 @@ -24,9 +24,9 @@ Status: implemented ## Deferred -浏览器客户端仍通过 `FoldAdapter` 从模型 surface 构建会话，因此压缩在 Web 端仍会把历史折叠成一行上下文。那里的修复用的是同一个谓词，另需按追加顺序的记录投影与一个标记组件；该工作是针对 `packages/client/runtime` 与 `packages/client/ui-conversation` 的独立变更。 +浏览器客户端在[Web 记录投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份 append 来源记录并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝该范围。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，其溯源分组把整段被遮蔽的范围一起拉到该页。 -该工作必须处理这样一页：其检查点引用的 `surfaceOp.start` 落在窗口之外。分页不再为检查点消耗额度，因此永远不会按检查点的溯源分组切分；而 `FoldAdapter` 会用一个非 surface 的哨兵事件填补缺失事件——于是 `SurfaceManager` 拒绝该范围，`nodes()` 退化为 `degradedSeqs()` 并记录一条错误。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，其溯源分组把整段被遮蔽的范围一起拉到该页。`degradedSeqs()`——按追加顺序的每个 surface 可入事件——已经很接近 A2 所需的记录投影，因此那正是应当刻意构建的形态，而不是作为退化路径被动落到的结果。渲染压缩*进度*——压缩运行期间的终端指示——需要排队式手动 `/compact` 工作引入的“先开括号”顺序，同样不在本次范围内。标记同样不携带规模信息：检查点的 `sourceEventSeqs` 已经包含被遮蔽的数量，因此一个计数或区间可以告诉读者每一行折叠了多少内容。这件事属于进度那一侧，读者正是在那里遇到同一份信息的另一半。接手者应当先把终端里两处替换分支——回放与实时监听器，文本完全相同却相隔 600 行——合并为一个 `renderReplacement(event)`，让标记的内容只有一个归处。 +渲染压缩*进度*——压缩运行期间的终端指示——需要排队式手动 `/compact` 工作引入的“先开括号”顺序，不在本次范围内。标记同样不携带规模信息：检查点的 `sourceEventSeqs` 已经包含被遮蔽的数量，因此一个计数或区间可以告诉读者每一行折叠了多少内容。这件事属于进度那一侧，读者正是在那里遇到同一份信息的另一半。接手者应当先把终端里两处替换分支——回放与实时监听器，文本完全相同却相隔 600 行——合并为一个 `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 new file mode 100644 index 0000000000..5f80a9b7c9 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.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-30-web-transcript-log-ordered-projection.md +2026-07-30-web-transcript-log-ordered-projection.md: 22e687ebc0a323a28eb554a9ad36749a0b6f3da6 +2026-07-30-web-transcript-log-ordered-projection.zh.md: 97004f7384aed8f9e43b0949b2fcd4b8c185ca65 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 new file mode 100644 index 0000000000..22e687ebc0 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md @@ -0,0 +1,66 @@ +# Agent Note: The browser conversation is a log-ordered human transcript + +Status: implemented + +English | [中文](2026-07-30-web-transcript-log-ordered-projection.zh.md) + +## Problem + +The browser client built its conversation from the model-visible surface: `FoldAdapter` ran the core `SurfaceManager` over the history window and read `surface.nodes`. A successful compaction replaces a surface range with one checkpoint node, so the moment that replacement landed the web flow collapsed every message it shadowed into a single dim context row — conversation the user had already read. Nothing was lost from the log; the defect was entirely in the projection, and [the terminal and the host gateway were fixed the same way](2026-07-29-human-transcript-append-origin.md) while the browser was left for this change. + +Surface order made two further problems structural. It is not seq-ascending after a replacement — `SurfaceManager` splices the high-seq checkpoint into the position of the range it shadows — so log-only nodes merged into that array by numeric seq (slash-command rows, interrupted frozen nodes) could be flushed ahead of the checkpoint and never interleave into the retained tail again. And because pagination no longer spends `maxMessages` quota on replacement copies, a page can now carry a checkpoint whose `surfaceOp.start` lies outside the window; the core fold rejects that range, so `nodes()` fell back to a lenient linear scan behind a `console.error` and published a `foldDegraded` flag describing the failure. + +## Decision + +`TranscriptAdapter` replaces `FoldAdapter` and never consults surface order. It projects the raw window in log order: every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint. A landed compaction therefore keeps the conversation it shadowed on the model side, and the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out of the transcript: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary in the conversation. Everything that must send exactly what the model sees keeps reading the surface; this is the human projection, and the two are now separate on both frontends. + +Node order is seq-monotonic by construction, and three things follow. The log-only `command/run` / `command/done` pair folds into `CommandNode`s that splice into an already-monotonic array by seq — no anchors, no reordering. `Session` keeps ownership of interrupted frozen nodes and merges them by their fractional seqs with a plain sort, which is now exactly flow order. And a window whose checkpoint cites a shadowed range outside it has no range to resolve, so the marker renders and nothing is logged. + +`foldDegraded` is gone from `ConversationSnapshot`, and with it the padding sentinels, the `baseSeq` arithmetic they needed, and `degradedSeqs()`. They existed only to satisfy the core fold's `seq === index` assertion and to survive its throw; the fold they describe is no longer run. Deleting the flag is part of the fix, not cleanup after it — `degradedSeqs()` was already almost the log-ordered projection, reached after a thrown error instead of intended. + +The marker's summary text comes from the checkpoint's own `compact/summary` provenance, never from the framed checkpoint payload, which is an instruction envelope written for the model. A window cut that left the provenance outside makes the row non-expandable rather than empty, the same soft-fall as a call-less tool result, and a later page supplying the provenance resolves the text. + +No persisted event, RPC envelope, compaction transaction, or model-visible surface changed, and no migration is required. + +## Recognizing a checkpoint: the local literal and its drift trap + +Recognition needs all three conditions, as in the terminal: `event.type === 'user/message'`, the compaction seam's checkpoint plugin source, **and** `isReplacementSurfaceEvent(event)`. A plugin-sourced `user/message` that *appends* is injected context — a session-reference card — not a compaction. + +The client restates that plugin source as a local literal, because `dsh-compact` is unreachable from `packages/client/runtime`'s program in **both** directions: + +- a **value** import fails the client purity gate (`packages/client/tsdown.client.ts`), and `dsh-compact`'s root value-imports cordis, so admitting it would pull `CompactService` into the browser bundle; +- a **type-only** import fails typecheck. `dsh-compact`'s root reaches `dsh-session`'s root, whose cordis `Context` merge declares the host `sessions: SessionStore` against this program's `sessions: ISessions` — `TS2717`, the one-program-per-side rule in [development.md](../../../../docs/development.md#typescript-project-layout). This was expected to work and does not; `import type` is erased before the *bundler* runs, but not before the *compiler* does, and the collision is a compiler fact. + +The drift protection therefore lives in a test, not in a type: `packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` runs in the client **test** program, which carries no such collision, and drives the adapter with a checkpoint built from the canonical `COMPACT_CHECKPOINT_SOURCE` itself. Renaming the seam's plugin fails there instead of silently deleting every compaction marker from the web transcript. `dsh-compact` is a `devDependency` of `dsh-client-runtime` and a reference of `tsconfig.client.json` only — never of a `packages/client/*` package project. + +That is a deliberate divergence from the terminal, which value-imports `isCompactCheckpointSource` directly because no gate applies host-side. + +## What #835's positional anchors were for, and why they are dissolved rather than lost + +The unmerged manual-compaction-queueing branch fixes the same interleaving bug by recording a per-event anchor — the surface tail at append time — and retargeting shadowed anchors onto the checkpoint. That mechanism exists to make positional anchors survive surface **reordering**. The human transcript is never re-ordered, so anchors have nothing to retarget: the precondition is removed, not the fix discarded. The mechanism is absent from this base and is not authored here. + +## Alternatives considered + +**Add `dsh-compact` to the client `INLINE_SAFE` allowlist** and move the predicate to a cordis-free subpath. Rejected: `INLINE_SAFE` matches on specifier *prefix*, so admitting the package admits its cordis-importing root too; the allowlist is a reviewer promise about client-facing subpaths, not a purity proof. It also needs a new export and a `files` fix, and it would not have helped — the blocking collision turned out to be in the compiler, which an allowlist does not touch. + +**A bare shape rule** — any replacement `user/message` is a compaction. Rejected: correct today only because compaction is the sole producer of replacement `user/message`s, with nothing to catch it if that changes. The pinning spec costs one file and removes exactly that risk. + +**Tag the checkpoint host-side** through the projection or wire contract. Rejected: most aligned with the "collaborate through cordis services" rule, but the client folds raw `SessionEvent`s today, so it means a wire contract change out of proportion to one pure predicate. + +**Move frozen-node ownership into the adapter** (`nodes(extraNodes)`), as the unmerged branch does. Rejected: the interrupted nodes come from the `turn/end` sweep `Session` already runs over the window, and with a seq-monotonic transcript the simple shape is correct — the adapter returns nodes, the session merges frozen ones by seq. Widening the adapter's signature would buy nothing and split the sweep from its product. + +**Keep `foldDegraded` as a defensive flag.** Rejected: it described a specific failure of a fold that no longer runs. A flag no consumer can act on, reachable only through a `console.error`, is a false contract. + +## Consequences + +Compaction no longer erases web history; a session compacted several times shows one marker per landed compaction, in log order, and the same window renders identically live and after a cold resume. The pagination hole is closed by construction rather than defended against, and `ConversationSnapshot` loses a published field, which touched thirteen files. + +`ConversationNode` gains an eighth arm, so every exhaustive consumer grew one case: `MessageItem` renders the marker through the new `CompactionItem`, and the trajectory layout widens its no-cell arm so a marker contributes no cell but still advances the duration cursor. + +The performance contract is unchanged and now simpler to state: one append materializes one node, an event that changes no node keeps the previous array reference — so a chunk storm costs nothing and `nodes()` is not even recomputed — and unchanged nodes keep their object identity. The window still grows with session length rather than with the surface, which is the trade the fix exists to make; a compaction used to bound the projection for exactly the long sessions compaction serves. + +The web e2e scenario now seeds a real compaction transaction over its recorded turn, so the aria golden pins both halves of the fix through the real host and a real browser: the recorded prompt and full tool output are still on screen, and one marker sits after them. The seed recording itself is untouched and stays model-authentic — replay derives the compacted turn from the recording's own surface. + +## 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. 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 new file mode 100644 index 0000000000..97004f7384 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md @@ -0,0 +1,66 @@ +# Agent Note: 浏览器会话是按日志顺序投影的人类对话记录 + +Status: implemented + +[English](2026-07-30-web-transcript-log-ordered-projection.md) | 中文 + +## Problem + +浏览器客户端从模型可见的 surface 构建会话：`FoldAdapter` 在历史窗口上运行核心 `SurfaceManager` 并读取 `surface.nodes`。一次成功的压缩会用一个检查点节点替换一段 surface 范围，因此该替换一落地，Web 流就把它所遮蔽的每条消息折叠成一行灰暗的上下文——那是用户已经读过的对话。日志中什么都没丢失；缺陷完全在投影层，而[终端与宿主历史网关已按同一方式修复](2026-07-29-human-transcript-append-origin.md)，浏览器留给了本次变更。 + +surface 顺序还让另外两个问题成为结构性的。一次替换之后它并非按 seq 升序——`SurfaceManager` 把高 seq 的检查点拼接到它所遮蔽范围的位置上——因此按数值 seq 归并进该数组的仅日志节点（斜杠命令行、被打断的冻结节点）可能被冲刷到检查点之前，再也无法交错回保留下来的尾部。而且由于分页不再为 replacement 副本消耗 `maxMessages` 额度，一页现在可以携带一个 `surfaceOp.start` 落在窗口之外的检查点；核心 fold 拒绝该范围，于是 `nodes()` 退回到一次宽容的线性扫描、打印一条 `console.error`，并发布一个描述该失败的 `foldDegraded` 标志。 + +## Decision + +`TranscriptAdapter` 取代 `FoldAdapter`，并且从不查询 surface 顺序。它按日志顺序投影原始窗口：每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，外加每次落地的压缩检查点一个 `CompactionSummaryNode` 标记。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话，标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不在对话中标记任何边界。凡必须发送模型所见内容的一切仍读 surface；这是人类投影，两者现在在两个前端上都已分离。 + +节点顺序天然按 seq 单调，由此有三个结果。仅日志的 `command/run` / `command/done` 对折叠成 `CommandNode`，按 seq 插入一个本已单调的数组——无锚点，无重排。`Session` 保留被打断的冻结节点的归属，用一次普通排序按其分数 seq 归并，而这现在恰好就是流顺序。检查点所引被遮蔽范围落在窗口之外的窗口没有范围需要解析，因此标记正常渲染且不打印任何日志。 + +`foldDegraded` 从 `ConversationSnapshot` 消失，随之消失的是哨兵填充、它们所需的 `baseSeq` 算术，以及 `degradedSeqs()`。它们的存在只为满足核心 fold 的 `seq === index` 断言并在其抛错时存活；它们所描述的 fold 已不再运行。删除该标志是修复的一部分，而非修复之后的清理——`degradedSeqs()` 本身已几乎就是按日志顺序的投影，只是作为抛错后的落点而非本意到达。 + +标记的摘要文本来自检查点自己的 `compact/summary` 溯源，绝不取自成框的检查点载荷——那是为模型撰写的指令信封。窗口切分把溯源留在窗口外时该行不可展开而非空白，与无调用的工具结果同一种软退让；后续补上溯源的分页会解析出文本。 + +没有任何持久化事件、RPC 信封、压缩事务或模型可见 surface 发生变化，也不需要迁移。 + +## 识别检查点：本地字面量与它的漂移陷阱 + +识别需要三个条件同时成立，与终端一致：`event.type === 'user/message'`、压缩缝隙的检查点插件来源，**以及** `isReplacementSurfaceEvent(event)`。一条 append 的插件来源 `user/message` 是注入上下文——跨会话引用卡片——不是压缩。 + +客户端把该插件来源重述为一个本地字面量，因为 `dsh-compact` 在**两个**方向上都无法从 `packages/client/runtime` 的程序到达： + +- **值**导入会失败于客户端纯度门禁（`packages/client/tsdown.client.ts`），而 `dsh-compact` 的根部会值导入 cordis，因此放行它就会把 `CompactService` 拉进浏览器产物； +- **仅类型**导入会失败于类型检查。`dsh-compact` 的根部会到达 `dsh-session` 的根部，后者的 cordis `Context` 合并声明了宿主侧 `sessions: SessionStore`，与本程序的 `sessions: ISessions` 冲突——`TS2717`，即 [development.md](../../../../docs/development.md#typescript-project-layout) 中每侧一个 program 的规则。这一点原本预期可行，实际不可行：`import type` 在**打包器**运行前被擦除，但不在**编译器**运行前被擦除，而该冲突是编译器事实。 + +因此漂移保护住在一个测试里，而不是一个类型里：`packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` 运行在客户端**测试**程序中——那里不存在这一冲突——并用由权威 `COMPACT_CHECKPOINT_SOURCE` 本身构造的检查点驱动适配器。重命名缝隙的插件会在那里失败，而不是无声地把每个压缩标记从 Web 记录中删除。`dsh-compact` 只是 `dsh-client-runtime` 的 `devDependency` 以及 `tsconfig.client.json` 的一条引用——绝不是任何 `packages/client/*` 包工程的引用。 + +这是与终端的一次刻意分歧：终端直接值导入 `isCompactCheckpointSource`，因为宿主侧不适用任何门禁。 + +## #835 的位置锚点是为什么而存在，以及为什么它是被溶解而非丢失 + +尚未合并的排队式手动压缩分支用另一种方式修同一个交错缺陷：为每个事件记录一个锚点——追加时的 surface 尾部——并把被遮蔽的锚点重定向到检查点上。该机制的存在是为了让位置锚点在 surface **重排**中存活。人类对话记录永不被重排，因此锚点没有任何东西需要重定向：前提被移除，修复并未被丢弃。该机制在本基线上并不存在，本次也不撰写它。 + +## Alternatives considered + +**把 `dsh-compact` 加入客户端 `INLINE_SAFE` 白名单**，并把谓词搬到一个不含 cordis 的子路径。已拒绝：`INLINE_SAFE` 按标识符*前缀*匹配，因此放行该包也就放行了它那个会导入 cordis 的根部；该白名单是对面向客户端子路径的评审承诺，不是纯度证明。它还需要一个新导出与一处 `files` 修正，而且本来也帮不上忙——真正阻塞的冲突出在编译器，白名单碰不到那里。 + +**一条纯形状规则**——任何 replacement `user/message` 都是压缩。已拒绝：它今天正确只因为压缩是 replacement `user/message` 的唯一生产者，一旦这点改变便无任何机制能捕获。那个 pin 测试只花一个文件，就精确消除了这一风险。 + +**在宿主侧给检查点打标**，经投影或线协议。已拒绝：这最贴合“经 cordis 服务协作”的规则，但客户端今天折叠的是原始 `SessionEvent`，因此这意味着一次线协议契约变更——为一个纯谓词付出的代价不成比例。 + +**把冻结节点的归属移进适配器**（`nodes(extraNodes)`），像那个未合并分支所做的那样。已拒绝：被打断的节点来自 `Session` 已经在窗口上运行的 `turn/end` 清扫，而在按 seq 单调的记录之上，简单形态就是正确的——适配器返回节点，会话按 seq 归并冻结节点。加宽适配器签名什么也换不到，还会把清扫与它的产物拆开。 + +**把 `foldDegraded` 留作一个防御性标志。** 已拒绝：它描述的是一个已不再运行的 fold 的特定失败。一个消费方无法据以行动、只能通过 `console.error` 到达的标志，是一份虚假契约。 + +## Consequences + +压缩不再抹掉 Web 历史；一个被压缩多次的会话按日志顺序显示每次落地压缩一个标记，而同一窗口在实时与冷恢复之后渲染完全相同。分页缺口是被构造性闭合而非被防御，`ConversationSnapshot` 少了一个已发布字段，这触及十三个文件。 + +`ConversationNode` 增加第八个分支，因此每个穷尽消费方都多一个分支：`MessageItem` 通过新的 `CompactionItem` 渲染标记，trajectory 布局加宽它的“无单元格”分支，使标记不贡献单元格但仍推进耗时游标。 + +性能契约未变，且现在更易表述：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用——因此分片风暴零成本、`nodes()` 甚至不会重算——未变化的节点保持其对象标识。窗口仍随会话长度而非随 surface 增长，这正是本修复存在所要做的交换；一次压缩过去恰好为压缩所服务的长会话限制了投影规模。 + +Web e2e 场景现在在它录制的那一轮之上播种一次真实的压缩事务，因此 aria 基准经真实宿主与真实浏览器钉住修复的两半：录制的提问与完整工具输出仍在屏幕上，其后坐着一个标记。录制本身未被触碰、保持模型真实——回放从录制自身的 surface 派生出被压缩的那一轮。 + +## Deferred + +压缩**进度**——压缩运行期间的指示——需要排队式手动压缩工作引入的“先开括号”顺序，与终端一样不在本次范围内。标记同样不携带**规模**信息：检查点的 `sourceEventSeqs` 已经包含被遮蔽的数量，因此一个计数或区间可以告诉读者每一行折叠了多少内容。两者应当放在一起，读者正是在那里遇到同一份信息的两半。 diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts index d30b3d7c39..30e824324b 100644 --- a/apps/web/tests/seeded-history.e2e.ts +++ b/apps/web/tests/seeded-history.e2e.ts @@ -1,8 +1,8 @@ // Web e2e scenario: seeded history. A recorded session seeded cold through // the REAL persistence API renders purely from the log — the surface nothing // else covers: sidebar cold listing, the implicit resume/attach inside the -// history RPC, history-page tool views, and the client fold of historical -// events — with ZERO model calls in replay (no replay fixture; a stray stream +// history RPC, history-page tool views, and the client's log-ordered transcript +// of historical events — with ZERO model calls in replay (no replay fixture; a stray stream // fails loud on the open llm seam). The seed is a recorded fixture under the // same record discipline as every other: DSH_SNAPSHOT=record drives the turn // live through the composer (real read tool against seeded workspace files) @@ -27,6 +27,77 @@ const SEED_ID = 'seeded-history-web-e2e' const PROMPT = 'Use the read tool twice in one assistant message: read a.txt and b.txt. Then reply with the single word DONE and stop.' +/** + * Append a complete, valid compaction transaction over the recorded turn's own + * surface. The recording stays model-authentic and reusable; replay adds this + * deterministic condition before seeding it cold, so the scenario pins the bug + * this change fixes — a landed compaction must not erase history the reader + * already saw — through the real host and the real browser. + * @param raw - the committed seed fixture text. + * @returns the fixture with a compacted turn appended. + */ +function withCompaction(raw: string): string { + const lines = raw.trimEnd().split('\n') + const events = lines.slice(1).map(line => JSON.parse(line) as { + type: string + seq: number + time: number + surfaceOp?: unknown + }) + const surfaceSeqs = events + .filter(event => event.surfaceOp === 'append' + && (event.type === 'user/message' + || event.type === 'assistant/message' + || event.type === 'tool/result' + || event.type === 'steering/message')) + .map(event => event.seq) + const first = surfaceSeqs[0] + const last = surfaceSeqs.at(-1) + const tail = events.at(-1) + if (first === undefined || last === undefined || tail === undefined) { + throw new Error('seeded-history compaction requires a non-empty closed surface') + } + let seq = tail.seq + 1 + let time = tail.time + 1 + const at = (event: Record): string => JSON.stringify({ ...event, seq: seq++, time: time++ }) + // The checkpoint's provenance names the two events appended before it. + const startSeq = seq + 1 + const summarySeq = seq + 2 + lines.push( + at({ type: 'turn/start', data: { turn: 2, trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'compact' } } } }), + at({ type: 'compact/start', data: { turn: 2 } }), + at({ + type: 'compact/summary', + data: { + summary: [{ + type: 'text', + text: '## Cold resume compact summary\n\n- The exact summary remains available.', + }], + shadowedRange: { start: first, end: last }, + shadowedSeqs: surfaceSeqs, + shadowedTokenCount: 10_000, + provider: 'snapshot', + model: 'snapshot-compactor', + }, + }), + at({ + type: 'user/message', + data: { + content: [{ + type: 'text', + text: 'Model-only compact checkpoint.', + }], + source: { kind: 'plugin', plugin: 'compact' }, + }, + surfaceOp: { op: 'replace', start: first, end: last }, + sourceEventSeqs: [startSeq, summarySeq, ...surfaceSeqs], + }), + at({ type: 'compact/end', data: { turn: 2 } }), + at({ type: 'turn/end', data: { turn: 2, reason: { kind: 'completed' } } }), + ) + return `${lines.join('\n')}\n` +} + describe('web e2e: seeded history renders through cold resume', () => { let scaffold: WebScaffold let browser: Browser @@ -46,7 +117,7 @@ describe('web e2e: seeded history renders through cold resume', () => { if (MODE !== 'record') { const raw = await readFile(SEED, 'utf8') expect(fixtureUserPrompts(raw), 'seed fixture must carry exactly the drive prompt').toEqual([PROMPT]) - await seedSession(scaffold, raw, SEED_ID) + await seedSession(scaffold, withCompaction(raw), SEED_ID) } browser = await chromium.launch() page = await browser.newPage({ viewport: { width: 1680, height: 1000 } }) @@ -112,11 +183,15 @@ describe('web e2e: seeded history renders through cold resume', () => { await sessionRow.click() // Settled barrier for history: the recorded final assistant text renders. await expect.poll(() => page.getByText('DONE', { exact: true }).count(), { timeout: 15_000 }).toBe(1) + await expect.poll(() => page.getByText('上下文已压缩', { exact: true }).count(), { timeout: 10_000 }).toBe(1) // Tool cards render from logged tool/call + tool/result alone (views are // host-recomputed per page; the generic card is the documented default). const toolRows = page.locator('[data-variant], [data-sample]') await expect.poll(() => toolRows.count(), { timeout: 10_000 }).toBeGreaterThanOrEqual(2) expect(await page.getByText('a.txt', { exact: false }).count()).toBeGreaterThan(0) + // The bug this fixes: the compaction shadowed the whole recorded surface on + // the model side, and the prompt and full tool output are still on screen. + expect(await page.getByText(PROMPT, { exact: true }).count()).toBe(1) }, 60_000) it.skipIf(MODE === 'record')('matches the historical conversation aria golden', async () => { @@ -147,6 +222,22 @@ describe('web e2e: seeded history renders through cold resume', () => { await expect.poll(() => page.getByText('a.txt', { exact: false }).count(), { timeout: 5_000 }).toBeGreaterThan(0) }) + it.skipIf(MODE === 'record')('expands the cold-resumed compact summary', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-seeded-compaction')) + const marker = page.getByRole('button', { name: /上下文已压缩/ }) + await marker.waitFor({ timeout: 10_000 }) + expect(await marker.getAttribute('aria-expanded')).toBe('false') + await marker.click() + await expect.poll(() => marker.getAttribute('aria-expanded'), { timeout: 5_000 }).toBe('true') + await expect.poll(() => page.getByRole('heading', { name: 'Cold resume compact summary' }).count(), { + timeout: 5_000, + }).toBe(1) + expect(await page.getByText('The exact summary remains available.', { exact: false }).count()).toBeGreaterThan(0) + // Collapse again so the aria golden captured after this case is unaffected. + await marker.click() + await expect.poll(() => marker.getAttribute('aria-expanded'), { timeout: 5_000 }).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/snapshots/seeded-history/ui.expected.md b/apps/web/tests/snapshots/seeded-history/ui.expected.md index db71bd6696..28252224f1 100644 --- a/apps/web/tests/snapshots/seeded-history/ui.expected.md +++ b/apps/web/tests/snapshots/seeded-history/ui.expected.md @@ -36,7 +36,11 @@ - img - button "在新对话中分支": - img -- text: {{clock}} cache hit 98% · 15,962 tokens · 1 turns · 2 steps +- text: {{clock}} +- button "上下文已压缩 点击查看压缩摘要": + - img + - text: 上下文已压缩 点击查看压缩摘要 +- text: cache hit 98% · 15,962 tokens · 1 turns · 2 steps - textbox "Message the agent" - button "Add attachment": - img diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml index 429ae8f0a9..ec2fb497e6 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: 25eb60e2c95059ae918669c9f5169b6b8e9c6816 -README.zh.md: e3085f91750503aeaffda41d86c40c62943b4ba9 +README.md: 7bf8050ea988945bead491d02528906863b129a6 +README.zh.md: ff3c91dee956b2c65f0029c97c73d73f5a627b05 diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md index 25eb60e2c9..7bf8050ea9 100644 --- a/packages/client/runtime/README.md +++ b/packages/client/runtime/README.md @@ -16,9 +16,15 @@ SlotsService gives the renderer separate bare observables for `useSessions` and `WorkspacesService.connectWorkspace(workspaceId)` resolves the session a New Session flow lands in: it reuses the workspace's existing blank session from the list mirror (`blank && cwd == workspace.path`) or calls `session.create({workspaceId})`, returning the session id for the caller to open. `SessionSummary.blank` mirrors the host's derived empty-log bit and only ever lowers on the client: seeded by `session.list` / the `host/session-added` frame, flipped false by the first ACCEPTED local `prompt()` (on the RPC success response — acceptance proves the user message is in the host log; a rejected first prompt keeps the session blank and reusable) and by any `running: true` status frame, re-aligned by every list re-pull. List surfaces hide blank rows; the store carries every row. `SessionsService.create` accepts an optional caller-preallocated SessionId and throws `SessionCreateError` (carrying `requestedSessionId`) on failure. +## The human transcript + +`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. That source literal is restated locally because `dsh-compact` is unreachable from this program in both directions (the client purity gate rejects a value import; a type-only import collides the host `Context.sessions` merge) — `tests/compact-checkpoint-pin.spec.ts` is the drift trap. + +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 one node, an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity. + ## 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 surface `nodes` flow; per-parent array and map references are memo-stable across unrelated snapshot swaps. +`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. ## Session title projection diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md index e3085f9175..ff3c91dee9 100644 --- a/packages/client/runtime/README.zh.md +++ b/packages/client/runtime/README.zh.md @@ -16,9 +16,15 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 `WorkspacesService.connectWorkspace(workspaceId)` 解析 New Session 流程最终落入的会话：先在列表镜像中复用该 workspace 的既有空会话（`blank && cwd == workspace.path`），未命中则调用 `session.create({workspaceId})`，返回会话 id 由调用方 open。`SessionSummary.blank` 镜像主机派生的空日志位，在客户端只降不升：由 `session.list`／`host/session-added` 帧播种，本地首次**受理成功**的 `prompt()`（RPC 成功响应时——受理即证明用户消息已入主机日志；首讯被拒则会话保持 blank、保持可复用）与任何 `running: true` 状态帧翻为 false，每次列表重拉重新对齐。列表表面隐藏 blank 行；store 保留全部行。`SessionsService.create` 接受可选的、由调用方预先分配的 SessionId，失败时抛出 `SessionCreateError`（携带 `requestedSessionId`）。 +## 人类对话记录 + +`ConversationSnapshot.nodes` 是人类对话记录，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口——每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，外加每次落地的压缩检查点贡献一个 `CompactionSummaryNode` 标记——且从不查询 surface 顺序。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩缝隙插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。该来源字面量在本地重述，因为 `dsh-compact` 在两个方向上都无法从本程序到达（客户端纯度门禁拒绝值导入；仅类型导入会与 host 的 `Context.sessions` 合并冲突）——`tests/compact-checkpoint-pin.spec.ts` 是漂移陷阱。 + +由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时该行不可展开而非空白，后续补上溯源的分页会解析出文本。性能契约：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。 + ## Code Mode 子调用索引 -`ConversationSnapshot.codeDispatches` 按父调用的 callId 和启动顺序，用原生调用块形状组织一个 `run_code` 调用的子调用：`tool/code-dispatch-start` 事件落成 `RunningToolCall` 形状（行组件从该形状推导运行中的转圈状态），其 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode` 形状，`callTime` 携带成对 start 事件的时间。start 落在回放窗口之外的完结事件则直接追加，`callTime: null`（耗时未知——绝不伪造零耗时）。live mux 帧与历史回放构建相同的索引；子调用永不进入 surface `nodes` 流；无关快照交换不会改变每个父调用对应的数组引用和映射引用，两者均保持 memo 稳定。 +`ConversationSnapshot.codeDispatches` 按父调用的 callId 和启动顺序，用原生调用块形状组织一个 `run_code` 调用的子调用：`tool/code-dispatch-start` 事件落成 `RunningToolCall` 形状（行组件从该形状推导运行中的转圈状态），其 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode` 形状，`callTime` 携带成对 start 事件的时间。start 落在回放窗口之外的完结事件则直接追加，`callTime: null`（耗时未知——绝不伪造零耗时）。live mux 帧与历史回放构建相同的索引；子调用永不进入对话记录 `nodes` 流；无关快照交换不会改变每个父调用对应的数组引用和映射引用，两者均保持 memo 稳定。 ## Session 标题投影 diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json index 60e2eddf09..3868ab8d8c 100644 --- a/packages/client/runtime/package.json +++ b/packages/client/runtime/package.json @@ -48,6 +48,7 @@ "cordis": "^4.0.0-rc.7" }, "devDependencies": { + "@deepseek-ai/dsh-compact": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@types/react": "~18.3.1", "cordis": "^4.0.0-rc.7" diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts index 3b8e02b5a9..c548c03502 100644 --- a/packages/client/runtime/src/client/index.ts +++ b/packages/client/runtime/src/client/index.ts @@ -38,8 +38,8 @@ export type { EngineStoreHandle, EngineStoreInstance, ObservableSnapshot, SnapshotStore, } from './contract/store.ts' export type { - AssistantBlock, AssistantMessageNode, CodeSubCall, CommandNode, ComposerPhase, ContextMessageNode, ConversationNode, - ConversationSnapshot, QueuedMessage, RunningToolCall, + AssistantBlock, AssistantMessageNode, CodeSubCall, CommandNode, CompactionSummaryNode, ComposerPhase, + ContextMessageNode, ConversationNode, ConversationSnapshot, QueuedMessage, RunningToolCall, SteeringMessageNode, TodoItem, ToolResultNode, UnknownSurfaceNode, UserMessageNode, } from './sessions/conversation.ts' export { PendingWait } from './sessions/pending.ts' diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts index f5f0717236..fc9a9d6bcd 100644 --- a/packages/client/runtime/src/client/sessions/conversation.ts +++ b/packages/client/runtime/src/client/sessions/conversation.ts @@ -111,6 +111,24 @@ export interface ToolResultNode { resultView: ToolResultView | null } +/** + * One landed compaction, marked at the checkpoint's own log position. The + * conversation it shadowed on the model surface stays in the transcript above + * it: the marker reports where the model stopped seeing that history, it does + * not replace it. The framed checkpoint payload is an instruction envelope + * written for the model and never renders. + */ +export interface CompactionSummaryNode { + kind: 'compaction' + /** Seq of the replacement `user/message` that landed the checkpoint. */ + seq: number + /** Unix epoch ms of the checkpoint event. */ + time: number + /** Summary text from the checkpoint's `compact/summary` provenance; null when + * the window cut left that provenance outside (the marker is then not expandable). */ + summary: string | null +} + /** Fallback for surface events this UI version does not know. */ export interface UnknownSurfaceNode { kind: 'unknown' @@ -124,7 +142,7 @@ export interface UnknownSurfaceNode { /** * One slash-command lifecycle folded from the log-only `command/run` / * `command/done` pair (paired by commandId, mirroring tool call↔result). - * Log-only events never enter the surface fold, so the FoldAdapter indexes + * Log-only events are not surface events, so the TranscriptAdapter indexes * them separately and merges the nodes into the flow by seq. A window cut * between the pair soft-falls like tool pairs: a done with no in-window run * still builds a node (name/args null), and a run with no done renders as @@ -154,6 +172,7 @@ export type ConversationNode = | ContextMessageNode | ToolResultNode | CommandNode + | CompactionSummaryNode | UnknownSurfaceNode /** @@ -163,7 +182,7 @@ export type ConversationNode = * {@link RunningToolCall} (rows derive the running state from the shape, * exactly as for native calls) and its `tool/code-dispatch` settlement * replaces it in place with the {@link ToolResultNode} form. Never part of - * the surface `nodes` flow — sub-calls live under their parent via + * the transcript `nodes` flow — sub-calls live under their parent via * {@link ConversationSnapshot.codeDispatches}. `callId` is the deterministic * sub-call id (`:code:`); the call side carries the sub-tool name * and its JSON-stringified logged arguments; `content`/`isError` are the @@ -232,10 +251,8 @@ export interface PromptError { /** The immutable snapshot contract Session hands to uSES (see the web client architecture RFC). */ export interface ConversationSnapshot { sessionId: SessionId - /** Surface fold product (finalized conversation nodes in surface order). */ + /** Human transcript (finalized conversation nodes in log order). */ nodes: readonly ConversationNode[] - /** Fold degradation flag (cross-window replace defense): when true, nodes come from the lenient linear scan. */ - foldDegraded: boolean partial: PartialAssistant | null runningCalls: readonly RunningToolCall[] /** diff --git a/packages/client/runtime/src/client/sessions/fold-adapter.ts b/packages/client/runtime/src/client/sessions/fold-adapter.ts deleted file mode 100644 index 039c36056b..0000000000 --- a/packages/client/runtime/src/client/sessions/fold-adapter.ts +++ /dev/null @@ -1,275 +0,0 @@ -// FoldAdapter: core SurfaceManager wiring + node materialization cache. -// Padding sentinels solve the paged-window seq offset (core fold asserts seq === index); -// a cross-window replace throw degrades to a lenient linear scan (foldDegraded — -// the degradation lives in one branch function in this file, zero scattered removal points). - -import type { SessionEvent } from '@deepseek-ai/dsh-session/types' -// Subpath export (package.json exports "./surface", alias added for this): all value imports -// go through it — the package root points at lib/index.js (needs a build) which the vite -// browser bundle cannot resolve; surface.ts has no Node dependencies. -import { SurfaceManager, isSurfaceEligibleType } from '@deepseek-ai/dsh-session/surface' -import type { CommandId } from '@deepseek-ai/dsh-commands/brand' -import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client' -import type { CommandNode, ConversationNode } from './conversation.ts' -import { toAssistantBlocks } from './conversation.ts' - -/** In-window tool/call index entry (result-card backfill + runningCalls material). */ -export interface CallIndexEntry { - name: string - argsRaw: string - turn: number - step: number - /** Unix epoch ms of the tool/call event. */ - time: number - /** Wire view riding the tool/call (envelope-level; never inside the event). */ - callView: ToolCallView | null -} - -/** Non-surface sentinel used to preserve paged-window sequence offsets. - * `noop/padding` is deliberately not a real event type, so it cannot acquire - * surface behavior; this cast is the only synthetic event entry point. - */ -function paddingEvent(seq: number): SessionEvent { - return { type: 'noop/padding', seq, time: 0, data: {} } as unknown as SessionEvent -} - -/** One event -> UI node (pure function; the six-variant ConversationNode union). */ -function materializeNode( - event: SessionEvent, - callIndex: ReadonlyMap, - resultView: ToolResultView | null, -): ConversationNode { - switch (event.type) { - case 'user/message': - // Injected context (plugin/goal source) folds to a context node, not a - // user message; only a direct human prompt is a user node. - if (event.data.source.kind !== 'user') { - return { - kind: 'context', seq: event.seq, time: event.time, - content: event.data.content, source: event.data.source, - } - } - return { - kind: 'user', seq: event.seq, time: event.time, - content: event.data.content, source: event.data.source, - } - case 'assistant/message': - return { - kind: 'assistant', seq: event.seq, time: event.time, - turn: event.data.turn, step: event.data.step, - blocks: toAssistantBlocks(event.data.message.content), usage: event.data.usage, - } - case 'steering/message': - return { - kind: 'steering', seq: event.seq, time: event.time, turn: event.data.turn, - content: event.data.message.content, source: event.data.message.source, - } - case 'tool/result': { - const result = event.data.message.content[0] - const callId = String(event.data.message.source.callId) - const call = callIndex.get(callId) - return { - kind: 'tool-result', seq: event.seq, time: event.time, - callId, - call: call ? { name: call.name, argsRaw: call.argsRaw } : null, - callTime: call?.time ?? null, - content: result.content, isError: result.isError === true, - ...(event.data.error !== undefined ? { error: event.data.error } : {}), - meta: event.data.meta, - callView: call?.callView ?? null, - resultView, - } - } - /* v8 ignore next 2 -- defensive arm: fold output only carries the four - surface-eligible types, and each has a case above; reachable only if core - adds an eligible type. */ - default: - return { - kind: 'unknown', seq: event.seq, time: event.time, - type: event.type, data: (event as { data?: unknown }).data, - } - } -} - -/** Window fold over the core SurfaceManager (sentinel padding for the seq offset; degrades to a linear scan on cross-window replace). */ -export class FoldAdapter { - /** padded = [sentinel x baseSeq, ...window events]; SurfaceManager borrows this reference for lazy incremental folding. */ - private padded: SessionEvent[] = [] - private baseSeq = 0 - private surface = new SurfaceManager(this.padded) - private nodeCache = new Map() - private degraded = false - private callIdx = new Map() - /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */ - private resultViews = new Map() - /** - * Command lifecycle nodes by commandId (insertion = run order). The - * `command/run`/`command/done` pair is log-only, so the surface fold never - * emits it; this index folds the pair (done settles its run's node in - * place) and nodes() merges the products into the flow by seq. Window cuts - * soft-fall like tool pairs: a done with no in-window run still builds a - * node. - */ - private commandIdx = new Map() - /** Window revision (bumped on reset/append) keying the nodes() result cache: an unchanged - * window returns the previous ARRAY reference, not just cached elements — the snapshot's - * reference-stability contract (§A.9.4) starts here. */ - private rev = 0 - private nodesResult: { rev: number; value: { nodes: ConversationNode[]; degraded: boolean } } | null = null - - /** In-window tool/call index (Session uses it for runningCalls and result-card backfill). */ - get callIndex(): ReadonlyMap { - return this.callIdx - } - - /** - * Window rebuild (after open/resync/page prepend): new padded array, new - * SurfaceManager, cleared cache, rebuilt callIndex. - * @param events - the new window contents (seq-ascending). - * @param baseSeq - seq of the window head (sentinels pad below it). - * @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events). - */ - reset(events: readonly SessionEvent[], baseSeq: number, views?: readonly (ToolEventView | undefined)[]): void { - this.rev++ - this.baseSeq = baseSeq - this.padded = [] - for (let i = 0; i < baseSeq; i++) this.padded.push(paddingEvent(i)) - for (const event of events) this.padded.push(event) - this.surface = new SurfaceManager(this.padded) - this.nodeCache.clear() - this.degraded = false - this.callIdx = new Map() - this.resultViews.clear() - this.commandIdx = new Map() - for (let i = 0; i < events.length; i++) { - const event = events[i] - /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */ - if (event !== undefined) { - this.indexCall(event, views?.[i]) - this.indexCommand(event) - } - } - } - - /** - * Tail append (live session/event): push into the same array (incremental - * lazy fold applies) + incremental callIndex upkeep. - * @param event - the live event (seq = window tail + 1). - * @param view - host-computed tool view paired with the event when it is a tool call/result; indexed for card rendering. - */ - append(event: SessionEvent, view?: ToolEventView): void { - this.rev++ - this.padded.push(event) - this.indexCall(event, view) - this.indexCommand(event) - } - - /** - * Current node array + degradation flag. Same revision -> same array - * reference (memo boundary); node object references always come from the per-seq cache. - * @returns the fold projection for the current window revision. - */ - nodes(): { nodes: ConversationNode[]; degraded: boolean } { - if (this.nodesResult !== null && this.nodesResult.rev === this.rev) return this.nodesResult.value - let seqs: readonly number[] - if (this.degraded) { - seqs = this.degradedSeqs() - } else { - try { - seqs = this.surface.nodes - } catch (error) { - console.error('[web-runtime] surface fold failed, degrading to linear scan:', error) - this.degraded = true - seqs = this.degradedSeqs() - } - } - const out: ConversationNode[] = [] - for (const seq of seqs) { - const cached = this.nodeCache.get(seq) - if (cached !== undefined) { - out.push(cached) - continue - } - const event = this.padded[seq] - /* v8 ignore next -- sparse guard: both seq sources (surface fold and degradedSeqs) only emit indexes present in padded. */ - if (event === undefined) continue - const node = materializeNode(event, this.callIdx, this.resultViews.get(seq) ?? null) - this.nodeCache.set(seq, node) - out.push(node) - } - // Command nodes fold outside the surface (log-only events); merge by seq. - // Both inputs are seq-ascending (surface order and run-index insertion - // order share the log order), so one linear merge keeps flow order. - let nodes = out - if (this.commandIdx.size > 0) { - nodes = [] - const commands = [...this.commandIdx.values()] - let next = 0 - for (const node of out) { - for (let cmd = commands[next]; cmd !== undefined && cmd.seq < node.seq; cmd = commands[++next]) { - nodes.push(cmd) - } - nodes.push(node) - } - for (let cmd = commands[next]; cmd !== undefined; cmd = commands[++next]) nodes.push(cmd) - } - const value = { nodes, degraded: this.degraded } - this.nodesResult = { rev: this.rev, value } - return value - } - - /** Degradation branch: lenient linear scan ignoring surfaceOp/replace (all surface-eligible events in append order). */ - private degradedSeqs(): number[] { - const seqs: number[] = [] - for (let i = this.baseSeq; i < this.padded.length; i++) { - const event = this.padded[i] - if (event !== undefined && isSurfaceEligibleType(event.type)) seqs.push(event.seq) - } - return seqs - } - - /** Fold one command lifecycle event into its node (run mints, done settles in place; done-only soft-falls). */ - private indexCommand(event: SessionEvent): void { - // Log-only plugin events: the host-side dsh-commands declaration cannot - // enter the client program, so this wire consumer narrows structurally - // (the same posture as tool/code-dispatch in session.ts). - if ((event.type as string) === 'command/run') { - const data = event.data as unknown as { commandId: CommandId; name: string; args: string } - this.commandIdx.set(data.commandId, { - kind: 'command', seq: event.seq, time: event.time, - commandId: data.commandId, name: data.name, args: data.args, outcome: null, - }) - return - } - if ((event.type as string) !== 'command/done') return - const data = event.data as unknown as { commandId: CommandId; kind: 'success' | 'error'; text?: string } - const run = this.commandIdx.get(data.commandId) - const outcome = { kind: data.kind, ...data.text === undefined ? {} : { text: data.text } } - if (run === undefined) { - // Cross-window cut: the run page fell out of the window — build the - // node from the done alone (same soft-fall as a call-less tool result). - this.commandIdx.set(data.commandId, { - kind: 'command', seq: event.seq, time: event.time, - commandId: data.commandId, name: null, args: null, outcome, - }) - return - } - // Settle in place: a fresh node object (published references stay immutable). - this.commandIdx.set(data.commandId, { ...run, outcome }) - } - - private indexCall(event: SessionEvent, view?: ToolEventView): void { - if (event.type === 'tool/result') { - if (view?.for === 'result') this.resultViews.set(event.seq, view.view) - return - } - if (event.type !== 'tool/call') return - this.callIdx.set(String(event.data.callId), { - name: event.data.name, argsRaw: event.data.arguments, turn: event.data.turn, step: event.data.step, - time: event.time, - callView: view?.for === 'call' ? view.view : null, - }) - // No backfill into already-materialized tool-result nodes for this callId - // (window order puts the call before its result; cannot happen on the normal path). - } -} diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts index 0f5d39ac8e..9927f0e171 100644 --- a/packages/client/runtime/src/client/sessions/session.ts +++ b/packages/client/runtime/src/client/sessions/session.ts @@ -17,7 +17,7 @@ import type { } from './conversation.ts' import type { PendingInteraction } from './pending.ts' import { PendingWait } from './pending.ts' -import { FoldAdapter } from './fold-adapter.ts' +import { TranscriptAdapter } from './transcript-adapter.ts' import { Notifier } from './notifier.ts' import { PartialAccumulator } from './partial.ts' import { ProjectionValueStore } from './projection-store.ts' @@ -87,11 +87,13 @@ export class Session implements SessionFace { * passes drop all writes once the generation moves on. */ private openGeneration = 0 private loadingOlder = false - private readonly foldAdapter = new FoldAdapter() + private readonly transcript = new TranscriptAdapter() private partial: PartialAccumulator | null = null private openCalls = new Map() /** Interrupted-turn terminal nodes (frozen partial text / aborted tool cards), merged into the flow by seq. - * Derived from window events (turn/end sweep) — rebuilt by rebuildDerivedFromWindow like partial/openCalls. */ + * Derived from window events (turn/end sweep) — rebuilt by rebuildDerivedFromWindow like partial/openCalls. + * Owned here rather than by the adapter: these nodes come from the turn/end sweep this class already + * runs over the window, and the transcript array is seq-monotonic, so a plain seq merge is correct. */ private frozenNodes: ConversationNode[] = [] private pending = new Map() // Revision counters preserve array identity when derived content is unchanged, so @@ -108,7 +110,7 @@ export class Session implements SessionFace { private queueRev = 0 private queueCache: { rev: number; value: QueuedMessage[] } | null = null private frozenRev = 0 - private nodesCache: { folded: readonly ConversationNode[]; frozenRev: number; value: readonly ConversationNode[] } | null = null + private nodesCache: { projected: readonly ConversationNode[]; frozenRev: number; value: readonly ConversationNode[] } | null = null /** `run_code` sub-dispatches by parent callId (window-derived, like openCalls). Appends * copy-on-write the per-parent array so published snapshot references never mutate. */ private codeDispatches = new Map() @@ -306,7 +308,7 @@ export class Session implements SessionFace { /* v8 ignore next -- the ?? arm needs older[0] undefined, but the empty-page branch above already returned. */ this.baseSeq = older[0]?.event.seq ?? this.baseSeq this.hasMore = result.value.hasMore - this.foldAdapter.reset(this.events, this.baseSeq, this.views) // prepend forces a rebuild (sentinel count changed) + this.transcript.reset(this.events, this.views) // prepend forces a rebuild (the window grew at the head) this.rebuildDerivedFromWindow() } catch (error) { console.error('[web-runtime] loadOlder failed:', error) @@ -553,7 +555,7 @@ export class Session implements SessionFace { this.views = entries.map(e => e.view) this.baseSeq = this.events[0]?.seq ?? 0 this.hasMore = hasMore - this.foldAdapter.reset(this.events, this.baseSeq, this.views) + this.transcript.reset(this.events, this.views) this.rebuildDerivedFromWindow() if (projections !== undefined) this.projections.seed(projections) const buffered = this.liveBuffer @@ -568,14 +570,15 @@ export class Session implements SessionFace { if (tailSeq !== null && event.seq <= tailSeq) return // replay overlap, drop this.events.push(event) this.views.push(view) - this.foldAdapter.append(event, view) + this.transcript.append(event, view) this.applyEventSideEffects(event, view) } /** Land a live session/event (open/repair in flight -> buffer; overlapping seq -> drop; * a seq gap -> buffer + tail-page repull instead of appending a hole (audit S3: a gap is an - * expected reconnect-window artifact, repaired by refetch — never fed to the fold to trip - * its continuity assertion into the degraded view). */ + * expected reconnect-window artifact, repaired by refetch). The window stays one contiguous + * raw range, which is what lets the transcript render every event between its ends and lets a + * compaction checkpoint find its own provenance. */ private acceptLiveEvent(event: SessionEvent, view?: ToolEventView): void { if (this.openState === 'loading' || this.stitching) { this.liveBuffer.push({ event, view }) @@ -790,18 +793,19 @@ export class Session implements SessionFace { } private buildSnapshot(): ConversationSnapshot { - const { nodes: folded, degraded } = this.foldAdapter.nodes() + const projected = this.transcript.nodes() // Frozen interrupted nodes ride fractional seqs: a stable merge keeps them in flow order. - // The merged array is cached on (folded reference, frozenRev) so an unchanged flow keeps its - // reference across snapshot swaps (§A.9.4). + // The transcript is seq-monotonic (log order), so sorting the union by seq is exactly the + // flow order. The merged array is cached on (projected reference, frozenRev) so an unchanged + // flow keeps its reference across snapshot swaps (§A.9.4). let nodes: readonly ConversationNode[] - if (this.nodesCache !== null && this.nodesCache.folded === folded && this.nodesCache.frozenRev === this.frozenRev) { + if (this.nodesCache !== null && this.nodesCache.projected === projected && this.nodesCache.frozenRev === this.frozenRev) { nodes = this.nodesCache.value } else { nodes = this.frozenNodes.length === 0 - ? folded - : [...folded, ...this.frozenNodes].sort((a, b) => a.seq - b.seq) - this.nodesCache = { folded, frozenRev: this.frozenRev, value: nodes } + ? projected + : [...projected, ...this.frozenNodes].sort((a, b) => a.seq - b.seq) + this.nodesCache = { projected, frozenRev: this.frozenRev, value: nodes } } if (this.callsCache === null || this.callsCache.rev !== this.callsRev) { this.callsCache = { rev: this.callsRev, value: [...this.openCalls.values()] } @@ -819,7 +823,6 @@ export class Session implements SessionFace { return { sessionId: this.sessionId, nodes, - foldDegraded: degraded, partial, runningCalls: this.callsCache.value, pending: this.pendingCache.value, diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts new file mode 100644 index 0000000000..b79e6ee2fe --- /dev/null +++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts @@ -0,0 +1,325 @@ +// TranscriptAdapter: the human transcript projected from the raw event window +// in LOG order. The model-visible surface deliberately shadows replaced ranges, +// so it is the wrong source for conversation a reader already saw; this adapter +// keeps every append-origin event at its own log position and contributes one +// marker node per landed compaction checkpoint. Node order is therefore +// seq-monotonic by construction — no surface fold, no padding sentinels, no +// seq === index assertion to satisfy, and no degradation branch. + +import type { SessionEvent } from '@deepseek-ai/dsh-session/types' +// Subpath export (package.json exports "./surface", alias added for this): all value imports +// go through it — the package root points at lib/index.js (needs a build) which the vite +// browser bundle cannot resolve; surface.ts has no Node dependencies. +import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface' +import type { CommandId } from '@deepseek-ai/dsh-commands/brand' +import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client' +import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts' +import { toAssistantBlocks } from './conversation.ts' + +/** + * The compaction seam's checkpoint plugin, restated locally. + * + * `dsh-compact` cannot be reached from this program in any form. A VALUE import + * fails the client purity gate (`packages/client/tsdown.client.ts`) and would + * pull the cordis `Service` base into the browser bundle; a TYPE-ONLY import of + * its `COMPACT_CHECKPOINT_SOURCE` fails typecheck, because `dsh-compact`'s root + * reaches `dsh-session`'s root, whose `Context` merge declares the HOST + * `sessions: SessionStore` against this program's `sessions: ISessions` + * (`TS2717` — the one-program-per-side rule in docs/development.md). The + * literal is pinned to the canonical const by + * `tests/compact-checkpoint-pin.spec.ts`, which runs in the client TEST program + * where that collision does not apply. + */ +const COMPACT_PLUGIN = 'compact' + +/** In-window tool/call index entry (result-card backfill + runningCalls material). */ +export interface CallIndexEntry { + name: string + argsRaw: string + turn: number + step: number + /** Unix epoch ms of the tool/call event. */ + time: number + /** Wire view riding the tool/call (envelope-level; never inside the event). */ + callView: ToolCallView | null +} + +/** One event -> UI node (pure function; the eight-variant ConversationNode union). */ +function materializeNode( + event: SessionEvent, + callIndex: ReadonlyMap, + resultView: ToolResultView | null, +): ConversationNode { + switch (event.type) { + case 'user/message': + // Injected context (plugin/goal source) folds to a context node, not a + // user message; only a direct human prompt is a user node. A compaction + // checkpoint never reaches here (isCompactCheckpoint routes it away). + if (event.data.source.kind !== 'user') { + return { + kind: 'context', seq: event.seq, time: event.time, + content: event.data.content, source: event.data.source, + } + } + return { + kind: 'user', seq: event.seq, time: event.time, + content: event.data.content, source: event.data.source, + } + case 'assistant/message': + return { + kind: 'assistant', seq: event.seq, time: event.time, + turn: event.data.turn, step: event.data.step, + blocks: toAssistantBlocks(event.data.message.content), usage: event.data.usage, + } + case 'steering/message': + return { + kind: 'steering', seq: event.seq, time: event.time, turn: event.data.turn, + content: event.data.message.content, source: event.data.message.source, + } + case 'tool/result': { + const result = event.data.message.content[0] + const callId = String(event.data.message.source.callId) + const call = callIndex.get(callId) + return { + kind: 'tool-result', seq: event.seq, time: event.time, + callId, + call: call ? { name: call.name, argsRaw: call.argsRaw } : null, + callTime: call?.time ?? null, + content: result.content, isError: result.isError === true, + ...(event.data.error !== undefined ? { error: event.data.error } : {}), + meta: event.data.meta, + callView: call?.callView ?? null, + resultView, + } + } + /* v8 ignore next 2 -- defensive arm: only the four surface-eligible types + can be append-origin, and each has a case above; reachable only if core + adds an eligible type. */ + default: + return { + kind: 'unknown', seq: event.seq, time: event.time, + type: event.type, data: (event as { data?: unknown }).data, + } + } +} + +/** + * Whether an event is a landed compaction checkpoint — all three conditions, + * matching the terminal's `isCompactCheckpoint`: a `user/message`, carrying the + * compaction seam's checkpoint plugin source, that REPLACED a surface range. A + * plugin-sourced `user/message` that appends is injected context (a + * session-reference card), not a compaction; a replacement `tool/result` is an + * in-place prune and a replacement `assistant/message` a generic rewrite, and + * both mark no boundary in the conversation. + * @param event - the raw window event. + * @returns true when the event compacted a surface range. + */ +function isCompactCheckpoint(event: SessionEvent): boolean { + if (event.type !== 'user/message') return false + const source = event.data.source + return source.kind === 'plugin' && source.plugin === COMPACT_PLUGIN + && isReplacementSurfaceEvent(event) +} + +/** Whether an event contributes a node to the human transcript. */ +function isTranscriptEvent(event: SessionEvent): boolean { + return isAppendSurfaceEvent(event) || isCompactCheckpoint(event) +} + +/** Concatenated text of a `compact/summary` payload, or null when it carries no usable text. */ +function compactSummaryText(event: SessionEvent): string | null { + const summary = (event.data as unknown as { summary?: unknown }).summary + if (!Array.isArray(summary) || summary.length === 0) return null + let text = '' + for (const block of summary as readonly unknown[]) { + const candidate = block as { type?: unknown; text?: unknown } + if (candidate.type !== 'text' || typeof candidate.text !== 'string') return null + text += candidate.text + } + return text.trim() === '' ? null : text +} + +/** + * One landed checkpoint -> the human-facing compaction marker. The summary text + * comes from the checkpoint's own provenance (`sourceEventSeqs` names the + * `compact/summary` event), never from the framed checkpoint payload, which is + * an instruction envelope written for the model. A window cut that left the + * provenance outside soft-falls to `summary: null` (a non-expandable marker), + * the same posture as a call-less tool result. + */ +function materializeCompaction( + checkpoint: SessionEvent, + eventIndex: ReadonlyMap, +): CompactionSummaryNode { + const sources = (checkpoint as SessionEvent & { sourceEventSeqs?: number[] }).sourceEventSeqs + let summary: string | null = null + for (const seq of sources ?? []) { + const candidate = eventIndex.get(seq) + if (candidate === undefined || (candidate.type as string) !== 'compact/summary') continue + summary = compactSummaryText(candidate) + break + } + return { kind: 'compaction', seq: checkpoint.seq, time: checkpoint.time, summary } +} + +/** Log-ordered human transcript over a paged raw event window (never consults surface order). */ +export class TranscriptAdapter { + /** Window events by seq: provenance lookup for a checkpoint's summary. */ + private eventIndex = new Map() + /** Transcript nodes in log order; copy-on-write so a published array never mutates. */ + private projected: ConversationNode[] = [] + private callIdx = new Map() + /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */ + private resultViews = new Map() + /** + * Command lifecycle nodes by commandId (insertion = run order). The + * `command/run`/`command/done` pair is log-only, so it is not a surface + * event and never joins the transcript projection; this index folds the pair + * (done settles its run's node in place) and nodes() merges the products in + * by seq. Window cuts soft-fall like tool pairs: a done with no in-window + * run still builds a node. + */ + private commandIdx = new Map() + /** Projection revision, bumped only when a transcript node or a command node actually + * changed, keying the nodes() result cache: an unchanged projection returns the previous + * ARRAY reference, not just cached elements — the snapshot's reference-stability contract + * (§A.9.4) starts here, and a chunk storm bumps nothing at all. */ + private rev = 0 + private nodesResult: { rev: number; value: readonly ConversationNode[] } | null = null + + /** In-window tool/call index (Session uses it for runningCalls and result-card backfill). */ + get callIndex(): ReadonlyMap { + return this.callIdx + } + + /** + * Window rebuild (after open/resync/page prepend): re-index the raw window + * and re-project the transcript. + * @param events - the new window contents (seq-ascending). + * @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events). + */ + reset(events: readonly SessionEvent[], views?: readonly (ToolEventView | undefined)[]): void { + this.rev++ + this.eventIndex = new Map() + this.callIdx = new Map() + this.resultViews.clear() + this.commandIdx = new Map() + for (let i = 0; i < events.length; i++) { + const event = events[i] + /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */ + if (event === undefined) continue + this.eventIndex.set(event.seq, event) + this.indexCall(event, views?.[i]) + this.indexCommand(event) + } + // Indexes first, then project: a tool/result materializes against the + // complete call index, and a checkpoint against the complete event index. + const projected: ConversationNode[] = [] + for (const event of events) { + if (isTranscriptEvent(event)) projected.push(this.materialize(event)) + } + this.projected = projected + } + + /** + * Tail append (live session/event): index the event and, when it belongs to + * the transcript, extend the projection by one node — O(1) per append. An + * event that changes no node (a chunk storm) bumps no revision, so nodes() + * keeps returning the same array reference. + * @param event - the live event (seq = window tail + 1). + * @param view - host-computed tool view paired with the event when it is a tool call/result; indexed for card rendering. + */ + append(event: SessionEvent, view?: ToolEventView): void { + this.eventIndex.set(event.seq, event) + this.indexCall(event, view) + if (this.indexCommand(event)) this.rev++ + if (!isTranscriptEvent(event)) return + this.projected = [...this.projected, this.materialize(event)] + this.rev++ + } + + /** + * The current transcript node array. Same revision -> same array reference + * (memo boundary); node objects are materialized once, so an unchanged node + * keeps its identity across appends. + * @returns transcript nodes in log order, command nodes merged in by seq. + */ + nodes(): readonly ConversationNode[] { + if (this.nodesResult !== null && this.nodesResult.rev === this.rev) return this.nodesResult.value + // Command nodes fold outside the transcript (log-only events); merge by + // seq. Both inputs are seq-ascending (log order and run-index insertion + // order are the same order), so one linear merge keeps flow order. + let nodes = this.projected + if (this.commandIdx.size > 0) { + nodes = [] + const commands = [...this.commandIdx.values()] + let next = 0 + for (const node of this.projected) { + for (let cmd = commands[next]; cmd !== undefined && cmd.seq < node.seq; cmd = commands[++next]) { + nodes.push(cmd) + } + nodes.push(node) + } + for (let cmd = commands[next]; cmd !== undefined; cmd = commands[++next]) nodes.push(cmd) + } + this.nodesResult = { rev: this.rev, value: nodes } + return nodes + } + + /** Materialize one transcript event against the complete current indexes. */ + private materialize(event: SessionEvent): ConversationNode { + return isCompactCheckpoint(event) + ? materializeCompaction(event, this.eventIndex) + : materializeNode(event, this.callIdx, this.resultViews.get(event.seq) ?? null) + } + + /** + * Fold one command lifecycle event into its node (run mints, done settles in + * place; done-only soft-falls). + * @returns whether the command index changed, so callers can bump the revision. + */ + private indexCommand(event: SessionEvent): boolean { + // Log-only plugin events: the host-side dsh-commands declaration cannot + // enter the client program, so this wire consumer narrows structurally + // (the same posture as tool/code-dispatch in session.ts). + if ((event.type as string) === 'command/run') { + const data = event.data as unknown as { commandId: CommandId; name: string; args: string } + this.commandIdx.set(data.commandId, { + kind: 'command', seq: event.seq, time: event.time, + commandId: data.commandId, name: data.name, args: data.args, outcome: null, + }) + return true + } + if ((event.type as string) !== 'command/done') return false + const data = event.data as unknown as { commandId: CommandId; kind: 'success' | 'error'; text?: string } + const run = this.commandIdx.get(data.commandId) + const outcome = { kind: data.kind, ...data.text === undefined ? {} : { text: data.text } } + if (run === undefined) { + // Cross-window cut: the run page fell out of the window — build the + // node from the done alone (same soft-fall as a call-less tool result). + this.commandIdx.set(data.commandId, { + kind: 'command', seq: event.seq, time: event.time, + commandId: data.commandId, name: null, args: null, outcome, + }) + return true + } + // Settle in place: a fresh node object (published references stay immutable). + this.commandIdx.set(data.commandId, { ...run, outcome }) + return true + } + + private indexCall(event: SessionEvent, view?: ToolEventView): void { + if (event.type === 'tool/result') { + if (view?.for === 'result') this.resultViews.set(event.seq, view.view) + return + } + if (event.type !== 'tool/call') return + this.callIdx.set(String(event.data.callId), { + name: event.data.name, argsRaw: event.data.arguments, turn: event.data.turn, step: event.data.step, + time: event.time, + callView: view?.for === 'call' ? view.view : null, + }) + // No backfill into already-materialized tool-result nodes for this callId + // (window order puts the call before its result; cannot happen on the normal path). + } +} diff --git a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts new file mode 100644 index 0000000000..c657ebd036 --- /dev/null +++ b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts @@ -0,0 +1,52 @@ +/** + * Drift trap for the compaction-checkpoint recognition rule. + * + * `TranscriptAdapter` restates the compaction seam's checkpoint source as a + * local literal because it cannot import `dsh-compact` in any form: a VALUE + * import fails the client purity gate, and a TYPE-ONLY import fails typecheck — + * `dsh-compact`'s root reaches `dsh-session`'s root, whose cordis `Context` + * merge declares the HOST `sessions: SessionStore` against the client program's + * `sessions: ISessions` (`TS2717`). This spec runs in the client TEST program, + * which does not carry that collision, and it is the only thing keeping the two + * implementations from drifting: it drives the adapter with a checkpoint built + * from the canonical `COMPACT_CHECKPOINT_SOURCE` itself, so renaming the seam's + * plugin fails HERE instead of silently deleting every compaction marker from + * the web transcript. + */ + +import { COMPACT_CHECKPOINT_SOURCE, isCompactCheckpointSource } from '@deepseek-ai/dsh-compact' +import { createUserMessage } from '@deepseek-ai/dsh-llm' +import { describe, expect, it } from 'vitest' +import type { SessionEvent } from '@deepseek-ai/dsh-session/types' +import { TranscriptAdapter } from '../src/client/sessions/transcript-adapter.ts' + +/** A replacement user message stamped with the seam's own canonical source. */ +function canonicalCheckpoint(seq: number): SessionEvent { + return { + type: 'user/message', + seq, + time: 1_700_000_000_000 + seq, + surfaceOp: { op: 'replace', start: 0, end: 0 }, + sourceEventSeqs: [0], + data: createUserMessage({ + content: [{ type: 'text', text: 'model only' }], + source: COMPACT_CHECKPOINT_SOURCE, + }), + } as unknown as SessionEvent +} + +describe('compaction checkpoint recognition', () => { + it('recognizes a checkpoint carrying the seam-canonical source', () => { + const adapter = new TranscriptAdapter() + adapter.reset([canonicalCheckpoint(1)]) + expect(adapter.nodes()).toEqual([{ kind: 'compaction', seq: 1, time: 1_700_000_000_001, summary: null }]) + }) + + it('agrees with the seam s own predicate on the source it recognizes', () => { + // Both sides answer the same question about the same value: if the seam + // renames its plugin, this equality is what breaks. + const checkpoint = canonicalCheckpoint(1) + expect(checkpoint.type === 'user/message' && isCompactCheckpointSource(checkpoint.data.source)).toBe(true) + expect(COMPACT_CHECKPOINT_SOURCE).toEqual({ kind: 'plugin', plugin: 'compact' }) + }) +}) diff --git a/packages/client/runtime/tests/event-script.ts b/packages/client/runtime/tests/event-script.ts index 53f80e0e69..f92ee787f4 100644 --- a/packages/client/runtime/tests/event-script.ts +++ b/packages/client/runtime/tests/event-script.ts @@ -69,6 +69,27 @@ export const ev = { at(seq, { type: 'command/run', data: { commandId, name, args, source: { kind: 'user' } } }), commandDone: (seq: number, commandId: string, kind: 'success' | 'error' = 'success', text?: string): SessionEvent => at(seq, { type: 'command/done', data: { commandId, kind, ...text === undefined ? {} : { text } } }), + /** A compaction's log-only `compact/summary` provenance record. */ + compactSummary: (seq: number, summary: string, start: number, end: number): SessionEvent => + at(seq, { type: 'compact/summary', data: { + summary: text(summary), + shadowedRange: { start, end }, + shadowedSeqs: [start, end], + shadowedTokenCount: 100, + provider: 'fake', + model: 'compact-1', + } }), + /** The replacement user message a compaction backend lands (the checkpoint). */ + compactCheckpoint: (seq: number, summarySeq: number, start: number, end: number): SessionEvent => + at(seq, { + type: 'user/message', + surfaceOp: { op: 'replace', start, end }, + sourceEventSeqs: [summarySeq, start, end], + data: createUserMessage({ + content: text('model only'), + source: { kind: 'plugin', plugin: 'compact' }, + }), + }), } /** One complete plain turn (turn/start → user → step → assistant → turn/end), 6 events from startSeq. */ diff --git a/packages/client/runtime/tests/fold-adapter.spec.ts b/packages/client/runtime/tests/fold-adapter.spec.ts deleted file mode 100644 index b40bdb4111..0000000000 --- a/packages/client/runtime/tests/fold-adapter.spec.ts +++ /dev/null @@ -1,251 +0,0 @@ -import { createUserMessage, CallId, createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm' -/** - * FoldAdapter over the real core SurfaceManager: padding sentinels for paged - * windows, incremental append with node-cache identity, six-variant - * materialization, call-index backfill, and the degraded linear-scan branch. - */ - -import { describe, expect, it, vi } from 'vitest' -import type { SessionEvent } from '@deepseek-ai/dsh-session/types' -import { FoldAdapter } from '../src/client/sessions/fold-adapter.ts' -import { ev, plainTurn } from './event-script.ts' - -const at = (seq: number, e: Record): SessionEvent => - ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent - -describe('FoldAdapter', () => { - it('folds a baseSeq>0 window through padding sentinels with correct seqs', () => { - const adapter = new FoldAdapter() - const window = plainTurn(100, 5, '偏移问', '偏移答') - adapter.reset(window, 100) - const { nodes, degraded } = adapter.nodes() - expect(degraded).toBe(false) - expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 101], ['assistant', 103]]) - }) - - it('appends incrementally keeping old node references (cache identity)', () => { - const adapter = new FoldAdapter() - adapter.reset(plainTurn(0, 0, 'a', 'b'), 0) - const first = adapter.nodes() - adapter.append(ev.user(6, '追加')) - const second = adapter.nodes() - expect(second.nodes).toHaveLength(3) - expect(second.nodes[0]).toBe(first.nodes[0]) - expect(second.nodes[1]).toBe(first.nodes[1]) - expect(second.nodes).not.toBe(first.nodes) // array itself fresh per call - }) - - it('materializes all six node variants with field mapping', () => { - const adapter = new FoldAdapter() - const events = [ - ev.user(0, '用户'), - ev.assistant(1, 0, '助手'), - at(2, { type: 'steering/message', surfaceOp: 'append', data: { - turn: 0, - message: createUserMessage({ - content: [{ type: 'text', text: '插话' }], - source: { kind: 'user' }, - }), - } }), - at(3, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({ - content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' }, - }) }), - ev.toolCall(4, 0, 'c1', 'echo', '{"x":1}'), - ev.toolResult(5, 0, 'c1', '结果'), - ] - adapter.reset(events, 0) - const { nodes } = adapter.nodes() - const kinds = nodes.map(n => n.kind) - expect(kinds).toContain('user') - expect(kinds).toContain('assistant') - expect(kinds).toContain('steering') - expect(kinds).toContain('context') - const result = nodes.find(n => n.kind === 'tool-result') - expect(result).toMatchObject({ callId: 'c1', call: { name: 'echo', argsRaw: '{"x":1}' }, isError: false }) - }) - - it('returns call:null for a tool-result whose call fell outside the window', () => { - const adapter = new FoldAdapter() - adapter.reset([ev.toolResult(50, 3, 'outside-call', '孤儿结果')], 50) - const { nodes } = adapter.nodes() - expect(nodes[0]).toMatchObject({ kind: 'tool-result', callId: 'outside-call', call: null }) - }) - - it('materializes surface-eligible types it does not know as unknown nodes', () => { - const adapter = new FoldAdapter() - adapter.reset([at(0, { type: 'notice/message', surfaceOp: 'append', data: { note: 1 } })], 0) - const { nodes } = adapter.nodes() - // Either the fold surfaces it (unknown node) or skips it as non-eligible — both are valid - // shapes; what matters is no throw and no misclassification into a known kind. - for (const node of nodes) expect(node.kind).toBe('unknown') - }) - - it('degrades to the lenient linear scan when the fold throws, and stays degraded', () => { - const adapter = new FoldAdapter() - // An invalid surfaceOp on a surface-eligible event deterministically throws in the core fold. - const window = [ - ev.user(10, '正常'), - at(11, { type: 'assistant/message', surfaceOp: 'bogus-op', data: { - turn: 0, step: 0, - message: createMessage({ - role: 'assistant', - content: [{ type: 'text', text: '坏 op' }], - source: { - kind: 'model', - ...{ provider: 'x', model: 'y' }, - }, - }), - } }), - ] - const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined) - try { - adapter.reset(window, 10) - const first = adapter.nodes() - expect(first.degraded).toBe(true) - expect(errorSpy).toHaveBeenCalled() - expect(first.nodes.map(n => n.seq)).toEqual([10, 11]) // linear scan: append order, bad op ignored - adapter.append(ev.user(12, '降级后追加')) // bump rev so the cached result is not reused - const second = adapter.nodes() - expect(second.degraded).toBe(true) // sticky: no re-throw loop, straight to the linear scan - expect(second.nodes[0]).toBe(first.nodes[0]) // cache still serves node identity - expect(second.nodes.map(n => n.seq)).toEqual([10, 11, 12]) - } finally { - errorSpy.mockRestore() - } - }) - - it('materializes a tool-result error field when present', () => { - const adapter = new FoldAdapter() - adapter.reset([ - at(0, { type: 'tool/result', surfaceOp: 'append', data: { - turn: 0, step: 0, - message: createToolResultMessage({ - callId: CallId('c1'), - content: [], - isError: true, - }), - error: { name: 'Boom', code: 'boom' }, - } }), - ], 0) - expect(adapter.nodes().nodes[0]).toMatchObject({ kind: 'tool-result', isError: true, error: { code: 'boom' } }) - }) - - it('exposes the in-window call index for runningCalls material', () => { - const adapter = new FoldAdapter() - adapter.reset([ev.toolCall(0, 1, 'c9', 'slow', '{}')], 0) - expect(adapter.callIndex.get('c9')).toMatchObject({ name: 'slow', turn: 1 }) - adapter.append(ev.toolCall(1, 1, 'c10', 'fast', '{}')) - expect(adapter.callIndex.size).toBe(2) - }) - - it('attaches wire views: callView into the call index, resultView onto the node by seq', () => { - const adapter = new FoldAdapter() - const events = [ - ev.toolCall(0, 1, 'c1', 'bash', '{"cmd":"ls"}'), - ev.toolResult(1, 1, 'c1', 'listing'), - ] - const callView = { for: 'call' as const, view: { card: 'terminal' as const, command: 'ls' } } - const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '完成' } } - adapter.reset(events, 0, [callView, resultView] as never) - expect(adapter.callIndex.get('c1')).toMatchObject({ callView: { card: 'terminal' } }) - const node = adapter.nodes().nodes.find(n => n.kind === 'tool-result') - expect(node).toMatchObject({ callView: { card: 'terminal' }, resultView: { card: 'generic', title: '完成' } }) - }) - - it('attaches views on the live append path and defaults to null without views', () => { - const adapter = new FoldAdapter() - adapter.reset(plainTurn(0, 0, 'a', 'b'), 0) // no views argument: legacy-shaped call - adapter.append(ev.toolCall(6, 1, 'c2', 'echo', '{}'), { for: 'call', view: { card: 'generic', title: '回声' } } as never) - adapter.append(ev.toolResult(7, 1, 'c2', 'ok')) // no view on the result - expect(adapter.callIndex.get('c2')).toMatchObject({ callView: { title: '回声' } }) - const node = adapter.nodes().nodes.find(n => n.kind === 'tool-result') - expect(node).toMatchObject({ callView: { title: '回声' }, resultView: null }) - }) - - it('leaves callView null when the paired call fell outside the window (cross-page break)', () => { - const adapter = new FoldAdapter() - const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '孤儿' } } - adapter.reset([ev.toolResult(50, 3, 'outside', '窗外配对')], 50, [resultView] as never) - const node = adapter.nodes().nodes[0] - expect(node).toMatchObject({ kind: 'tool-result', call: null, callView: null, resultView: { title: '孤儿' } }) - }) - - describe('command lifecycle nodes', () => { - it('folds a run/done pair into one settled node merged into flow order by seq', () => { - const adapter = new FoldAdapter() - adapter.reset([ - ev.user(0, '先说话'), - ev.commandRun(1, 'cmd-1', 'plan'), - ev.commandDone(2, 'cmd-1', 'success', '已进入 plan mode'), - ev.assistant(3, 0, '然后回答'), - ], 0) - const { nodes } = adapter.nodes() - expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['assistant', 3]]) - expect(nodes[1]).toMatchObject({ - kind: 'command', commandId: 'cmd-1', name: 'plan', args: '', - outcome: { kind: 'success', text: '已进入 plan mode' }, - }) - }) - - it('renders a run with no done as still executing (outcome null)', () => { - const adapter = new FoldAdapter() - adapter.reset([ev.commandRun(0, 'cmd-2', 'goal', ' ship it')], 0) - expect(adapter.nodes().nodes[0]).toMatchObject({ - kind: 'command', name: 'goal', args: ' ship it', outcome: null, - }) - }) - - it('soft-falls a done-only window into a node built from the done (cross-window cut)', () => { - const adapter = new FoldAdapter() - adapter.reset([ev.commandDone(80, 'cmd-3', 'error', '失败了')], 80) - expect(adapter.nodes().nodes[0]).toMatchObject({ - kind: 'command', seq: 80, commandId: 'cmd-3', name: null, args: null, - outcome: { kind: 'error', text: '失败了' }, - }) - }) - - it('settles a live-appended done in place, keeping the node at the run seq', () => { - const adapter = new FoldAdapter() - adapter.reset(plainTurn(0, 0, 'q', 'a'), 0) - adapter.append(ev.commandRun(6, 'cmd-4', 'clear')) - const running = adapter.nodes().nodes.find(n => n.kind === 'command') - expect(running).toMatchObject({ outcome: null }) - adapter.append(ev.commandDone(7, 'cmd-4')) - const settled = adapter.nodes().nodes.find(n => n.kind === 'command') - expect(settled).toMatchObject({ seq: 6, outcome: { kind: 'success' } }) - // Settlement replaced the node object rather than mutating the published one. - expect(settled).not.toBe(running) - }) - - it('tails command nodes whose seq is past every surface node', () => { - const adapter = new FoldAdapter() - adapter.reset([ev.user(0, '问'), ev.commandRun(1, 'cmd-tail', 'plan')], 0) - expect(adapter.nodes().nodes.map(n => n.kind)).toEqual(['user', 'command']) - }) - - it('command nodes survive the degraded linear-scan branch', () => { - const adapter = new FoldAdapter() - const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined) - try { - adapter.reset([ - ev.commandRun(0, 'cmd-5', 'plan'), - ev.commandDone(1, 'cmd-5'), - at(2, { type: 'assistant/message', surfaceOp: 'bogus-op', data: { - turn: 0, - step: 0, - message: createMessage({ - role: 'assistant', - content: [{ type: 'text', text: '坏 op' }], - source: { kind: 'model', provider: 'x', model: 'y' }, - }), - } }), - ], 0) - const { nodes, degraded } = adapter.nodes() - expect(degraded).toBe(true) - expect(nodes.some(n => n.kind === 'command')).toBe(true) - } finally { - errorSpy.mockRestore() - } - }) - }) -}) diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts index c7be330d55..8d09798b8e 100644 --- a/packages/client/runtime/tests/session.spec.ts +++ b/packages/client/runtime/tests/session.spec.ts @@ -195,6 +195,45 @@ describe('live event path', () => { }) }) + it('keeps compacted history and adds one marker, live and on replay alike', async () => { + // A landed compaction must not erase conversation the reader already saw: + // the shadowed messages stay at their own log positions and the checkpoint + // contributes one marker after them. + const { session } = await opened() + const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) } + feed(ev.compactSummary(6, '压缩摘要', 1, 3)) + feed(ev.compactCheckpoint(7, 6, 1, 3)) + const live = session.getSnapshot().nodes + expect(live.map(n => [n.kind, n.seq])).toEqual([['user', 1], ['assistant', 3], ['compaction', 7]]) + expect(live.at(-1)).toMatchObject({ kind: 'compaction', summary: '压缩摘要' }) + + const replayed = await opened([ + ...plainTurn(0, 0, 'a', 'b'), + ev.compactSummary(6, '压缩摘要', 1, 3), + ev.compactCheckpoint(7, 6, 1, 3), + ]) + expect(replayed.session.getSnapshot().nodes).toEqual(live) + }) + + it('merges an interrupted frozen node by seq into the log-ordered transcript', async () => { + // The transcript array is seq-monotonic, so the frozen node's fractional + // seq lands it exactly where it happened — including after a compaction + // checkpoint whose own seq is higher than the range it shadowed. + const { session } = await opened() + const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) } + feed(ev.compactSummary(6, '压缩摘要', 1, 3)) + feed(ev.compactCheckpoint(7, 6, 1, 3)) + feed(ev.turnStart(8, 1)) + feed(ev.user(9, '压缩后的提问')) + feed(ev.chunkStart(10, 1)) + feed(ev.chunkText(11, 1, '说到一半')) + feed(ev.turnEnd(12, 1, 'cancelled')) + expect(session.getSnapshot().nodes.map(n => n.kind)).toEqual([ + 'user', 'assistant', 'compaction', 'user', 'assistant', + ]) + expect(session.getSnapshot().nodes.at(-1)).toMatchObject({ interrupted: true }) + }) + it('repairs a seq gap by repulling the tail page instead of appending a hole', async () => { const { api, session } = await opened(plainTurn(0, 0, 'a', 'b')) // tail seq = 5 const repaired = [...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')] @@ -226,6 +265,30 @@ describe('paging', () => { expect(snapshot.nodes.map(n => n.seq)).toEqual([1, 3, 7, 9]) }) + it('renders a page whose checkpoint shadows seqs below the window head, logging nothing', async () => { + // Pagination no longer spends maxMessages quota on replacement copies, so a + // page can carry a compaction checkpoint whose surfaceOp.start lies outside + // the window. The old surface fold rejected that range and degraded with a + // console error; the log-ordered transcript has no range to resolve. + const { api, session } = makeSession() + api.onHistory = () => histResponse([ + ev.compactSummary(80, '窗外范围的摘要', 3, 40), + ev.compactCheckpoint(81, 80, 3, 40), + ev.user(82, '压缩后的新问题'), + ], true) + const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined) + try { + await session.open() + const snapshot = session.getSnapshot() + expect(snapshot.openState).toBe('open') + expect(snapshot.nodes.map(n => [n.kind, n.seq])).toEqual([['compaction', 81], ['user', 82]]) + expect(snapshot.nodes[0]).toMatchObject({ summary: '窗外范围的摘要' }) + expect(errorSpy).not.toHaveBeenCalled() + } finally { + errorSpy.mockRestore() + } + }) + it('drops a discontinuous older page fail-soft (window unchanged, hasMore cleared)', async () => { const { api, session } = makeSession() api.onHistory = payload => payload.beforeSeq === undefined diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts new file mode 100644 index 0000000000..b53fcb0117 --- /dev/null +++ b/packages/client/runtime/tests/transcript-adapter.spec.ts @@ -0,0 +1,415 @@ +/** + * TranscriptAdapter over the raw append-only window: log-ordered projection of + * append-origin events, one marker per landed compaction, replacement copies + * hidden, command-lifecycle folding, node/array identity, call pairing, and + * host-provided wire views. + */ + +import { createUserMessage, CallId, createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm' +import { describe, expect, it } from 'vitest' +import type { SessionEvent } from '@deepseek-ai/dsh-session/types' +import { TranscriptAdapter } from '../src/client/sessions/transcript-adapter.ts' +import { ev, plainTurn } from './event-script.ts' + +const at = (seq: number, e: Record): SessionEvent => + ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent + +/** A `compact/summary` provenance event (log-only, no surfaceOp). */ +function compactSummary(seq: number, summary: unknown = [{ type: 'text', text: '# 摘要\n\n保留事实' }]): SessionEvent { + return at(seq, { + type: 'compact/summary', + data: { + summary, + shadowedRange: { start: 1, end: 3 }, + shadowedSeqs: [1, 3], + shadowedTokenCount: 100, + provider: 'fake', + model: 'compact-1', + }, + }) +} + +/** The replacement user message a compaction backend lands (the checkpoint). */ +function checkpoint( + seq: number, + summarySeq: number, + { start = 1, end = 3, sourceEventSeqs = [summarySeq, start, end] }: { + start?: number + end?: number + sourceEventSeqs?: number[] + } = {}, +): SessionEvent { + return at(seq, { + type: 'user/message', + surfaceOp: { op: 'replace', start, end }, + sourceEventSeqs, + data: createUserMessage({ + content: [{ type: 'text', text: 'model only' }], + source: { kind: 'plugin', plugin: 'compact' }, + }), + }) +} + +describe('TranscriptAdapter', () => { + it('projects a window starting past seq 0 at its own log positions', () => { + const adapter = new TranscriptAdapter() + adapter.reset(plainTurn(100, 5, '偏移问', '偏移答')) + expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 101], ['assistant', 103]]) + }) + + it('appends incrementally keeping old node references (materialize-once identity)', () => { + const adapter = new TranscriptAdapter() + adapter.reset(plainTurn(0, 0, 'a', 'b')) + const first = adapter.nodes() + adapter.append(ev.user(6, '追加')) + const second = adapter.nodes() + expect(second).toHaveLength(3) + expect(second[0]).toBe(first[0]) + expect(second[1]).toBe(first[1]) + expect(second).not.toBe(first) // a real change swaps the array + }) + + it('keeps the array reference across a chunk storm and swaps it when a node lands', () => { + const adapter = new TranscriptAdapter() + adapter.reset(plainTurn(0, 0, 'a', 'b')) + const settled = adapter.nodes() + adapter.append(ev.chunkStart(6, 1)) + expect(adapter.nodes()).toBe(settled) + adapter.append(ev.chunkText(7, 1, '流式')) + expect(adapter.nodes()).toBe(settled) + adapter.append(ev.assistant(8, 1, '流式完成')) + const finalized = adapter.nodes() + expect(finalized).not.toBe(settled) + expect(finalized.at(-1)).toMatchObject({ kind: 'assistant', seq: 8 }) + }) + + it('materializes every append-origin variant with field mapping', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ + ev.user(0, '用户'), + ev.assistant(1, 0, '助手'), + at(2, { type: 'steering/message', surfaceOp: 'append', data: { + turn: 0, + message: createUserMessage({ + content: [{ type: 'text', text: '插话' }], + source: { kind: 'user' }, + }), + } }), + at(3, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({ + content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' }, + }) }), + ev.toolCall(4, 0, 'c1', 'echo', '{"x":1}'), + ev.toolResult(5, 0, 'c1', '结果'), + ]) + const nodes = adapter.nodes() + expect(nodes.map(n => n.kind)).toEqual(['user', 'assistant', 'steering', 'context', 'tool-result']) + expect(nodes.find(n => n.kind === 'tool-result')).toMatchObject({ + callId: 'c1', call: { name: 'echo', argsRaw: '{"x":1}' }, isError: false, + }) + }) + + it('skips events core does not call surface-eligible, marker or not', () => { + // The transcript is the append-origin surface, so log-only events (a chunk, + // a turn boundary, a compact/* provenance record) and a future type core + // has not admitted contribute no node. + const adapter = new TranscriptAdapter() + adapter.reset([ + ev.turnStart(0, 1), + at(1, { type: 'notice/message', surfaceOp: 'append', data: { note: 1 } }), + compactSummary(2), + ev.user(3, '唯一的一条'), + ev.turnEnd(4, 1), + ]) + expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 3]]) + }) + + describe('compaction markers', () => { + it('keeps the original messages and full tool output, hiding replacement copies', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ + ev.user(0, '原始问题'), + ev.assistant(1, 0, '原始回答'), + ev.toolCall(4, 0, 'c1', 'echo', '{}'), + ev.toolResult(5, 0, 'c1', '完整工具输出'), + // A pruned tool/result copy: rewrites one node for the model, marks nothing. + at(6, { type: 'tool/result', surfaceOp: { op: 'replace', start: 5, end: 5 }, sourceEventSeqs: [5], data: { + turn: 0, step: 0, + message: createToolResultMessage({ callId: CallId('c1'), content: [{ type: 'text', text: '已裁剪' }], isError: false }), + } }), + compactSummary(7), + checkpoint(8, 7, { start: 1, end: 5, sourceEventSeqs: [7, 1, 5] }), + // A regenerated assistant/message: also a silent model-only rewrite. + at(9, { type: 'assistant/message', surfaceOp: { op: 'replace', start: 8, end: 8 }, sourceEventSeqs: [8], data: { + turn: 0, step: 0, + message: createMessage({ + role: 'assistant', + content: [{ type: 'text', text: '通用 replacement 副本' }], + source: { kind: 'model', ...{ provider: 'x', model: 'copy' } }, + }), + } }), + ]) + const nodes = adapter.nodes() + expect(nodes.map(n => [n.kind, n.seq])).toEqual([ + ['user', 0], ['assistant', 1], ['tool-result', 5], ['compaction', 8], + ]) + expect(nodes[2]).toMatchObject({ kind: 'tool-result', content: [{ type: 'text', text: '完整工具输出' }] }) + expect(nodes[3]).toMatchObject({ kind: 'compaction', summary: '# 摘要\n\n保留事实' }) + }) + + it('adds one marker per landed compaction, in log order', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ + ev.user(0, 'a'), + compactSummary(1, [{ type: 'text', text: 'first' }]), + checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }), + ev.user(3, 'b'), + compactSummary(4, [{ type: 'text', text: 'second' }]), + checkpoint(5, 4, { start: 2, end: 3, sourceEventSeqs: [4, 2, 3] }), + ]) + expect(adapter.nodes().filter(n => n.kind === 'compaction')).toEqual([ + { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: 'first' }, + { kind: 'compaction', seq: 5, time: 1_700_000_000_005, summary: 'second' }, + ]) + }) + + it('renders the marker when the shadowed range is outside the window and logs nothing', () => { + // The pagination hole A1 left open: quota is no longer spent on + // replacement copies, so a page can carry a checkpoint whose + // surfaceOp.start lies below the window head. The old surface fold threw + // on the missing range and degraded with a console error; a log-ordered + // projection has no range to resolve. + const adapter = new TranscriptAdapter() + const noise = { error: console.error, warn: console.warn } + const logged: unknown[] = [] + console.error = (...args: unknown[]) => logged.push(args) + console.warn = (...args: unknown[]) => logged.push(args) + try { + adapter.reset([ + compactSummary(80, [{ type: 'text', text: '窗外范围' }]), + checkpoint(81, 80, { start: 3, end: 40, sourceEventSeqs: [80, 3, 40] }), + ev.user(82, '压缩后的新问题'), + ]) + expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['compaction', 81], ['user', 82]]) + expect(adapter.nodes()[0]).toMatchObject({ summary: '窗外范围' }) + } finally { + console.error = noise.error + console.warn = noise.warn + } + expect(logged).toEqual([]) + }) + + it('treats an APPENDING plugin-sourced user/message as injected context, not a compaction', () => { + // A session-reference card carries the same plugin source shape; only the + // replacement marker makes an event a checkpoint. + const adapter = new TranscriptAdapter() + adapter.reset([ + at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({ + content: [{ type: 'text', text: '注入的上下文' }], + source: { kind: 'plugin', plugin: 'compact' }, + }) }), + ]) + expect(adapter.nodes()).toMatchObject([{ kind: 'context', seq: 0 }]) + }) + + it('ignores a foreign plugin s replacement user/message', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ + ev.user(0, '保留'), + at(1, { type: 'user/message', surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0], data: createUserMessage({ + content: [{ type: 'text', text: '别的插件重写' }], + source: { kind: 'plugin', plugin: 'not-compact' }, + }) }), + ]) + expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 0]]) + }) + + it.each([ + ['absent provenance', undefined], + ['malformed summary blocks', compactSummary(1, [{ type: 'image', data: 'nope' }])], + ['a whitespace-only summary', compactSummary(1, [{ type: 'text', text: ' ' }])], + ['an empty summary array', compactSummary(1, [])], + ['a non-array summary', compactSummary(1, 'plain string')], + ])('degrades %s to a non-expandable marker', (_label, summary) => { + const adapter = new TranscriptAdapter() + adapter.reset([ + ...(summary === undefined ? [] : [summary]), + checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }), + ]) + expect(adapter.nodes()).toEqual([ + { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null }, + ]) + }) + + it('leaves the summary null when the checkpoint records no provenance at all', () => { + const adapter = new TranscriptAdapter() + adapter.reset([at(2, { + type: 'user/message', + surfaceOp: { op: 'replace', start: 0, end: 0 }, + data: createUserMessage({ + content: [{ type: 'text', text: 'x' }], + source: { kind: 'plugin', plugin: 'compact' }, + }), + })]) + expect(adapter.nodes()).toEqual([{ kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null }]) + }) + + it('skips a non-summary provenance seq before reaching the real one', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ + ev.user(0, '被压缩的问题'), + at(1, { type: 'compact/start', data: { turn: 0 } }), + compactSummary(2, [{ type: 'text', text: '第三个来源才是摘要' }]), + checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [1, 2, 0] }), + ]) + expect(adapter.nodes().at(-1)).toMatchObject({ kind: 'compaction', summary: '第三个来源才是摘要' }) + }) + + it('resolves the summary once an older page supplies the provenance', () => { + const adapter = new TranscriptAdapter() + const landed = checkpoint(8, 7, { start: 0, end: 0, sourceEventSeqs: [7, 0] }) + adapter.reset([landed]) + expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: null }) + adapter.reset([compactSummary(7, [{ type: 'text', text: '分页补齐的摘要' }]), landed]) + expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: '分页补齐的摘要' }) + }) + + it('creates the marker on the live append path', () => { + const adapter = new TranscriptAdapter() + adapter.reset(plainTurn(0, 0, 'a', 'b')) + adapter.append(compactSummary(6, [{ type: 'text', text: '直播摘要' }])) + adapter.append(checkpoint(7, 6, { start: 1, end: 3, sourceEventSeqs: [6, 1, 3] })) + const nodes = adapter.nodes() + // The compacted history is still there; the marker is one more row after it. + expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 1], ['assistant', 3], ['compaction', 7]]) + expect(nodes.at(-1)).toMatchObject({ kind: 'compaction', seq: 7, summary: '直播摘要' }) + }) + }) + + it('returns call:null for a tool-result whose call fell outside the window', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ev.toolResult(50, 3, 'outside-call', '孤儿结果')]) + expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', callId: 'outside-call', call: null }) + }) + + it('materializes a tool-result error field when present', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ + at(0, { type: 'tool/result', surfaceOp: 'append', data: { + turn: 0, step: 0, + message: createToolResultMessage({ callId: CallId('c1'), content: [], isError: true }), + error: { name: 'Boom', code: 'boom' }, + } }), + ]) + expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', isError: true, error: { code: 'boom' } }) + }) + + it('exposes the in-window call index for runningCalls material', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ev.toolCall(0, 1, 'c9', 'slow', '{}')]) + expect(adapter.callIndex.get('c9')).toMatchObject({ name: 'slow', turn: 1 }) + adapter.append(ev.toolCall(1, 1, 'c10', 'fast', '{}')) + expect(adapter.callIndex.size).toBe(2) + }) + + it('attaches wire views: callView into the call index, resultView onto the node by seq', () => { + const adapter = new TranscriptAdapter() + const callView = { for: 'call' as const, view: { card: 'terminal' as const, command: 'ls' } } + const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '完成' } } + adapter.reset([ + ev.toolCall(0, 1, 'c1', 'bash', '{"cmd":"ls"}'), + ev.toolResult(1, 1, 'c1', 'listing'), + ], [callView, resultView] as never) + expect(adapter.callIndex.get('c1')).toMatchObject({ callView: { card: 'terminal' } }) + expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({ + callView: { card: 'terminal' }, resultView: { card: 'generic', title: '完成' }, + }) + }) + + it('attaches views on the live append path and defaults to null without views', () => { + const adapter = new TranscriptAdapter() + adapter.reset(plainTurn(0, 0, 'a', 'b')) // no views argument + adapter.append(ev.toolCall(6, 1, 'c2', 'echo', '{}'), { for: 'call', view: { card: 'generic', title: '回声' } } as never) + adapter.append(ev.toolResult(7, 1, 'c2', 'ok')) // no view on the result + expect(adapter.callIndex.get('c2')).toMatchObject({ callView: { title: '回声' } }) + expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({ + callView: { title: '回声' }, resultView: null, + }) + }) + + it('leaves callView null when the paired call fell outside the window (cross-page break)', () => { + const adapter = new TranscriptAdapter() + const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '孤儿' } } + adapter.reset([ev.toolResult(50, 3, 'outside', '窗外配对')], [resultView] as never) + expect(adapter.nodes()[0]).toMatchObject({ + kind: 'tool-result', call: null, callView: null, resultView: { title: '孤儿' }, + }) + }) + + describe('command lifecycle nodes', () => { + it('folds a run/done pair into one settled node merged into flow order by seq', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ + ev.user(0, '先说话'), + ev.commandRun(1, 'cmd-1', 'plan'), + ev.commandDone(2, 'cmd-1', 'success', '已进入 plan mode'), + ev.assistant(3, 0, '然后回答'), + ]) + const nodes = adapter.nodes() + expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['assistant', 3]]) + expect(nodes[1]).toMatchObject({ + kind: 'command', commandId: 'cmd-1', name: 'plan', args: '', + outcome: { kind: 'success', text: '已进入 plan mode' }, + }) + }) + + it('renders a run with no done as still executing (outcome null)', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ev.commandRun(0, 'cmd-2', 'goal', ' ship it')]) + expect(adapter.nodes()[0]).toMatchObject({ kind: 'command', name: 'goal', args: ' ship it', outcome: null }) + }) + + it('soft-falls a done-only window into a node built from the done (cross-window cut)', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ev.commandDone(80, 'cmd-3', 'error', '失败了')]) + expect(adapter.nodes()[0]).toMatchObject({ + kind: 'command', seq: 80, commandId: 'cmd-3', name: null, args: null, + outcome: { kind: 'error', text: '失败了' }, + }) + }) + + it('settles a live-appended done in place, keeping the node at the run seq', () => { + const adapter = new TranscriptAdapter() + adapter.reset(plainTurn(0, 0, 'q', 'a')) + adapter.append(ev.commandRun(6, 'cmd-4', 'clear')) + const running = adapter.nodes().find(n => n.kind === 'command') + expect(running).toMatchObject({ outcome: null }) + adapter.append(ev.commandDone(7, 'cmd-4')) + const settled = adapter.nodes().find(n => n.kind === 'command') + expect(settled).toMatchObject({ seq: 6, outcome: { kind: 'success' } }) + // Settlement replaced the node object rather than mutating the published one. + expect(settled).not.toBe(running) + }) + + it('tails command nodes whose seq is past every transcript node', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ev.user(0, '问'), ev.commandRun(1, 'cmd-tail', 'plan')]) + expect(adapter.nodes().map(n => n.kind)).toEqual(['user', 'command']) + }) + + it('renders the /compact row alongside the marker its own command produced', () => { + // The row that reports the compaction is a command node; dropping command + // folding would delete it together with every other slash-command row. + const adapter = new TranscriptAdapter() + adapter.reset([ + ev.user(0, '压缩前的问题'), + ev.commandRun(1, 'cmd-compact', 'compact'), + compactSummary(2, [{ type: 'text', text: '手动压缩摘要' }]), + checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [2, 0] }), + ev.commandDone(4, 'cmd-compact', 'success', '已压缩'), + ]) + const nodes = adapter.nodes() + expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['compaction', 3]]) + expect(nodes[1]).toMatchObject({ name: 'compact', outcome: { kind: 'success', text: '已压缩' } }) + }) + }) +}) diff --git a/packages/client/test-runtime/src/fixtures.ts b/packages/client/test-runtime/src/fixtures.ts index 4219d233e2..6c2f8e077b 100644 --- a/packages/client/test-runtime/src/fixtures.ts +++ b/packages/client/test-runtime/src/fixtures.ts @@ -46,7 +46,6 @@ export function conversationSnapshot(sessionId: SessionId): ConversationSnapshot return { sessionId, nodes: [], - foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(), diff --git a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx new file mode 100644 index 0000000000..604f504aac --- /dev/null +++ b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx @@ -0,0 +1,49 @@ +// CompactionItem: the one row a landed compaction contributes to the flow. +// The conversation it shadowed on the model surface stays above it, so this +// marker reports where the model stopped seeing that history — it never +// replaces it. The framed checkpoint payload is written for the model and is +// not rendered; the disclosure shows the summary from the checkpoint's own +// provenance, and a window cut that left that provenance outside makes the row +// non-expandable rather than empty. + +import { memo, useState } from 'react' +import type { CompactionSummaryNode } from '@deepseek-ai/dsh-client-runtime/client' +import { + IconChevronDownOutline14, + IconChevronRightOutline14, + MarkdownText, +} from '@deepseek-ai/dsh-client-ui-primitives' +import css from './MessageItem.module.css' + +/** + * The collapsed-by-default compaction marker. + * @param props - the marker node off the snapshot cache. + * @returns the marker row, with the summary disclosure when one is available. + */ +export const CompactionItem = memo(function CompactionItem({ node }: { node: CompactionSummaryNode }) { + const [expanded, setExpanded] = useState(false) + const expandable = node.summary !== null + const open = expandable && expanded + return ( +
+ + {open && node.summary !== null + &&
} +
+ ) +}) 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 260382d530..be6ddf897e 100644 --- a/packages/client/ui-conversation/src/client/chat/MessageItem.module.css +++ b/packages/client/ui-conversation/src/client/chat/MessageItem.module.css @@ -42,6 +42,81 @@ padding: 2px 0; } +/* Compaction marker: one dim 24px row with a chevron disclosure for the + summary body. Dimmed title (not label-primary) — the row is a boundary + notice, not conversation content. */ +.compactionRow { + padding: 2px 0; +} + +.compactionButton { + display: flex; + align-items: center; + width: 100%; + height: 24px; + min-width: 0; + padding: 0; + border: none; + border-radius: 6px; + background: none; + color: inherit; + font: inherit; + text-align: left; +} + +.compactionButton:not(:disabled) { + cursor: pointer; +} + +.compactionButton:not(:disabled):hover { + background: var(--dsw-alias-interactive-bg-hover); +} + +.compactionLeading { + flex: none; + display: inline-flex; + align-items: center; + justify-content: center; + width: 16px; + height: 16px; + margin-right: 6px; + color: var(--dsw-alias-label-secondary); +} + +.compactionTitle { + flex: none; + font-size: 14px; + line-height: 24px; + color: var(--dsw-alias-label-primary-dimmed); +} + +.compactionSep { + flex: none; + width: 2px; + height: 2px; + margin: 0 8px; + border-radius: 1px; + background: var(--dsw-alias-label-caption); +} + +.compactionSummary { + flex: 1 1 auto; + min-width: 0; + overflow: hidden; + color: var(--dsw-alias-label-tertiary); + font-size: 14px; + line-height: 24px; + text-overflow: ellipsis; + white-space: nowrap; +} + +.compactionBody { + padding: 4px 0 4px 22px; + color: var(--dsw-alias-label-tertiary); + font-size: 14px; + line-height: 24px; +} + /* Reference chip projection inside a user bubble (`name` model spans render as chips; free geometry — no textarea pairing here). */ .refChip { diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx index a149d37337..b7a75262d7 100644 --- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx +++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx @@ -1,20 +1,21 @@ -// MessageItem: the four simple node kinds — user bubble (right-aligned, with +// MessageItem: the five simple node kinds — user bubble (right-aligned, with // clock + copy / branch / edit IconActions), steering (badged bubble), context -// injection and unknown-surface JSON rows. Props are frozen node slices off -// the snapshot cache; memo holds across streaming because unchanged nodes -// keep their references. +// injection, the compaction marker, and unknown-surface JSON rows. Props are +// frozen node slices off the snapshot cache; memo holds across streaming +// because unchanged nodes keep their references. import { memo } from 'react' import type { ReactNode } from 'react' import type { - ContextMessageNode, SteeringMessageNode, UnknownSurfaceNode, UserMessageNode, + CompactionSummaryNode, ContextMessageNode, SteeringMessageNode, UnknownSurfaceNode, UserMessageNode, } from '@deepseek-ai/dsh-client-runtime/client' import { JsonBlock, MessageText } from '@deepseek-ai/dsh-client-ui-primitives' +import { CompactionItem } from './CompactionItem.tsx' import { MessageIconActions } from './MessageIconActions.tsx' import css from './MessageItem.module.css' export interface MessageItemProps { - node: UserMessageNode | SteeringMessageNode | ContextMessageNode | UnknownSurfaceNode + node: UserMessageNode | SteeringMessageNode | ContextMessageNode | CompactionSummaryNode | UnknownSurfaceNode } function contentText(content: readonly unknown[]): { text: string; rest: unknown[] } { @@ -98,6 +99,8 @@ export const MessageItem = memo(function MessageItem({ node }: MessageItemProps) ) + case 'compaction': + return default: return (
diff --git a/packages/client/ui-conversation/src/client/chat/chat-flow.ts b/packages/client/ui-conversation/src/client/chat/chat-flow.ts index f1ce061af8..fb2ee42cf2 100644 --- a/packages/client/ui-conversation/src/client/chat/chat-flow.ts +++ b/packages/client/ui-conversation/src/client/chat/chat-flow.ts @@ -24,7 +24,7 @@ function rendersNothing(node: ConversationNode): boolean { /** * Group finalized nodes into the step-summary flow. - * @param nodes - snapshot nodes (surface order). + * @param nodes - snapshot nodes (human transcript order). * @returns flow items; consecutive tool-results merged into one group keyed by the first seq. */ export function deriveChatFlow(nodes: readonly ConversationNode[]): ChatFlowItem[] { 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 9bb6ba539a..73d746fc7c 100644 --- a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx +++ b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx @@ -117,6 +117,34 @@ describe('MessageItem arms', () => { ) expect(unknownView.getByText(/未知 surface 事件：surface\/next/)).toBeTruthy() }) + + it('a compaction marker discloses its summary and never shows the framed checkpoint', () => { + const view = render( + , + ) + const row = view.getByRole('button', { name: /上下文已压缩/ }) + expect(row.getAttribute('aria-expanded')).toBe('false') + expect(view.queryByText(/保留的事实/)).toBeNull() + fireEvent.click(row) + expect(row.getAttribute('aria-expanded')).toBe('true') + expect(view.getByRole('heading', { name: '摘要标题' })).toBeTruthy() + fireEvent.click(row) + expect(row.getAttribute('aria-expanded')).toBe('false') + }) + + it('a marker whose provenance fell outside the window is not expandable', () => { + const view = render() + const row = view.getByRole('button', { name: /上下文已压缩/ }) + expect(row).toHaveProperty('disabled', true) + expect(row.getAttribute('aria-expanded')).toBeNull() + expect(view.getByText('压缩摘要不可用')).toBeTruthy() + fireEvent.click(row) // a disabled control stays collapsed + expect(row.getAttribute('aria-expanded')).toBeNull() + }) }) describe('formatMessageClock', () => { diff --git a/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx index 1b4d1ee158..65dde74764 100644 --- a/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx +++ b/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx @@ -55,7 +55,7 @@ function snapshotWith( runningCalls: RunningToolCall[] = [], ): ConversationSnapshot { return { - sessionId: SID, nodes, foldDegraded: false, partial: null, runningCalls, codeDispatches, + sessionId: SID, nodes, partial: null, runningCalls, codeDispatches, pending: [], queue: [], running: runningCalls.length > 0, composerPhase: 'active', removed: false, openState: 'open', openError: null, hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, diff --git a/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx b/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx index 6985991074..8213a82a3c 100644 --- a/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx +++ b/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx @@ -26,7 +26,7 @@ const assistant = (seq: number, turn: number, usage?: unknown): AssistantMessage function snapshotBase(): ConversationSnapshot { return { - sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(), + sessionId: SID, nodes: [], partial: null, runningCalls: [], codeDispatches: new Map(), pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null, hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, } diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx index 328ba38340..5514f2504a 100644 --- a/packages/client/ui-conversation/tests/chat-view.spec.tsx +++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx @@ -29,7 +29,7 @@ const SID = 's1' as SessionId function snapshotBase(): ConversationSnapshot { return { - sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(), + sessionId: SID, nodes: [], partial: null, runningCalls: [], codeDispatches: new Map(), pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null, hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, } diff --git a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx index 6d58932ece..26171d4040 100644 --- a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx +++ b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx @@ -18,7 +18,7 @@ const SID = 's1' as SessionId function snapshotBase(): ConversationSnapshot { return { - sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(), + sessionId: SID, nodes: [], partial: null, runningCalls: [], codeDispatches: new Map(), pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null, hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, } diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx index 23d853dd1a..7d8012d413 100644 --- a/packages/client/ui-conversation/tests/input-bar.spec.tsx +++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx @@ -20,7 +20,7 @@ const SID = 's1' as SessionId function snapshotOf(overrides: Partial = {}): ConversationSnapshot { return { - sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(), + sessionId: SID, nodes: [], partial: null, runningCalls: [], codeDispatches: new Map(), pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null, hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, diff --git a/packages/client/ui-conversation/tests/input-matrix.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.spec.tsx index f6694f8cb4..b35b2fe06f 100644 --- a/packages/client/ui-conversation/tests/input-matrix.spec.tsx +++ b/packages/client/ui-conversation/tests/input-matrix.spec.tsx @@ -23,7 +23,7 @@ const SID = 's1' as SessionId /** Standard-props InputBar mount over a real shell (the composer-bar entry shape). */ function mountBar(shell: SessionInputShell, over?: { running?: boolean; disabled?: boolean }) { const session = createSnapshotStore({ - sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(), + sessionId: SID, nodes: [], partial: null, runningCalls: [], codeDispatches: new Map(), pending: [], queue: [], running: over?.running ?? false, composerPhase: 'active', removed: over?.disabled ?? false, openState: 'open', openError: null, hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, diff --git a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx index 9d9ace032c..7dbc254ebb 100644 --- a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx +++ b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx @@ -109,7 +109,7 @@ async function scopedBench(register?: (slash: SlashService) => void) { actx.on('slash/input-consume-token', req => shell.consumeToken(req.guard) ? true : undefined) const wiring = shell const sessionStore = createSnapshotStore({ - sessionId, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(), + sessionId, nodes: [], partial: null, runningCalls: [], codeDispatches: new Map(), pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null, hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, diff --git a/packages/client/ui-conversation/tests/queue-dock.spec.tsx b/packages/client/ui-conversation/tests/queue-dock.spec.tsx index c63d3628e5..7f7bae6d9f 100644 --- a/packages/client/ui-conversation/tests/queue-dock.spec.tsx +++ b/packages/client/ui-conversation/tests/queue-dock.spec.tsx @@ -18,7 +18,7 @@ const SID = 's1' as SessionId function snapshotWith(queue: QueuedMessage[]): ConversationSnapshot { return { - sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(), + sessionId: SID, nodes: [], partial: null, runningCalls: [], codeDispatches: new Map(), pending: [], queue, running: true, composerPhase: 'active', removed: false, openState: 'open', openError: null, hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, } diff --git a/packages/client/ui-conversation/tests/skeleton.spec.tsx b/packages/client/ui-conversation/tests/skeleton.spec.tsx index 0d32e2edea..d00ba84718 100644 --- a/packages/client/ui-conversation/tests/skeleton.spec.tsx +++ b/packages/client/ui-conversation/tests/skeleton.spec.tsx @@ -47,7 +47,7 @@ const workspaceState = (items: readonly WorkspaceView[]): WorkspaceListState => function conversationSnapshot(overrides: Partial = {}): ConversationSnapshot { return { - sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(), + sessionId: SID, nodes: [], partial: null, runningCalls: [], codeDispatches: new Map(), pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null, hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, diff --git a/packages/client/ui-trajectory/src/client/layout.ts b/packages/client/ui-trajectory/src/client/layout.ts index 37c86f6eb4..d714a3b42f 100644 --- a/packages/client/ui-trajectory/src/client/layout.ts +++ b/packages/client/ui-trajectory/src/client/layout.ts @@ -110,8 +110,8 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T lastAssistantTurn = node.turn continue } - if (node.kind === 'context') { - // No trajectory cell, but the surface still advances the duration cursor. + if (node.kind === 'context' || node.kind === 'compaction') { + // No trajectory cell, but transcript metadata still advances the duration cursor. prevAbsTime = finiteTime(node.time) ?? prevAbsTime continue } diff --git a/packages/client/ui-trajectory/src/client/spans.ts b/packages/client/ui-trajectory/src/client/spans.ts index 585a336333..de91e4382e 100644 --- a/packages/client/ui-trajectory/src/client/spans.ts +++ b/packages/client/ui-trajectory/src/client/spans.ts @@ -45,7 +45,7 @@ export interface SpanStats { * Fold snapshot nodes into per-turn spans. Only assistant nodes carry a turn * number; user/steering/context/tool nodes attach to the turn last seen in * sequence order (turn 0 collects the pre-assistant prologue). - * @param nodes - snapshot nodes in surface order. + * @param nodes - snapshot nodes in human transcript order. * @returns spans ordered by first appearance. */ export function deriveSpans(nodes: ConversationSnapshot['nodes']): readonly TurnSpan[] { diff --git a/packages/client/ui-trajectory/tests/layout.spec.tsx b/packages/client/ui-trajectory/tests/layout.spec.tsx index 5394d6ab09..c55a939808 100644 --- a/packages/client/ui-trajectory/tests/layout.spec.tsx +++ b/packages/client/ui-trajectory/tests/layout.spec.tsx @@ -176,7 +176,7 @@ describe('deriveTrajectoryLayout', () => { }) }) - it('advances the duration cursor over context nodes', () => { + it('advances the duration cursor over context and compaction nodes', () => { const nodes = [ { kind: 'user', seq: 1, time: 1_000, content: [{ type: 'text', text: 'hi' }], source: null }, { @@ -192,17 +192,21 @@ describe('deriveTrajectoryLayout', () => { kind: 'context', seq: 4, time: 9_000, content: [{ type: 'text', text: 'extra' }], source: null, }, + // A landed compaction renders no cell either, but is still a real log + // position, so it moves the cursor the same way a context row does. + { kind: 'compaction', seq: 5, time: 9_500, summary: 'checkpoint facts' }, { - kind: 'assistant', seq: 5, time: 10_000, turn: 1, step: 0, + kind: 'assistant', seq: 6, time: 10_000, turn: 1, step: 0, blocks: [{ kind: 'text', text: 'done' }], }, ] as unknown as ConversationSnapshot['nodes'] const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] }) - const message = turns[0]?.groups - .flatMap(g => g.cells) - .find(c => c.kind === 'message' && c.text === 'done') - // From context at 9s, not from the earlier user/tool surfaces. - expect(message?.timeSeconds).toBe(1) + const cells = turns[0]?.groups.flatMap(g => g.cells) ?? [] + const message = cells.find(c => c.kind === 'message' && c.text === 'done') + // From the compaction marker at 9.5s, not from context at 9s or the earlier surfaces. + expect(message?.timeSeconds).toBe(0.5) + // Neither the context row nor the marker contributed a cell. + expect(cells).toHaveLength(3) }) }) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index a6dac9263d..1102cd603e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -956,6 +956,9 @@ importers: specifier: ~4.4.7 version: 4.4.7(@types/react@18.3.31)(immer@10.2.0)(react@18.3.1) devDependencies: + '@deepseek-ai/dsh-compact': + specifier: workspace:^ + version: link:../../compact/compact '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../support/invariants diff --git a/tsconfig.client.json b/tsconfig.client.json index 5a52f59bb0..81681df038 100644 --- a/tsconfig.client.json +++ b/tsconfig.client.json @@ -36,6 +36,12 @@ // client-side Context merges keep it out of the host program. { "path": "./packages/host/directory-picker-native" }, { "path": "./packages/host/directory-picker-browse" }, + // Test-only leaf: the client-runtime drift trap for the compaction + // checkpoint source reads the seam's canonical const. It may appear HERE + // but never in a packages/client/* package project — dsh-compact's root + // reaches dsh-session's root, whose Context merge declares the host + // `sessions: SessionStore` and collides with the client's `ISessions`. + { "path": "./packages/compact/compact" }, { "path": "./packages/client/ui-slots" }, { "path": "./packages/client/ui-primitives" }, { "path": "./packages/client/web-react" }, From 8a915893e7788b67d767dff3f1b47722430745f2 Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Wed, 29 Jul 2026 21:29:49 -0700 Subject: [PATCH 02/50] docs: add THIRD_PARTY_NOTICES.md disclosing third-party dependencies List direct dependencies by tier (vendored Cordis sources, runtime npm, dev-only npm, Python SDK, build-time tools) with upstream links and licenses, and link it from the License section of both READMEs. --- README.i18n.yaml | 4 +- README.md | 2 + README.zh.md | 2 + THIRD_PARTY_NOTICES.md | 141 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 147 insertions(+), 2 deletions(-) create mode 100644 THIRD_PARTY_NOTICES.md diff --git a/README.i18n.yaml b/README.i18n.yaml index 7584d4f293..00e595139e 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: f9f7294b42e29132d5cd46c0ab6a5f5265a1d8f3 -README.zh.md: 88cbf8522d8f1a183a48dc7e80858d1a0ced8f0f +README.md: 32a5deb57f6ff8af810c66d27fe994ef469faea3 +README.zh.md: 7a5b875f38ddc74605f01bfca88941135d56679f diff --git a/README.md b/README.md index f9f7294b42..32a5deb57f 100644 --- a/README.md +++ b/README.md @@ -81,3 +81,5 @@ DeepSeek Harness is currently pre-release. ## License [BSD 3-Clause](LICENSE) + +Third-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). diff --git a/README.zh.md b/README.zh.md index 88cbf8522d..7a5b875f38 100644 --- a/README.zh.md +++ b/README.zh.md @@ -85,3 +85,5 @@ DeepSeek Harness 目前处于预发布阶段。 ## 许可证 [BSD 3-Clause](LICENSE) + +第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。 diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md new file mode 100644 index 0000000000..bfbe5608b0 --- /dev/null +++ b/THIRD_PARTY_NOTICES.md @@ -0,0 +1,141 @@ +# Third-Party Notices + +DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the third-party open-source software listed below. Each project remains under its own license; nothing in this file changes those terms. + +This file lists **direct** dependencies declared by the workspace. The complete transitive closure, with exact pinned versions, is recorded in [`pnpm-lock.yaml`](pnpm-lock.yaml) and can be inspected with `pnpm licenses list`. + +## Vendored source (`vendor/`) + +The Cordis framework and its foundation libraries are source-vendored into this repository rather than consumed from npm. All are MIT-licensed; each directory preserves its upstream `LICENSE` file. Exact upstream commits and local modifications are recorded in [`vendor/README.md`](vendor/README.md). + +| Package | Upstream | License | +| --- | --- | --- | +| `cordis` | https://github.com/cordiverse/cordis | MIT | +| `@cordisjs/plugin-loader` | https://github.com/cordiverse/cordis | MIT | +| `@cordisjs/plugin-include` | https://github.com/deepseek-harness/cordis | MIT | +| `@cordisjs/plugin-group` | https://github.com/deepseek-harness/cordis | MIT | +| `@cordisjs/plugin-timer` | https://github.com/deepseek-harness/cordis | MIT | +| `@cordisjs/plugin-hmr` | https://github.com/deepseek-harness/cordis | MIT | +| `@cordisjs/plugin-logger-console` | https://github.com/deepseek-harness/cordis | MIT | +| `cosmokit` | https://github.com/deepseek-harness/cosmokit | MIT | +| `schemastery` | https://github.com/deepseek-harness/schemastery | MIT | + +## Runtime npm dependencies + +Direct dependencies that ship in at least one runtime surface (CLI/TUI, Web UI, SDK runtime, or the website at serve time). + +| Package | License | +| --- | --- | +| [`@agentclientprotocol/sdk`](https://github.com/agentclientprotocol/typescript-sdk) | Apache-2.0 | +| [`@babel/code-frame`](https://github.com/babel/babel) | MIT | +| [`@clack/core`](https://github.com/bombshell-dev/clack) | MIT | +| [`@clack/prompts`](https://github.com/bombshell-dev/clack) | MIT | +| [`@earendil-works/pi-ai`](https://github.com/earendil-works/pi) | MIT | +| [`@earendil-works/pi-tui`](https://github.com/earendil-works/pi) | MIT | +| [`@joplin/turndown-plugin-gfm`](https://github.com/laurent22/joplin-turndown-plugin-gfm) | MIT | +| [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) | MIT | +| [`@opentelemetry/api`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | +| [`@opentelemetry/api-logs`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | +| [`@opentelemetry/exporter-logs-otlp-http`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | +| [`@opentelemetry/otlp-exporter-base`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | +| [`@opentelemetry/resources`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | +| [`@opentelemetry/sdk-logs`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | +| [`@shikijs/langs`](https://github.com/shikijs/shiki) | MIT | +| [`@standard-schema/spec`](https://github.com/standard-schema/standard-schema) | MIT | +| [`@testing-library/dom`](https://github.com/testing-library/dom-testing-library) | MIT | +| [`@testing-library/react`](https://github.com/testing-library/react-testing-library) | MIT | +| [`anser`](https://github.com/IonicaBizau/anser) | MIT | +| [`chokidar`](https://github.com/paulmillr/chokidar) | MIT | +| [`clsx`](https://github.com/lukeed/clsx) | MIT | +| [`commander`](https://github.com/tj/commander.js) | MIT | +| [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause | +| [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT | +| [`execa`](https://github.com/sindresorhus/execa) | MIT | +| [`handlebars`](https://github.com/handlebars-lang/handlebars.js) | MIT | +| [`immer`](https://github.com/immerjs/immer) | MIT | +| [`js-yaml`](https://github.com/nodeca/js-yaml) | MIT | +| [`jsonc-parser`](https://github.com/microsoft/node-jsonc-parser) | MIT | +| [`koffi`](https://github.com/Koromix/koffi) | MIT | +| [`mdast-util-from-markdown`](https://github.com/syntax-tree/mdast-util-from-markdown) | MIT | +| [`mdast-util-gfm`](https://github.com/syntax-tree/mdast-util-gfm) | MIT | +| [`micromark-extension-gfm`](https://github.com/micromark/micromark-extension-gfm) | MIT | +| [`node-addon-require-builtin`](https://www.npmjs.com/package/node-addon-require-builtin) | MIT | +| [`node-pty`](https://github.com/microsoft/node-pty) | MIT | +| [`picomatch`](https://github.com/micromatch/picomatch) | MIT | +| [`react`](https://github.com/facebook/react) | MIT | +| [`react-dom`](https://github.com/facebook/react) | MIT | +| [`react-markdown`](https://github.com/remarkjs/react-markdown) | MIT | +| [`remark-gfm`](https://github.com/remarkjs/remark-gfm) | MIT | +| [`saxes`](https://github.com/lddubeau/saxes) | ISC | +| [`shiki`](https://github.com/shikijs/shiki) | MIT | +| [`supports-color`](https://github.com/chalk/supports-color) | MIT | +| [`tsx`](https://github.com/privatenumber/tsx) | MIT | +| [`turndown`](https://github.com/mixmark-io/turndown) | MIT | +| [`typescript`](https://github.com/microsoft/TypeScript) | Apache-2.0 | +| [`use-sync-external-store`](https://github.com/facebook/react) | MIT | +| [`vitest`](https://github.com/vitest-dev/vitest) | MIT | +| [`yaml`](https://github.com/eemeli/yaml) | ISC | +| [`zod`](https://github.com/colinhacks/zod) | MIT | +| [`zustand`](https://github.com/pmndrs/zustand) | MIT | + +## Development-only npm dependencies + +Direct dependencies used for building, linting, testing, and generating the documentation site. They are not part of any shipped runtime artifact. + +| Package | License | +| --- | --- | +| [`@braintree/sanitize-url`](https://github.com/braintree/sanitize-url) | MIT | +| [`@modelcontextprotocol/server-everything`](https://github.com/modelcontextprotocol/servers) | MIT / Apache-2.0 | +| [`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers) | MIT / Apache-2.0 | +| [`@stylistic/eslint-plugin`](https://github.com/eslint-stylistic/eslint-stylistic) | MIT | +| [`@types/*`](https://github.com/DefinitelyTyped/DefinitelyTyped) (babel__code-frame, js-yaml, jsdom, mdast, node, picomatch, react, react-dom, turndown) | MIT | +| [`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint) | MIT | +| [`@vitejs/plugin-react`](https://github.com/vitejs/vite-plugin-react) | MIT | +| [`@vitest/coverage-v8`](https://github.com/vitest-dev/vitest) | MIT | +| [`@xterm/headless`](https://github.com/xtermjs/xterm.js) | MIT | +| [`@yarnpkg/cli-dist`](https://github.com/yarnpkg/berry) | BSD-2-Clause | +| [`cytoscape`](https://github.com/cytoscape/cytoscape.js) | MIT | +| [`cytoscape-cose-bilkent`](https://github.com/cytoscape/cytoscape.js-cose-bilkent) | MIT | +| [`dayjs`](https://github.com/iamkun/dayjs) | MIT | +| [`debug`](https://github.com/debug-js/debug) | MIT | +| [`esbuild`](https://github.com/evanw/esbuild) | MIT | +| [`eslint`](https://github.com/eslint/eslint) | MIT | +| [`eslint-plugin-sonarjs`](https://github.com/SonarSource/SonarJS) | LGPL-3.0-only | +| [`fast-check`](https://github.com/dubzzz/fast-check) | MIT | +| [`jscpd`](https://github.com/kucherenko/jscpd) | MIT | +| [`jsdom`](https://github.com/jsdom/jsdom) | MIT | +| [`knip`](https://github.com/webpro-nl/knip) | ISC | +| [`lefthook`](https://github.com/evilmartians/lefthook) | MIT | +| [`lightningcss`](https://github.com/parcel-bundler/lightningcss) | MPL-2.0 | +| [`mermaid`](https://github.com/mermaid-js/mermaid) | MIT | +| [`oxlint`](https://github.com/oxc-project/oxc) | MIT | +| [`oxlint-tsgolint`](https://github.com/oxc-project/tsgolint) | MIT | +| [`playwright`](https://github.com/microsoft/playwright) | Apache-2.0 | +| [`publint`](https://github.com/publint/publint) | MIT | +| [`tsdown`](https://github.com/rolldown/tsdown) | MIT | +| [`typescript-language-server`](https://github.com/typescript-language-server/typescript-language-server) | Apache-2.0 | +| [`vite`](https://github.com/vitejs/vite) | MIT | +| [`vite-tsconfig-paths`](https://github.com/aleclarson/vite-tsconfig-paths) | MIT | +| [`vitepress`](https://github.com/vuejs/vitepress) | MIT | +| [`vitepress-plugin-mermaid`](https://github.com/emersonbottero/vitepress-plugin-mermaid) | MIT | + +`eslint-plugin-sonarjs` (LGPL-3.0-only) and `lightningcss` (MPL-2.0) run only as development tooling; their code is not linked into or distributed with any DeepSeek Harness artifact. + +## Python SDK dependencies (`python/`) + +| Package | License | Role | +| --- | --- | --- | +| [`pydantic`](https://github.com/pydantic/pydantic) | MIT | runtime dependency of `deepseek-harness` | +| [`hatchling`](https://github.com/pypa/hatch) | MIT | build backend | +| [`pytest`](https://github.com/pytest-dev/pytest) | MIT | test-only | +| [`uv`](https://github.com/astral-sh/uv) | MIT / Apache-2.0 | development workflow tool | + +## Fetched at build time + +| Package | License | Role | +| --- | --- | --- | +| [`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg) | MIT | invoked by `scripts/build-exe-for-python-sdk.ts` to assemble the single-file SDK runtime executable | + +## First-party sibling releases + +`node-addon-landlock-run` (and its platform packages) is released from a DeepSeek Harness sibling repository under BSD 3-Clause. It is listed here for completeness; it is first-party, not third-party. From 91ee264e16ffda88d2b5b6975417cef24a9283b8 Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Thu, 30 Jul 2026 14:07:08 +0800 Subject: [PATCH 03/50] round 2: pin checkpoint recognition at compile time Move COMPACT_CHECKPOINT_SOURCE and isCompactCheckpointSource into a cordis-free src/checkpoint.ts leaf, re-exported from the root so every host-side consumer keeps its import. The client can then type-import the leaf without reaching dsh-session's root, whose Context merge declares the host sessions service and collides with the client's -- the dsh-commands/brand shape. Renaming the plugin id now fails the client typecheck. Also: keep recoverable summary text when a compact/summary mixes text with other block types, and capture the seeded-history provenance seqs from the pushes that produce them instead of deriving them by arithmetic. --- ...ranscript-log-ordered-projection.i18n.yaml | 4 +- ...0-web-transcript-log-ordered-projection.md | 20 +++-- ...eb-transcript-log-ordered-projection.zh.md | 20 +++-- apps/web/tests/seeded-history.e2e.ts | 85 +++++++++++-------- docs/cordis-catalog/services.md | 2 +- packages/client/runtime/README.i18n.yaml | 4 +- packages/client/runtime/README.md | 2 +- packages/client/runtime/README.zh.md | 2 +- .../src/client/sessions/conversation.ts | 9 +- .../src/client/sessions/transcript-adapter.ts | 39 +++++---- .../tests/compact-checkpoint-pin.spec.ts | 22 +++-- .../runtime/tests/transcript-adapter.spec.ts | 15 +++- packages/client/runtime/tsconfig.json | 3 + packages/compact/compact/README.i18n.yaml | 6 +- packages/compact/compact/README.md | 4 + packages/compact/compact/README.zh.md | 4 + packages/compact/compact/package.json | 5 ++ packages/compact/compact/src/checkpoint.ts | 27 ++++++ packages/compact/compact/src/index.ts | 17 +--- tsconfig.base.json | 1 + tsconfig.client.json | 14 +-- 21 files changed, 197 insertions(+), 108 deletions(-) create mode 100644 packages/compact/compact/src/checkpoint.ts 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 5f80a9b7c9..4c078446f1 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: 22e687ebc0a323a28eb554a9ad36749a0b6f3da6 -2026-07-30-web-transcript-log-ordered-projection.zh.md: 97004f7384aed8f9e43b0949b2fcd4b8c185ca65 +2026-07-30-web-transcript-log-ordered-projection.md: 0c58373d58e08fbfe260f16f2104b3f7d1ccc3fd +2026-07-30-web-transcript-log-ordered-projection.zh.md: 49de0a9ecbbf2da92113f8ad63afe6478caedadd 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 22e687ebc0..0c58373d58 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 @@ -22,18 +22,24 @@ The marker's summary text comes from the checkpoint's own `compact/summary` prov No persisted event, RPC envelope, compaction transaction, or model-visible surface changed, and no migration is required. -## Recognizing a checkpoint: the local literal and its drift trap +## Recognizing a checkpoint: one declaration, pinned at compile time Recognition needs all three conditions, as in the terminal: `event.type === 'user/message'`, the compaction seam's checkpoint plugin source, **and** `isReplacementSurfaceEvent(event)`. A plugin-sourced `user/message` that *appends* is injected context — a session-reference card — not a compaction. -The client restates that plugin source as a local literal, because `dsh-compact` is unreachable from `packages/client/runtime`'s program in **both** directions: +What is unreachable from a `packages/client/*` program is `dsh-compact`'s **root**, not the package. The root reaches `dsh-session`'s root, whose cordis `Context` merge declares the host `sessions: SessionStore` against the client's `sessions: ISessions` — `TS2717`, the one-program-per-side rule in [development.md](../../../../docs/development.md#typescript-project-layout) — and that holds for a type-only import too, because the collision is a compiler fact rather than a bundler one. -- a **value** import fails the client purity gate (`packages/client/tsdown.client.ts`), and `dsh-compact`'s root value-imports cordis, so admitting it would pull `CompactService` into the browser bundle; -- a **type-only** import fails typecheck. `dsh-compact`'s root reaches `dsh-session`'s root, whose cordis `Context` merge declares the host `sessions: SessionStore` against this program's `sessions: ISessions` — `TS2717`, the one-program-per-side rule in [development.md](../../../../docs/development.md#typescript-project-layout). This was expected to work and does not; `import type` is erased before the *bundler* runs, but not before the *compiler* does, and the collision is a compiler fact. +The repo's answer to exactly this is a cordis-free leaf subpath, and this change adds one: `COMPACT_CHECKPOINT_SOURCE` and `isCompactCheckpointSource` now live in `packages/compact/compact/src/checkpoint.ts`, which imports no cordis and augments no module (the `dsh-commands/brand` / `dsh-llm/message` shape), and the root re-exports both so every host-side consumer — the terminal's chat helpers, `dsh-session-reference`'s projection — is unchanged. The adapter pins its literal to that declaration with a type-only import: -The drift protection therefore lives in a test, not in a type: `packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` runs in the client **test** program, which carries no such collision, and drives the adapter with a checkpoint built from the canonical `COMPACT_CHECKPOINT_SOURCE` itself. Renaming the seam's plugin fails there instead of silently deleting every compaction marker from the web transcript. `dsh-compact` is a `devDependency` of `dsh-client-runtime` and a reference of `tsconfig.client.json` only — never of a `packages/client/*` package project. +```ts +import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint' +const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact' +``` -That is a deliberate divergence from the terminal, which value-imports `isCompactCheckpointSource` directly because no gate applies host-side. +Renaming the seam's plugin id is now a compile error in the client: `TS2322: Type '"compact"' is not assignable to type '"compaction"'`. The import must stay **type-only** — a value import of any `@deepseek-ai` package that is neither a platform module nor an inline-safe wire layer is rejected by the client purity gate (`packages/client/tsdown.client.ts`), whose own message records that type-only imports are erased and never reach it. A type-only leaf import needs both a `tsconfig.base.json` `paths` entry and `{"path": "../../compact/compact"}` in `packages/client/runtime/tsconfig.json` `references`: composite `rootDir` rules apply to erased imports as well, and without the reference the diagnostic is `TS6059`/`TS6307`. + +`packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` stays as the behavioral half, driving the adapter with a checkpoint built from the canonical **value**. It runs in the client **test** program, which may value-import the root; a `packages/client/*` package program may not. + +The divergence from the terminal is therefore narrow: both frontends recognize a checkpoint from the same declaration — the terminal value-imports `isCompactCheckpointSource` host-side, where no gate applies, and the client pins the type. ## What #835's positional anchors were for, and why they are dissolved rather than lost @@ -41,7 +47,7 @@ The unmerged manual-compaction-queueing branch fixes the same interleaving bug b ## Alternatives considered -**Add `dsh-compact` to the client `INLINE_SAFE` allowlist** and move the predicate to a cordis-free subpath. Rejected: `INLINE_SAFE` matches on specifier *prefix*, so admitting the package admits its cordis-importing root too; the allowlist is a reviewer promise about client-facing subpaths, not a purity proof. It also needs a new export and a `files` fix, and it would not have helped — the blocking collision turned out to be in the compiler, which an allowlist does not touch. +**Value-import the predicate** from the new leaf and add `dsh-compact` to the client `INLINE_SAFE` allowlist. Rejected: the client needs the plugin id, not the predicate — a type is enough, and an erased import never reaches the purity gate, so nothing has to be admitted to it. The allowlist would only matter for a value import, and there it is a poor trade: `INLINE_SAFE` matches on specifier *prefix*, so admitting the package admits its cordis-importing root along with the leaf. **A bare shape rule** — any replacement `user/message` is a compaction. Rejected: correct today only because compaction is the sole producer of replacement `user/message`s, with nothing to catch it if that changes. The pinning spec costs one file and removes exactly that risk. 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 97004f7384..49de0a9ecb 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 @@ -22,18 +22,24 @@ surface 顺序还让另外两个问题成为结构性的。一次替换之后它 没有任何持久化事件、RPC 信封、压缩事务或模型可见 surface 发生变化，也不需要迁移。 -## 识别检查点：本地字面量与它的漂移陷阱 +## 识别检查点：同一份声明，在编译期钉住 识别需要三个条件同时成立，与终端一致：`event.type === 'user/message'`、压缩缝隙的检查点插件来源，**以及** `isReplacementSurfaceEvent(event)`。一条 append 的插件来源 `user/message` 是注入上下文——跨会话引用卡片——不是压缩。 -客户端把该插件来源重述为一个本地字面量，因为 `dsh-compact` 在**两个**方向上都无法从 `packages/client/runtime` 的程序到达： +从 `packages/client/*` 程序无法到达的是 `dsh-compact` 的**根部**，而不是这个包。根部会到达 `dsh-session` 的根部，后者的 cordis `Context` 合并声明了宿主侧 `sessions: SessionStore`，与客户端的 `sessions: ISessions` 冲突——`TS2717`，即 [development.md](../../../../docs/development.md#typescript-project-layout) 中每侧一个 program 的规则；这一点对仅类型导入同样成立，因为该冲突是编译器事实而非打包器事实。 -- **值**导入会失败于客户端纯度门禁（`packages/client/tsdown.client.ts`），而 `dsh-compact` 的根部会值导入 cordis，因此放行它就会把 `CompactService` 拉进浏览器产物； -- **仅类型**导入会失败于类型检查。`dsh-compact` 的根部会到达 `dsh-session` 的根部，后者的 cordis `Context` 合并声明了宿主侧 `sessions: SessionStore`，与本程序的 `sessions: ISessions` 冲突——`TS2717`，即 [development.md](../../../../docs/development.md#typescript-project-layout) 中每侧一个 program 的规则。这一点原本预期可行，实际不可行：`import type` 在**打包器**运行前被擦除，但不在**编译器**运行前被擦除，而该冲突是编译器事实。 +本仓库对这一情形的既有答案是不含 cordis 的叶子子路径，本次变更就新增了一个：`COMPACT_CHECKPOINT_SOURCE` 与 `isCompactCheckpointSource` 现在住在 `packages/compact/compact/src/checkpoint.ts`，它不导入 cordis、也不增强任何模块（即 `dsh-commands/brand` / `dsh-llm/message` 的形状），而包根重新导出两者，因此每个宿主侧消费方——终端的 chat helper、`dsh-session-reference` 的投影——都不需改动。适配器用仅类型导入把它的字面量钉在该声明上： -因此漂移保护住在一个测试里，而不是一个类型里：`packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` 运行在客户端**测试**程序中——那里不存在这一冲突——并用由权威 `COMPACT_CHECKPOINT_SOURCE` 本身构造的检查点驱动适配器。重命名缝隙的插件会在那里失败，而不是无声地把每个压缩标记从 Web 记录中删除。`dsh-compact` 只是 `dsh-client-runtime` 的 `devDependency` 以及 `tsconfig.client.json` 的一条引用——绝不是任何 `packages/client/*` 包工程的引用。 +```ts +import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint' +const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact' +``` -这是与终端的一次刻意分歧：终端直接值导入 `isCompactCheckpointSource`，因为宿主侧不适用任何门禁。 +重命名缝隙的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。 + +`packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` 作为行为侧的另一半保留，用由权威**值**构造的检查点驱动适配器。它运行在客户端**测试**程序中，那里可以值导入包根；`packages/client/*` 包工程不可以。 + +因此与终端的分歧很窄：两个前端都从同一份声明识别检查点——终端在宿主侧值导入 `isCompactCheckpointSource`（那里不适用任何门禁），客户端钉住类型。 ## #835 的位置锚点是为什么而存在，以及为什么它是被溶解而非丢失 @@ -41,7 +47,7 @@ surface 顺序还让另外两个问题成为结构性的。一次替换之后它 ## Alternatives considered -**把 `dsh-compact` 加入客户端 `INLINE_SAFE` 白名单**，并把谓词搬到一个不含 cordis 的子路径。已拒绝：`INLINE_SAFE` 按标识符*前缀*匹配，因此放行该包也就放行了它那个会导入 cordis 的根部；该白名单是对面向客户端子路径的评审承诺，不是纯度证明。它还需要一个新导出与一处 `files` 修正，而且本来也帮不上忙——真正阻塞的冲突出在编译器，白名单碰不到那里。 +**从新叶子值导入该谓词**，并把 `dsh-compact` 加入客户端 `INLINE_SAFE` 白名单。已拒绝：客户端需要的是插件 id，不是谓词——一个类型就够了，而被擦除的导入根本不会抵达纯度门禁，因此无需向它放行任何东西。白名单只在值导入时才有意义，而在那里它是笔糟糕的交换：`INLINE_SAFE` 按标识符*前缀*匹配，因此放行该包会连它那个会导入 cordis 的根部一起放行。 **一条纯形状规则**——任何 replacement `user/message` 都是压缩。已拒绝：它今天正确只因为压缩是 replacement `user/message` 的唯一生产者，一旦这点改变便无任何机制能捕获。那个 pin 测试只花一个文件，就精确消除了这一风险。 diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts index 30e824324b..f673f43631 100644 --- a/apps/web/tests/seeded-history.e2e.ts +++ b/apps/web/tests/seeded-history.e2e.ts @@ -43,6 +43,7 @@ function withCompaction(raw: string): string { seq: number time: number surfaceOp?: unknown + data?: { turn?: unknown } }) const surfaceSeqs = events .filter(event => event.surfaceOp === 'append' @@ -57,44 +58,56 @@ function withCompaction(raw: string): string { if (first === undefined || last === undefined || tail === undefined) { throw new Error('seeded-history compaction requires a non-empty closed surface') } + // The transaction opens the turn after the recording's last closed one; read + // it from the fixture so a re-recording with a different turn count stays + // valid instead of appending a duplicate turn number. + const lastTurn = events.filter(event => event.type === 'turn/end').at(-1)?.data?.turn + if (typeof lastTurn !== 'number') { + throw new Error('seeded-history compaction requires a recording ending on a closed turn') + } + const turn = lastTurn + 1 let seq = tail.seq + 1 let time = tail.time + 1 - const at = (event: Record): string => JSON.stringify({ ...event, seq: seq++, time: time++ }) - // The checkpoint's provenance names the two events appended before it. - const startSeq = seq + 1 - const summarySeq = seq + 2 - lines.push( - at({ type: 'turn/start', data: { turn: 2, trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'compact' } } } }), - at({ type: 'compact/start', data: { turn: 2 } }), - at({ - type: 'compact/summary', - data: { - summary: [{ - type: 'text', - text: '## Cold resume compact summary\n\n- The exact summary remains available.', - }], - shadowedRange: { start: first, end: last }, - shadowedSeqs: surfaceSeqs, - shadowedTokenCount: 10_000, - provider: 'snapshot', - model: 'snapshot-compactor', - }, - }), - at({ - type: 'user/message', - data: { - content: [{ - type: 'text', - text: 'Model-only compact checkpoint.', - }], - source: { kind: 'plugin', plugin: 'compact' }, - }, - surfaceOp: { op: 'replace', start: first, end: last }, - sourceEventSeqs: [startSeq, summarySeq, ...surfaceSeqs], - }), - at({ type: 'compact/end', data: { turn: 2 } }), - at({ type: 'turn/end', data: { turn: 2, reason: { kind: 'completed' } } }), - ) + /** + * Append one event at the next seq/time. + * @param event - the event body, without seq/time. + * @returns the seq it took, so provenance cites the push instead of arithmetic over the push order below. + */ + const at = (event: Record): number => { + const taken = seq++ + lines.push(JSON.stringify({ ...event, seq: taken, time: time++ })) + return taken + } + at({ type: 'turn/start', data: { turn, trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'compact' } } } }) + const startSeq = at({ type: 'compact/start', data: { turn } }) + const summarySeq = at({ + type: 'compact/summary', + data: { + summary: [{ + type: 'text', + text: '## Cold resume compact summary\n\n- The exact summary remains available.', + }], + shadowedRange: { start: first, end: last }, + shadowedSeqs: surfaceSeqs, + shadowedTokenCount: 10_000, + provider: 'snapshot', + model: 'snapshot-compactor', + }, + }) + at({ + type: 'user/message', + data: { + content: [{ + type: 'text', + text: 'Model-only compact checkpoint.', + }], + source: { kind: 'plugin', plugin: 'compact' }, + }, + surfaceOp: { op: 'replace', start: first, end: last }, + sourceEventSeqs: [startSeq, summarySeq, ...surfaceSeqs], + }) + at({ type: 'compact/end', data: { turn } }) + at({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } }) return `${lines.join('\n')}\n` } diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 1f27744341..fe45b5b78b 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -486,7 +486,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:54`](../../packages/compact/compact/src/index.ts) +Source: [`packages/compact/compact/src/index.ts:45`](../../packages/compact/compact/src/index.ts) ## `ctx.directoryPicker` — `DirectoryPicker` (abstract seam) diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml index ec2fb497e6..e70060f5ac 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: 7bf8050ea988945bead491d02528906863b129a6 -README.zh.md: ff3c91dee956b2c65f0029c97c73d73f5a627b05 +README.md: 69576f1e23a34b83915d075c4120d04368c49f43 +README.zh.md: 7243a9119d9c669c76e8490bd271b2669568bff0 diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md index 7bf8050ea9..69576f1e23 100644 --- a/packages/client/runtime/README.md +++ b/packages/client/runtime/README.md @@ -18,7 +18,7 @@ SlotsService gives the renderer separate bare observables for `useSessions` and ## The human transcript -`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. That source literal is restated locally because `dsh-compact` is unreachable from this program in both directions (the client purity gate rejects a value import; a type-only import collides the host `Context.sessions` merge) — `tests/compact-checkpoint-pin.spec.ts` is the drift trap. +`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's). `tests/compact-checkpoint-pin.spec.ts` covers the same drift behaviorally. 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 one node, an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity. diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md index ff3c91dee9..7243a9119d 100644 --- a/packages/client/runtime/README.zh.md +++ b/packages/client/runtime/README.zh.md @@ -18,7 +18,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 ## 人类对话记录 -`ConversationSnapshot.nodes` 是人类对话记录，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口——每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，外加每次落地的压缩检查点贡献一个 `CompactionSummaryNode` 标记——且从不查询 surface 顺序。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩缝隙插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。该来源字面量在本地重述，因为 `dsh-compact` 在两个方向上都无法从本程序到达（客户端纯度门禁拒绝值导入；仅类型导入会与 host 的 `Context.sessions` 合并冲突）——`tests/compact-checkpoint-pin.spec.ts` 是漂移陷阱。 +`ConversationSnapshot.nodes` 是人类对话记录，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口——每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，外加每次落地的压缩检查点贡献一个 `CompactionSummaryNode` 标记——且从不查询 surface 顺序。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩缝隙插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩缝隙自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。`tests/compact-checkpoint-pin.spec.ts` 从行为侧覆盖同一漂移。 由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时该行不可展开而非空白，后续补上溯源的分页会解析出文本。性能契约：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。 diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts index fc9a9d6bcd..0e98eb8ae5 100644 --- a/packages/client/runtime/src/client/sessions/conversation.ts +++ b/packages/client/runtime/src/client/sessions/conversation.ts @@ -129,7 +129,14 @@ export interface CompactionSummaryNode { summary: string | null } -/** Fallback for surface events this UI version does not know. */ +/** + * Fallback for surface events this UI version does not know: the documented + * default arm of `SessionEventMap`, which is merge-extensible, so the + * projection's switch cannot end in `assertNever`. No event produces this node + * today — `isAppendSurfaceEvent` admits only the four types in core's + * `SurfaceEventType`, and each has its own arm — and it exists so widening that + * set core-side degrades to a raw row instead of dropping the event silently. + */ export interface UnknownSurfaceNode { kind: 'unknown' seq: number diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts index b79e6ee2fe..4985f263f4 100644 --- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts +++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts @@ -12,25 +12,26 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session/types' // browser bundle cannot resolve; surface.ts has no Node dependencies. import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface' import type { CommandId } from '@deepseek-ai/dsh-commands/brand' +// Cordis-free leaf subpath (the dsh-commands/brand shape): the seam's own +// declaration of the checkpoint source, reachable as a TYPE from this program. +// The package ROOT is not — it reaches dsh-session's root, whose Context merge +// declares the HOST `sessions: SessionStore` against this program's +// `sessions: ISessions` (TS2717, the one-program-per-side rule in +// docs/development.md). +import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint' import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client' import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts' import { toAssistantBlocks } from './conversation.ts' /** - * The compaction seam's checkpoint plugin, restated locally. - * - * `dsh-compact` cannot be reached from this program in any form. A VALUE import - * fails the client purity gate (`packages/client/tsdown.client.ts`) and would - * pull the cordis `Service` base into the browser bundle; a TYPE-ONLY import of - * its `COMPACT_CHECKPOINT_SOURCE` fails typecheck, because `dsh-compact`'s root - * reaches `dsh-session`'s root, whose `Context` merge declares the HOST - * `sessions: SessionStore` against this program's `sessions: ISessions` - * (`TS2717` — the one-program-per-side rule in docs/development.md). The - * literal is pinned to the canonical const by - * `tests/compact-checkpoint-pin.spec.ts`, which runs in the client TEST program - * where that collision does not apply. + * The compaction seam's checkpoint plugin, pinned to the seam's own declaration + * at COMPILE time: renaming it there fails this annotation (`TS2322`). The + * import stays type-only because a value import would fail the client purity + * gate (`packages/client/tsdown.client.ts`) — cross-plugin value imports are + * forbidden in a browser bundle — while an erased type never reaches it. + * `tests/compact-checkpoint-pin.spec.ts` covers the same drift behaviorally. */ -const COMPACT_PLUGIN = 'compact' +const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact' /** In-window tool/call index entry (result-card backfill + runningCalls material). */ export interface CallIndexEntry { @@ -126,14 +127,20 @@ function isTranscriptEvent(event: SessionEvent): boolean { return isAppendSurfaceEvent(event) || isCompactCheckpoint(event) } -/** Concatenated text of a `compact/summary` payload, or null when it carries no usable text. */ +/** + * Concatenated text of a `compact/summary` payload, or null when it carries no + * usable text. The payload is a `ContentBlock[]` whose union is + * merge-extensible, so a non-text block is skipped rather than discarding the + * text beside it; a payload with no text block at all falls to null through the + * empty check. + */ function compactSummaryText(event: SessionEvent): string | null { const summary = (event.data as unknown as { summary?: unknown }).summary - if (!Array.isArray(summary) || summary.length === 0) return null + if (!Array.isArray(summary)) return null let text = '' for (const block of summary as readonly unknown[]) { const candidate = block as { type?: unknown; text?: unknown } - if (candidate.type !== 'text' || typeof candidate.text !== 'string') return null + if (candidate.type !== 'text' || typeof candidate.text !== 'string') continue text += candidate.text } return text.trim() === '' ? null : text diff --git a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts index c657ebd036..f7f345d931 100644 --- a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts +++ b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts @@ -1,17 +1,15 @@ /** - * Drift trap for the compaction-checkpoint recognition rule. + * Behavioral half of the compaction-checkpoint drift trap. * - * `TranscriptAdapter` restates the compaction seam's checkpoint source as a - * local literal because it cannot import `dsh-compact` in any form: a VALUE - * import fails the client purity gate, and a TYPE-ONLY import fails typecheck — - * `dsh-compact`'s root reaches `dsh-session`'s root, whose cordis `Context` - * merge declares the HOST `sessions: SessionStore` against the client program's - * `sessions: ISessions` (`TS2717`). This spec runs in the client TEST program, - * which does not carry that collision, and it is the only thing keeping the two - * implementations from drifting: it drives the adapter with a checkpoint built - * from the canonical `COMPACT_CHECKPOINT_SOURCE` itself, so renaming the seam's - * plugin fails HERE instead of silently deleting every compaction marker from - * the web transcript. + * `TranscriptAdapter` pins its plugin literal to the seam's own declaration at + * compile time through a type-only import of `dsh-compact/checkpoint`, so + * renaming the seam's plugin already fails `tsc`. This spec covers the same + * drift from the other side — end to end through the adapter, driving it with a + * checkpoint built from the canonical `COMPACT_CHECKPOINT_SOURCE` **value** and + * checking the seam's own predicate agrees. It runs in the client TEST program, + * which can value-import the package root; a `packages/client/*` package + * program cannot, because that root reaches `dsh-session`'s root and collides + * the host `Context.sessions` merge (`TS2717`). */ import { COMPACT_CHECKPOINT_SOURCE, isCompactCheckpointSource } from '@deepseek-ai/dsh-compact' diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts index b53fcb0117..0c8aa9e12b 100644 --- a/packages/client/runtime/tests/transcript-adapter.spec.ts +++ b/packages/client/runtime/tests/transcript-adapter.spec.ts @@ -225,7 +225,7 @@ describe('TranscriptAdapter', () => { it.each([ ['absent provenance', undefined], - ['malformed summary blocks', compactSummary(1, [{ type: 'image', data: 'nope' }])], + ['text-less summary blocks', compactSummary(1, [{ type: 'image', data: 'nope' }])], ['a whitespace-only summary', compactSummary(1, [{ type: 'text', text: ' ' }])], ['an empty summary array', compactSummary(1, [])], ['a non-array summary', compactSummary(1, 'plain string')], @@ -240,6 +240,19 @@ describe('TranscriptAdapter', () => { ]) }) + it('keeps the text of a mixed-block summary, skipping the blocks it cannot render', () => { + // ContentBlock is merge-extensible and the payload type is ContentBlock[], + // so a non-text block must not discard recoverable text beside it. + const adapter = new TranscriptAdapter() + adapter.reset([ + compactSummary(1, [{ type: 'text', text: '可用摘要' }, { type: 'image', data: 'nope' }]), + checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }), + ]) + expect(adapter.nodes()).toEqual([ + { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: '可用摘要' }, + ]) + }) + it('leaves the summary null when the checkpoint records no provenance at all', () => { const adapter = new TranscriptAdapter() adapter.reset([at(2, { diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json index 7d3f05e6c7..d7968cce84 100644 --- a/packages/client/runtime/tsconfig.json +++ b/packages/client/runtime/tsconfig.json @@ -26,6 +26,9 @@ { "path": "../../ui/commands" }, + { + "path": "../../compact/compact" + }, { "path": "../../session-projection/session-projection" }, diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml index 921ee62a6d..5996c3b801 100644 --- a/packages/compact/compact/README.i18n.yaml +++ b/packages/compact/compact/README.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 -README.md: 17a5420ae9fa23ce4021b4d4927ae5b95962f979 -README.zh.md: d98251649cfdcf6b12e89a192a43b08b0f071f38 +# pnpm run verify-translation-pairing --write packages/compact/compact/README.md +README.md: b6386e8fed9c10cf072683fbdf78c85fb8ac8866 +README.zh.md: b59e03ccf846e88d328dfecdd76a2a490a966a0e diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md index 17a5420ae9..b6386e8fed 100644 --- a/packages/compact/compact/README.md +++ b/packages/compact/compact/README.md @@ -59,6 +59,10 @@ The `compact/*` events extend `SessionEventMap` (merge-extensible) via declarati Subclass `CompactService`, implement `compactIfNeeded` and `compactRegion`, and load the subclass as a plugin — it registers as `ctx.compact`. Every successful backend uses `COMPACT_CHECKPOINT_SOURCE` on its replacement user message; `isCompactCheckpointSource()` recognizes the marker after persistence or cloning without depending on backend identity. A template- or model-backed implementation can live as a sibling package without changing callers or the shared token meter. +## Recognizing a checkpoint outside the host program (`./checkpoint`) + +`COMPACT_CHECKPOINT_SOURCE` and `isCompactCheckpointSource()` are declared on the `@deepseek-ai/dsh-compact/checkpoint` subpath and re-exported from the root, so host-side consumers keep reading them from the root. The leaf imports no cordis and declares no module augmentation (the [`dsh-commands/brand`](../../ui/commands/README.md) shape), which is what lets a client or wire program name the checkpoint source: the package **root** cannot enter such a program at all, because it reaches `dsh-session`'s root and that `Context` merge declares the host `sessions` service against the client's own (`TS2717` — one program per side, per [development.md](../../../docs/development.md#typescript-project-layout)). The web client's transcript adapter pins its plugin literal to this leaf with a type-only import, so renaming the plugin id here is a compile error there. + ## Model Experience ### Conversation history, when a backend is invoked diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md index d98251649c..b59e03ccf8 100644 --- a/packages/compact/compact/README.zh.md +++ b/packages/compact/compact/README.zh.md @@ -59,6 +59,10 @@ 继承 `CompactService`，实现 `compactIfNeeded` 与 `compactRegion`，再将子类作为插件加载：它会注册为 `ctx.compact`。每个成功后端都在替换 user 消息上使用 `COMPACT_CHECKPOINT_SOURCE`；`isCompactCheckpointSource()` 可在持久化或克隆后识别该标记，无需依赖后端身份。基于模板或模型的实现可以放在同级包中，不需更改调用方或共享 token meter。 +## 在 host 程序之外识别检查点（`./checkpoint`） + +`COMPACT_CHECKPOINT_SOURCE` 与 `isCompactCheckpointSource()` 声明在 `@deepseek-ai/dsh-compact/checkpoint` 子路径上，并由包根重新导出，因此 host 侧消费方仍从根读取它们。该叶子不导入 cordis、也不声明任何模块增强（即 [`dsh-commands/brand`](../../ui/commands/README.md) 的形状），这正是客户端或 wire 程序能够命名该检查点来源的原因：包的**根**根本无法进入这类程序，因为它会到达 `dsh-session` 的根，而那处 `Context` 合并会让 host 的 `sessions` 服务与客户端自己的冲突（`TS2717`——每侧一个程序，见 [development.md](../../../docs/development.md#typescript-project-layout)）。Web 客户端的对话记录适配器用仅类型导入把它的插件字面量钉在该叶子上，因此在此处改插件 id 会让那边编译失败。 + ## 模型体验 ### 调用后端时的会话历史 diff --git a/packages/compact/compact/package.json b/packages/compact/compact/package.json index 135c688507..f0874990a3 100644 --- a/packages/compact/compact/package.json +++ b/packages/compact/compact/package.json @@ -15,12 +15,17 @@ "types": "./lib/types/invariant.d.ts", "default": "./lib/invariant.js" }, + "./checkpoint": { + "types": "./lib/types/checkpoint.d.ts", + "default": "./lib/types/checkpoint.js" + }, "./src/*": "./src/*", "./package.json": "./package.json" }, "files": [ "lib/index.js", "lib/invariant.js", + "lib/types/**/*.js", "lib/types/**/*.d.ts", "lib/types/**/*.d.ts.map", "src" diff --git a/packages/compact/compact/src/checkpoint.ts b/packages/compact/compact/src/checkpoint.ts new file mode 100644 index 0000000000..9d8b98e4d6 --- /dev/null +++ b/packages/compact/compact/src/checkpoint.ts @@ -0,0 +1,27 @@ +/** + * The compaction seam's canonical checkpoint source: the plugin marker every + * backend stamps on the replacement user message that lands a checkpoint, plus + * the predicate that recognizes it. + * + * The seam itself lives in `@deepseek-ai/dsh-compact`, which re-exports both of + * these; this module is a pure value/predicate outlet (no cordis imports, no + * module augmentation) so client and wire programs can name the checkpoint + * source without loading the host plugin's Context merges — the + * `dsh-commands/brand` shape. + * + * @module @deepseek-ai/dsh-compact/checkpoint + */ + +import type { MessageSource } from '@deepseek-ai/dsh-llm/message' + +/** Canonical source for the replacement user message produced by every compaction backend. */ +export const COMPACT_CHECKPOINT_SOURCE = Object.freeze({ kind: 'plugin', plugin: 'compact' } as const) + +/** + * Test whether a persisted message source identifies a compaction checkpoint. + * @param source - source restored from a surface user message. + * @returns whether the source carries the backend-independent checkpoint marker. + */ +export function isCompactCheckpointSource(source: MessageSource): boolean { + return source.kind === 'plugin' && source.plugin === COMPACT_CHECKPOINT_SOURCE.plugin +} diff --git a/packages/compact/compact/src/index.ts b/packages/compact/compact/src/index.ts index 2988a0b780..dd105ca5fb 100644 --- a/packages/compact/compact/src/index.ts +++ b/packages/compact/compact/src/index.ts @@ -8,24 +8,15 @@ */ import { Context, Service } from 'cordis' -import type { MessageSource } from '@deepseek-ai/dsh-llm' import type { Session } from '@deepseek-ai/dsh-session' import type { CompactionResult } from './types.ts' export type { CompactionResult } from './types.ts' export { toolPairingBalancedAfter, toolPairingBalancedBefore } from './tool-pairing.ts' - -/** Canonical source for the replacement user message produced by every compaction backend. */ -export const COMPACT_CHECKPOINT_SOURCE = Object.freeze({ kind: 'plugin', plugin: 'compact' } as const) - -/** - * Test whether a persisted message source identifies a compaction checkpoint. - * @param source - source restored from a surface user message. - * @returns whether the source carries the backend-independent checkpoint marker. - */ -export function isCompactCheckpointSource(source: MessageSource): boolean { - return source.kind === 'plugin' && source.plugin === COMPACT_CHECKPOINT_SOURCE.plugin -} +// The checkpoint source and its predicate are declared on the cordis-free +// `./checkpoint` leaf so client and wire programs can name them without this +// root's Context merge; the root stays the host-side entry point for both. +export { COMPACT_CHECKPOINT_SOURCE, isCompactCheckpointSource } from './checkpoint.ts' /** Why automatic policy is asking a backend to consider compaction. */ export type CompactionTrigger = 'pressure' | 'context-overflow' diff --git a/tsconfig.base.json b/tsconfig.base.json index 00c19c4b8c..a8dd18d660 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -54,6 +54,7 @@ "@deepseek-ai/dsh-llm/brand": ["./packages/llm/llm/src/brand.ts"], "@deepseek-ai/dsh-llm/message": ["./packages/llm/llm/src/message.ts"], "@deepseek-ai/dsh-commands/brand": ["./packages/ui/commands/src/brand.ts"], + "@deepseek-ai/dsh-compact/checkpoint": ["./packages/compact/compact/src/checkpoint.ts"], "@deepseek-ai/dsh-tools/presentation": ["./packages/core/tools/src/presentation.ts"], "@deepseek-ai/dsh-user-approval/types": ["./packages/ui/user-approval/src/types.ts"], "@deepseek-ai/dsh-user-interaction/types": ["./packages/ui/user-interaction/src/types.ts"], diff --git a/tsconfig.client.json b/tsconfig.client.json index 81681df038..43f1d635ba 100644 --- a/tsconfig.client.json +++ b/tsconfig.client.json @@ -36,11 +36,15 @@ // client-side Context merges keep it out of the host program. { "path": "./packages/host/directory-picker-native" }, { "path": "./packages/host/directory-picker-browse" }, - // Test-only leaf: the client-runtime drift trap for the compaction - // checkpoint source reads the seam's canonical const. It may appear HERE - // but never in a packages/client/* package project — dsh-compact's root - // reaches dsh-session's root, whose Context merge declares the host - // `sessions: SessionStore` and collides with the client's `ISessions`. + // Compaction seam: the client-runtime drift trap value-imports the seam's + // canonical checkpoint const from the package ROOT, which may be reached + // from this TEST program but never from a packages/client/* package + // program — the root reaches dsh-session's root, whose Context merge + // declares the host `sessions: SessionStore` and collides with the + // client's `ISessions`. Package programs use the cordis-free + // dsh-compact/checkpoint leaf instead (a type-only import in + // transcript-adapter.ts), which needs this reference on the runtime + // package project itself. { "path": "./packages/compact/compact" }, { "path": "./packages/client/ui-slots" }, { "path": "./packages/client/ui-primitives" }, From 7bcf5e3fb035613b369adac156beffb1a807aa09 Mon Sep 17 00:00:00 2001 From: Turtle Date: Thu, 30 Jul 2026 16:53:35 +0800 Subject: [PATCH 04/50] feat(cli): enable Node environment proxy in launcher --- bin/dsh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/bin/dsh b/bin/dsh index f85f28a5cd..c578d78e74 100755 --- a/bin/dsh +++ b/bin/dsh @@ -20,6 +20,7 @@ root=$(CDPATH='' cd -- "$(dirname -- "$script")/.." && pwd) # ESM-only and the CJS resolver costs ~0.4s of startup). Absolute paths keep # both the hook and the tsconfig anchored to this checkout when the launcher # runs from any cwd, where bare `tsx/esm` would not resolve. -TSX_TSCONFIG_PATH="$root/tsconfig.json" \ +NODE_USE_ENV_PROXY=1 \ + TSX_TSCONFIG_PATH="$root/tsconfig.json" \ exec node --import "$root/node_modules/tsx/dist/esm/index.mjs" \ "$root/apps/cli/src/bin.ts" "$@" From da41677049e0530a696ac335fb359e5d4117a4b8 Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Thu, 30 Jul 2026 17:10:45 +0800 Subject: [PATCH 05/50] fix(web): address transcript review follow-ups --- ...6-07-19-gui-web-client-architecture.i18n.yaml | 4 ++-- .../2026-07-19-gui-web-client-architecture.md | 2 +- .../2026-07-19-gui-web-client-architecture.zh.md | 4 ++-- .../2026-07-20-gui-testing-system.i18n.yaml | 4 ++-- .../process/2026-07-20-gui-testing-system.md | 2 +- .../process/2026-07-20-gui-testing-system.zh.md | 2 +- apps/web/tests/seeded-history.e2e.ts | 2 +- docs/core-data-structures/compaction.i18n.yaml | 4 ++-- docs/core-data-structures/compaction.md | 2 +- docs/core-data-structures/compaction.zh.md | 2 +- packages/client/runtime/README.i18n.yaml | 4 ++-- packages/client/runtime/README.md | 2 +- packages/client/runtime/README.zh.md | 2 +- packages/client/runtime/package.json | 2 +- .../src/client/sessions/transcript-adapter.ts | 16 ++++++---------- .../runtime/tests/compact-checkpoint-pin.spec.ts | 13 ++++++------- .../runtime/tests/transcript-adapter.spec.ts | 12 +----------- packages/client/test-runtime/README.i18n.yaml | 4 ++-- packages/client/test-runtime/README.md | 2 +- packages/client/test-runtime/README.zh.md | 2 +- packages/client/ui-conversation/README.i18n.yaml | 4 ++-- packages/client/ui-conversation/README.md | 3 +++ packages/client/ui-conversation/README.zh.md | 3 +++ pnpm-lock.yaml | 6 +++--- 24 files changed, 47 insertions(+), 56 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml index 6e1b952682..4530d5ee57 100644 --- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-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 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md -2026-07-19-gui-web-client-architecture.md: abe28b00638b4f01c7a50efe9ece5148e959a5ee -2026-07-19-gui-web-client-architecture.zh.md: 560015191fd8d99e2983a19d0b23aeb4dedff837 +2026-07-19-gui-web-client-architecture.md: 63b6f5795c3d49f25cd964cf04a0c9d41a667bfb +2026-07-19-gui-web-client-architecture.zh.md: 2d57c12ebae38aafa4e606da95af954990761b3c diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md index abe28b0063..63b6f5795c 100644 --- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md +++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md @@ -69,7 +69,7 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES── ``` - **Session** (session.ts): lazily built, resident — once created it keeps eating frames in the background, so switching away and back renders instantly. Operations: `prompt`/`cancel` (RPC passthrough; failures land in the snapshot's `promptError`), `open` (pull the tail history page, idempotent), `loadOlder` (upward paging, reentry-guarded), `resync` (reconnect = clear the window and rerun open). Subscription: `subscribe`/`getSnapshot` (always the cached reference) — `implements ObservableSnapshot`, with `useSelector = bindSnapshotSelector(this)` attached at construction, so a Session is directly a uSES source. Frame dispatch is one switch: `session/event` frames dedup by seq (the only dedup key), buffer while open is in flight, otherwise append + incremental projection; open/stitch merges the live buffer by seq and backfills once if `subscribed.lastSeq` outruns the window tail. -- **ConversationSnapshot** (conversation.ts): the immutable snapshot contract — `nodes` (the human transcript, log-ordered), `partial`, `runningCalls`, `pending`, `running`, `removed`, `openState`, `hasMore`, `promptError` and kin. **Reference discipline** (the premise of memo and uSES): the top-level object is fresh on every change; the nodes array is rebuilt but element references come from the cache; unchanged substructures reuse the previous snapshot's references. +- **ConversationSnapshot** (conversation.ts): the immutable snapshot contract — `nodes` (the human transcript, log-ordered), `partial`, `runningCalls`, `pending`, `running`, `removed`, `openState`, `hasMore`, `promptError` and kin. **Reference discipline** (the premise of memo and uSES): the top-level object is fresh on every change; an unchanged nodes projection keeps the same array reference, while a changed flow returns a new array that reuses unchanged element references; unchanged substructures reuse the previous snapshot's references. - **SessionManager** (manager.ts): instance cluster + frame entry + the session list. sessionId-bearing frames go only to existing instances (a mux broadcast must not instantiate every session); approval/question `requested` frames are the exception — they never land in history, so they buffer in `pendingBuffers` and replay on instantiation. - **Notifier** (notifier.ts): two channels chosen by change source. `markDirty()` (default; frame-driven changes always) batches per microtask — N changes, one notification, one re-render; the flush rebuilds the snapshot cache before notifying. `notifyNow()` (only direct echoes of user gestures) rebuilds and notifies in the same tick — controlled inputs roll the DOM back and jump the caret if their echo defers to a microtask. Frame-driven code using notifyNow collapses batching back to per-frame renders; banned. - **TranscriptAdapter / PartialAccumulator**: the transcript is the append-origin surface projected in log order (`isAppendSurfaceEvent` from `@deepseek-ai/dsh-session/surface`) plus one marker per landed compaction checkpoint — never the model surface, which shadows replaced ranges and would erase conversation the reader already saw. Node order is seq-monotonic by construction, so there is no core `seq === index` assertion to satisfy and no degradation branch. Chunks contribute no node (O(1) skip): the accumulator folds StreamChunks into `AssistantBlock[]`, a delta swapping only that block's reference, and the finalizing message discards the accumulator in the same batch (no flicker on promotion). Cost model: one chunk = one string concatenation + a dirty mark; an unsubscribed Session under a frame storm costs only the mark. diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md index 560015191f..2d57c12eba 100644 --- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md @@ -68,8 +68,8 @@ Session.handleMuxEnvelope ──► events 窗口（seq 连续升序） Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──► 组件 ``` -- **Session**（session.ts）：懒建、常驻——建成后在后台持续吃帧，切走切回秒显。操作面：`prompt`/`cancel`（RPC 透传；失败落进快照的 `promptError`）、`open`（拉尾页 history，幂等）、`loadOlder`（向上翻页，防重入）、`resync`（重连 = 清窗口重跑 open）。订阅面：`subscribe`/`getSnapshot`（恒返缓存引用）——`implements ObservableSnapshot`，构造时挂 `useSelector = bindSnapshotSelector(this)`，Session 本身就是 uSES 源。帧分发是一个 switch：`session/event` 帧按 seq 去重（唯一去重键），open 在途时缓冲，否则追加 + 增量 fold；open/缝合按 seq 合并 live 缓冲并去重，`subscribed.lastSeq` 超出窗口尾则回补一次。 -- **ConversationSnapshot**（conversation.ts）：不可变快照契约——`nodes`（人类对话记录，日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；nodes 数组重建但元素引用来自缓存；未变的子结构复用上一快照的引用。 +- **Session**（session.ts）：懒建、常驻——建成后在后台持续吃帧，切走切回秒显。操作面：`prompt`/`cancel`（RPC 透传；失败落进快照的 `promptError`）、`open`（拉尾页 history，幂等）、`loadOlder`（向上翻页，防重入）、`resync`（重连 = 清窗口重跑 open）。订阅面：`subscribe`/`getSnapshot`（恒返缓存引用）——`implements ObservableSnapshot`，构造时挂 `useSelector = bindSnapshotSelector(this)`，Session 本身就是 uSES 源。帧分发是一个 switch：`session/event` 帧按 seq 去重（唯一去重键），open 在途时缓冲，否则追加 + 增量投影；open/缝合按 seq 合并 live 缓冲并去重，`subscribed.lastSeq` 超出窗口尾则回补一次。 +- **ConversationSnapshot**（conversation.ts）：不可变快照契约——`nodes`（人类对话记录，日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；未变化的 nodes 投影保持同一数组引用，消息流变化时返回新数组并复用未变化的元素引用；未变的子结构复用上一快照的引用。 - **SessionManager**（manager.ts）：实例簇 + 帧总入口 + 会话列表。带 sessionId 的帧只投已存在实例（mux 广播不得把每个会话都实例化）；例外是审批/问答 `requested` 帧——它们不落 history、open 无法回补，故缓冲进 `pendingBuffers`，实例化时回放。 - **Notifier**（notifier.ts）：两条通知通道，按变更来源取用。`markDirty()`（默认；帧驱动一律用它）按微任务合批——N 次变更、一次通知、一次重渲染；flush 先重建快照缓存再通知。`notifyNow()`（仅用户手势的直接回响）同 tick 重建并通知——受控输入的回响若延到微任务，DOM 会回滚、光标跳尾。帧驱动代码用 notifyNow 会让合批塌回逐帧渲染；禁。 - **TranscriptAdapter / PartialAccumulator**：对话记录是按日志顺序投影的 append 来源 surface（`@deepseek-ai/dsh-session/surface` 的 `isAppendSurfaceEvent`），外加每次落地的压缩检查点一个标记——绝不用模型 surface，后者遮蔽被替换的范围，会抹掉读者已经看过的对话。节点顺序天然按 seq 单调，因此既无核心 `seq === index` 断言需要满足，也没有降级分支。分片不贡献任何节点（O(1) 跳过）：累积器把 StreamChunk 折叠成 `AssistantBlock[]`，一次增量只换该块引用；定稿消息到达即在同一批内弃掉累积器（提升无闪烁）。成本模型：一个分片 = 一次字符串拼接 + 一个脏标记；帧风暴下未订阅的 Session 只花那个标记。 diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml index 05d448c79b..deafb47f70 100644 --- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml +++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.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/process/2026-07-20-gui-testing-system.md -2026-07-20-gui-testing-system.md: 8c6dafb18fc207fc4eac780ba18e108267bc28b1 -2026-07-20-gui-testing-system.zh.md: 9a0de4bfa8fa2f8de55beef53bedde51649c5d9c +2026-07-20-gui-testing-system.md: 4a1600bbef7ef795677a446228fcc279a4b53f39 +2026-07-20-gui-testing-system.zh.md: 2aa5d7f66783c69964cabf7eb18a018b54528a33 diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md index 8c6dafb18f..4a1600bbef 100644 --- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md +++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md @@ -22,7 +22,7 @@ Cut along the architecture's natural test seams into three tiers, bottom-up: | 2 Object-layer orchestration | `Session`/`SessionManager`/`ConnectionController` (state machines and timing: stitching / dedup / paging / optimistic draft clearing / pendingBuffers / reconnect / backoff) | **The "event sequence in → snapshot out" golden path**: programmable fakes + deferreds controlling timing + fake timers controlling backoff | `packages/client/{runtime,connection}/tests/` | | 3 Assembled presentation | Built artifacts × the real client loader and plugin composition | App-owned semantic snapshots boot all eight built client plugins under jsdom for deterministic cross-plugin state changes; bare Playwright smoke separately proves the real browser/carrier boundary, with real-host cases self-skipping without a key; the keyless browser e2e lane disables the shipped model-adapter row and replays recorded session fixtures through `dsh-llm-replay` in the real in-process web assembly against conversation aria goldens ([web e2e lane](../testing/2026-07-24-web-gui-browser-e2e-lane.md), [required CI gate](../testing/2026-07-30-web-browser-snapshot-ci-gate.md)) | `apps/web/tests/*.snapshot.ts`, `apps/web/tests/smoke-{fixture,real}.e2e.ts`, `apps/web/tests/{replay-round-trip,seeded-history}.e2e.ts` | -Inter-tier discipline: **each tier tests its own layer, upper tiers never re-test lower ones** — an app semantic snapshot pins only user-visible projection across the assembled plugin boundary, while Playwright smoke proves browser and carrier liveness; wire semantics belong to tier 1 and data semantics to tier 2. Pure-function layers (lineage/partial/notifier/fold-adapter) are tested directly with zero fakes in the same package's tests/ alongside tier 2. +Inter-tier discipline: **each tier tests its own layer, upper tiers never re-test lower ones** — an app semantic snapshot pins only user-visible projection across the assembled plugin boundary, while Playwright smoke proves browser and carrier liveness; wire semantics belong to tier 1 and data semantics to tier 2. Pure-function layers (lineage/partial/notifier/transcript-adapter) are tested directly with zero fakes in the same package's tests/ alongside tier 2. - **Host and client source** are under the repo-wide per-file 100% coverage gate except the narrow browser-grade exclusions annotated in `vitest.config.ts`; component suites use per-file jsdom pragmas and Testing Library without changing Node suites. - **App-owned semantic snapshots** read built client bundles, execute them through the real loader, and drive only deterministic fixture hooks. They own stable visible state such as sidebar labels, breadcrumbs, and `document.title`, not CSS pixels or lower-layer state-machine details. diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md index 9a0de4bfa8..2aa5d7f667 100644 --- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md +++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md @@ -22,7 +22,7 @@ GUI 栈需要考虑多种应用形态，同应用形态内的不同运行环境 | 2 对象层编排 | `Session`/`SessionManager`/`ConnectionController`（状态机与时序：缝合/去重/翻页/乐观清稿/pendingBuffers/重连/退避） | **「事件序列进→快照出」黄金路径**：可编程假体 + deferred 控时序 + fake timers 控退避 | `packages/client/{runtime,connection}/tests/` | | 3 组装呈现层 | 构建产物 × 真实 client loader 与插件组合 | 归应用所有的语义快照会在 jsdom 下启动全部 8 个已构建的 client 插件，以固定确定性的跨插件状态变化；独立使用 Playwright 裸库的冒烟测试负责验证真实浏览器/承载层边界，真 host 用例在无密钥时自行跳过；无密钥浏览器 e2e 车道会禁用交付配置中的模型适配器行，并通过 `dsh-llm-replay` 在真实进程内 web 组装中回放录制的会话 fixture，与会话区 aria 期望输出比对（[web e2e 车道](../testing/2026-07-24-web-gui-browser-e2e-lane.md)、[必需 CI 门禁](../testing/2026-07-30-web-browser-snapshot-ci-gate.md)） | `apps/web/tests/*.snapshot.ts`、`apps/web/tests/smoke-{fixture,real}.e2e.ts`、`apps/web/tests/{replay-round-trip,seeded-history}.e2e.ts` | -层间纪律：**下层各测各的，上层不重测下层**：应用语义快照只固定组装后插件边界上的用户可见投影，Playwright 冒烟测试负责验证浏览器与承载层是否存活；wire 语义归 1 层，数据语义归 2 层。纯函数层（lineage/partial/notifier/fold-adapter）随 2 层同包 tests/ 零假体直测。 +层间纪律：**下层各测各的，上层不重测下层**：应用语义快照只固定组装后插件边界上的用户可见投影，Playwright 冒烟测试负责验证浏览器与承载层是否存活；wire 语义归 1 层，数据语义归 2 层。纯函数层（lineage/partial/notifier/transcript-adapter）随 2 层同包 tests/ 零假体直测。 - **host 与 client 源码**均纳入全仓 per-file 100% 覆盖率门禁，仅排除 `vitest.config.ts` 中带注释的少量浏览器级例外；组件套件通过逐文件 jsdom pragma 和 Testing Library 运行，不会改变 Node 套件。 - **归应用所有的语义快照**读取已构建的 client bundle，通过真实 loader 执行它们，并且只驱动确定性的 fixture 钩子。它们负责固定侧边栏标签、面包屑和 `document.title` 等稳定可见状态，而不固定 CSS 像素或下层状态机细节。 diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts index 485c2bc05b..fb3b266625 100644 --- a/apps/web/tests/seeded-history.e2e.ts +++ b/apps/web/tests/seeded-history.e2e.ts @@ -246,7 +246,7 @@ describe('web e2e: seeded history renders through cold resume', () => { timeout: 5_000, }).toBe(1) expect(await page.getByText('The exact summary remains available.', { exact: false }).count()).toBeGreaterThan(0) - // Collapse again so the aria golden captured after this case is unaffected. + // Restore the shared page state for any later case. await marker.click() await expect.poll(() => marker.getAttribute('aria-expanded'), { timeout: 5_000 }).toBe('false') }) diff --git a/docs/core-data-structures/compaction.i18n.yaml b/docs/core-data-structures/compaction.i18n.yaml index 89783b5d16..a933e793c4 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: 911b71d00fa4b42e9cdfa67f67d4e9b29e354a4a -compaction.zh.md: 643a116ff2edbbb53d300b4f5ff0ad36d401130b +compaction.md: 3ae4d7e50452b549654b7a7162141a4be505d784 +compaction.zh.md: 448c3aaf298b65ebe88565190c5b3978b975f5f3 diff --git a/docs/core-data-structures/compaction.md b/docs/core-data-structures/compaction.md index 911b71d00f..3ae4d7e504 100644 --- a/docs/core-data-structures/compaction.md +++ b/docs/core-data-structures/compaction.md @@ -60,7 +60,7 @@ 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 the package-exported `COMPACT_CHECKPOINT_SOURCE`; consumers call `isCompactCheckpointSource()` instead of coupling checkpoint recognition to 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. +`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. 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 643a116ff2..448c3aaf29 100644 --- a/docs/core-data-structures/compaction.zh.md +++ b/docs/core-data-structures/compaction.zh.md @@ -60,7 +60,7 @@ interface CompactionResult { type CompactionTrigger = 'pressure' | 'context-overflow' ``` -`CompactService` 暴露 `compactIfNeeded(agent, trigger, signal)` 以执行自动 `pressure` 或 `context-overflow` 策略；没有可安全执行的工作时返回 `null`。它还针对显式、两端均包含的 surface 范围暴露 `compactRegion(...)`。每个后端都使用包导出的 `COMPACT_CHECKPOINT_SOURCE` 标记其替换用的 `user/message`；消费方调用 `isCompactCheckpointSource()`，而不是把检查点识别逻辑耦合到某一个后端。实现必须把传入的 signal 转发给摘要流程。该 seam 不拥有计价 API：单例 [`ctx.tokenMeter`](token-meter.md) 直接拥有估算与回放，而 `dsh-compact-basic` 拥有保留策略、事件排序、按路由执行的摘要调用及其配置。 +`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` 拥有保留策略、事件排序、按路由执行的摘要调用及其配置。 压力压缩在串行 `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/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml index 483d34e8d3..3b19ab54c4 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: 51e13d2c68dce3c0c12e04ad0940af8a1e76a4bc -README.zh.md: 9cebc6e7489da65d18d6b308a4991aad06fc1193 +README.md: 63876e2f2c762c5eeff95e065338413017e0a333 +README.zh.md: efa5e841efad1e5ce0f8c3af63eba00bcae1a363 diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md index 51e13d2c68..63876e2f2c 100644 --- a/packages/client/runtime/README.md +++ b/packages/client/runtime/README.md @@ -24,7 +24,7 @@ SlotsService gives the renderer separate bare observables for `useSessions` and `ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's). `tests/compact-checkpoint-pin.spec.ts` covers the same drift behaviorally. -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 one node, an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity. +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. ## Code Mode sub-dispatch index diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md index 9cebc6e748..efa5e841ef 100644 --- a/packages/client/runtime/README.zh.md +++ b/packages/client/runtime/README.zh.md @@ -24,7 +24,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 `ConversationSnapshot.nodes` 是人类对话记录，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口——每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，外加每次落地的压缩检查点贡献一个 `CompactionSummaryNode` 标记——且从不查询 surface 顺序。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩缝隙插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩缝隙自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。`tests/compact-checkpoint-pin.spec.ts` 从行为侧覆盖同一漂移。 -由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时该行不可展开而非空白，后续补上溯源的分页会解析出文本。性能契约：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。 +由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时该行不可展开而非空白，后续补上溯源的分页会解析出文本。性能契约：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。 ## Code Mode 子调用索引 diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json index 3868ab8d8c..a6f96b9d47 100644 --- a/packages/client/runtime/package.json +++ b/packages/client/runtime/package.json @@ -32,6 +32,7 @@ "license": "BSD-3-Clause", "dependencies": { "@deepseek-ai/dsh-client-connection": "workspace:^", + "@deepseek-ai/dsh-compact": "workspace:^", "@deepseek-ai/dsh-commands": "workspace:^", "@deepseek-ai/dsh-client-ui-slots": "workspace:^", "@deepseek-ai/dsh-host-apiproxy": "workspace:^", @@ -48,7 +49,6 @@ "cordis": "^4.0.0-rc.7" }, "devDependencies": { - "@deepseek-ai/dsh-compact": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@types/react": "~18.3.1", "cordis": "^4.0.0-rc.7" diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts index 4985f263f4..6fae44ede4 100644 --- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts +++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts @@ -33,8 +33,8 @@ import { toAssistantBlocks } from './conversation.ts' */ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact' -/** In-window tool/call index entry (result-card backfill + runningCalls material). */ -export interface CallIndexEntry { +/** In-window tool/call index entry used to materialize result cards. */ +interface CallIndexEntry { name: string argsRaw: string turn: number @@ -194,11 +194,6 @@ export class TranscriptAdapter { private rev = 0 private nodesResult: { rev: number; value: readonly ConversationNode[] } | null = null - /** In-window tool/call index (Session uses it for runningCalls and result-card backfill). */ - get callIndex(): ReadonlyMap { - return this.callIdx - } - /** * Window rebuild (after open/resync/page prepend): re-index the raw window * and re-project the transcript. @@ -230,9 +225,10 @@ export class TranscriptAdapter { /** * Tail append (live session/event): index the event and, when it belongs to - * the transcript, extend the projection by one node — O(1) per append. An - * event that changes no node (a chunk storm) bumps no revision, so nodes() - * keeps returning the same array reference. + * the transcript, extend the projection by one copy-on-write node so a + * published array never mutates. An event that changes no node (a chunk + * storm) bumps no revision, so nodes() keeps returning the same array + * reference. * @param event - the live event (seq = window tail + 1). * @param view - host-computed tool view paired with the event when it is a tool call/result; indexed for card rendering. */ diff --git a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts index f7f345d931..ddc6c8adc5 100644 --- a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts +++ b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts @@ -5,14 +5,13 @@ * compile time through a type-only import of `dsh-compact/checkpoint`, so * renaming the seam's plugin already fails `tsc`. This spec covers the same * drift from the other side — end to end through the adapter, driving it with a - * checkpoint built from the canonical `COMPACT_CHECKPOINT_SOURCE` **value** and - * checking the seam's own predicate agrees. It runs in the client TEST program, - * which can value-import the package root; a `packages/client/*` package - * program cannot, because that root reaches `dsh-session`'s root and collides - * the host `Context.sessions` merge (`TS2717`). + * checkpoint built from the canonical `COMPACT_CHECKPOINT_SOURCE` value and + * checking the seam's own predicate agrees. Both values come from the + * cordis-free checkpoint leaf, so the client test program never loads the host + * package root or its `Context` merges. */ -import { COMPACT_CHECKPOINT_SOURCE, isCompactCheckpointSource } from '@deepseek-ai/dsh-compact' +import { COMPACT_CHECKPOINT_SOURCE, isCompactCheckpointSource } from '@deepseek-ai/dsh-compact/checkpoint' import { createUserMessage } from '@deepseek-ai/dsh-llm' import { describe, expect, it } from 'vitest' import type { SessionEvent } from '@deepseek-ai/dsh-session/types' @@ -40,7 +39,7 @@ describe('compaction checkpoint recognition', () => { expect(adapter.nodes()).toEqual([{ kind: 'compaction', seq: 1, time: 1_700_000_000_001, summary: null }]) }) - it('agrees with the seam s own predicate on the source it recognizes', () => { + it("agrees with the seam's own predicate on the source it recognizes", () => { // Both sides answer the same question about the same value: if the seam // renames its plugin, this equality is what breaks. const checkpoint = canonicalCheckpoint(1) diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts index 0c8aa9e12b..cc03d349b8 100644 --- a/packages/client/runtime/tests/transcript-adapter.spec.ts +++ b/packages/client/runtime/tests/transcript-adapter.spec.ts @@ -316,15 +316,7 @@ describe('TranscriptAdapter', () => { expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', isError: true, error: { code: 'boom' } }) }) - it('exposes the in-window call index for runningCalls material', () => { - const adapter = new TranscriptAdapter() - adapter.reset([ev.toolCall(0, 1, 'c9', 'slow', '{}')]) - expect(adapter.callIndex.get('c9')).toMatchObject({ name: 'slow', turn: 1 }) - adapter.append(ev.toolCall(1, 1, 'c10', 'fast', '{}')) - expect(adapter.callIndex.size).toBe(2) - }) - - it('attaches wire views: callView into the call index, resultView onto the node by seq', () => { + it('attaches wire views to the materialized result node', () => { const adapter = new TranscriptAdapter() const callView = { for: 'call' as const, view: { card: 'terminal' as const, command: 'ls' } } const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '完成' } } @@ -332,7 +324,6 @@ describe('TranscriptAdapter', () => { ev.toolCall(0, 1, 'c1', 'bash', '{"cmd":"ls"}'), ev.toolResult(1, 1, 'c1', 'listing'), ], [callView, resultView] as never) - expect(adapter.callIndex.get('c1')).toMatchObject({ callView: { card: 'terminal' } }) expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({ callView: { card: 'terminal' }, resultView: { card: 'generic', title: '完成' }, }) @@ -343,7 +334,6 @@ describe('TranscriptAdapter', () => { adapter.reset(plainTurn(0, 0, 'a', 'b')) // no views argument adapter.append(ev.toolCall(6, 1, 'c2', 'echo', '{}'), { for: 'call', view: { card: 'generic', title: '回声' } } as never) adapter.append(ev.toolResult(7, 1, 'c2', 'ok')) // no view on the result - expect(adapter.callIndex.get('c2')).toMatchObject({ callView: { title: '回声' } }) expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({ callView: { title: '回声' }, resultView: null, }) diff --git a/packages/client/test-runtime/README.i18n.yaml b/packages/client/test-runtime/README.i18n.yaml index 73a4705b1b..fe40088b11 100644 --- a/packages/client/test-runtime/README.i18n.yaml +++ b/packages/client/test-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/test-runtime/README.md -README.md: 883d71224139dc409229fdfb35362d040e810cc7 -README.zh.md: a3daf112940b03b585d44bc5fd1317e43ebd35fe +README.md: dc8ee8cadf5e61af15f04b1b9842af1eb658c031 +README.zh.md: a4c889d8a0291b52c8509403748df6b93567788e diff --git a/packages/client/test-runtime/README.md b/packages/client/test-runtime/README.md index 883d712241..dc8ee8cadf 100644 --- a/packages/client/test-runtime/README.md +++ b/packages/client/test-runtime/README.md @@ -21,4 +21,4 @@ None; this package neither assembles nor sends a provider request. ## Known Limitations and Deferred Work - **Consumed through repository source aliases only.** Specs resolve the package through tsconfig `paths` to `src`; the built `lib/` artifact re-exports `@deepseek-ai/dsh-client-runtime/client`, whose bundle is a browser loader script with no Node ESM exports, so `lib/index.js` is not importable under plain Node. Acceptable while every consumer is an in-repo Vitest suite; a Node-compatible runtime entry is deferred until an out-of-repo consumer exists. -- **Conversation snapshots are fixture data, not replayed history.** `updateSnapshot` writes the snapshot store directly; the wire-to-snapshot computation stays covered by the runtime package's own tests and the replay e2e. A fixture can therefore express states the production fold would never produce. +- **Conversation snapshots are fixture data, not replayed history.** `updateSnapshot` writes the snapshot store directly; the wire-to-snapshot computation stays covered by the runtime package's own tests and the replay e2e. A fixture can therefore express states the production projection would never produce. diff --git a/packages/client/test-runtime/README.zh.md b/packages/client/test-runtime/README.zh.md index a3daf11294..a4c889d8a0 100644 --- a/packages/client/test-runtime/README.zh.md +++ b/packages/client/test-runtime/README.zh.md @@ -21,4 +21,4 @@ ## Known Limitations and Deferred Work - **仅可经仓内源码别名消费。** spec 通过 tsconfig `paths` 解析到 `src`；构建产物 `lib/` 再导出 `@deepseek-ai/dsh-client-runtime/client`，而该 bundle 是无 Node ESM 导出的浏览器 loader 脚本，故 `lib/index.js` 在纯 Node 下不可导入。当前所有消费方都是仓内 Vitest 套件，可接受；Node 兼容的运行时入口待出现仓外消费方再补。 -- **会话快照是 fixture 数据，不是重放历史。** `updateSnapshot` 直写快照 store；wire 到快照的运算仍由 runtime 包自身测试与 replay e2e 把守。因此 fixture 可以表达生产折叠永不产出的状态。 +- **会话快照是 fixture 数据，不是重放历史。** `updateSnapshot` 直写快照 store；wire 到快照的运算仍由 runtime 包自身测试与 replay e2e 把守。因此 fixture 可以表达生产投影永不产出的状态。 diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index 654722b589..d4ea0caf53 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: 3973c14f2b8fe746549bb74af85a7a60a7d66aea -README.zh.md: a6bb15c4cdd53d05bf28147b97d9d64d1c59da2b +README.md: b9a4fd7de61ed8ce01417cc97ebfd80c312d37bf +README.zh.md: 3a79336f3cb40bf5682aabeb6503d71a1ee36746 diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index 3973c14f2b..b9a4fd7de6 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -4,6 +4,8 @@ English | [中文](README.zh.md) Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, per-tool row slot with a bash sample registrant and the todo row), composer dock (session stats sticky with the input), input dock (queue rows plus the todo plan strip), minimal details panel, scope-addressed ConversationService. Contract: api-contracts v3 §7 plus the slot terminal design (store seat / props shares). +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 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. @@ -34,6 +36,7 @@ None; this package neither assembles nor sends a provider request. ## Known Limitations and Deferred Work +- **Compaction markers show no scale** — the row does not yet report how many messages or which range the checkpoint replaced. - **Stats-line durations cover the in-window flow only** — LLM and tool wall times fold the snapshot's assistant `timing` and tool call/result pairs, so nodes outside the loaded event window (older history) are not counted. - **Details panel is the minimal form and currently has no entry point** — selected call args/result raw display; the Input/Output/Metadata switch, Prev/Next stepping, and See-in-trajectory deep link are deferred. Tool rows stopped being details-panel click targets and nothing replaced that gesture, so `ChatViewInjected.openDetails` is implemented but uncalled and the panel (including its terminal card) is unreachable in the assembled application; its rendering stays covered by mounting it with a selection directly. - **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / branch / clock) ships under text output only; branch remains a chrome stub. diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index a6bb15c4cd..3a79336f3c 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -4,6 +4,8 @@ 会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离、逐工具行 slot 及一个 bash 示例注册方与 todo 行）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（队列行加 todo 计划条）、最小详情面板、按 scope 寻址的 ConversationService。契约：api-contracts v3 §7 加 slot 终端设计（store seat／props share）。 +压缩在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的对话记录。展开内容来自检查点溯源的 `compact/summary`；该事件位于已加载窗口之外时，标记仍然可见但不可展开。面向模型的带框检查点载荷绝不渲染。 + 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段会话标题栏以普通列 chrome 占据顶部；其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。 视图环本身就是 slot：会话注册声明 `'conversation.view'` 列表 slot（Session scope），并将其列在 `children` 表中；ConversationRoot 通过 renderSlot share 渲染活跃配置项（`only: `）；视图标签页从环账本的注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的环配置项；其他插件（ui-trajectory）通过普通的 `ctx.slots.register` 贡献标签页。先前包内的视图注册表（`registerView`／`ViewEntry`／`ConversationViewMap` 及 chrome 附加表）已退役，逐视图 chrome 则被拆入视图组件自身。 @@ -34,6 +36,7 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插 ## 已知限制与暂缓事项 +- **压缩标记不显示规模**：该行尚不报告检查点替换了多少条消息或哪段范围。 - **统计行的耗时只覆盖窗口内消息流**：LLM 与工具墙钟时间由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。 - **详情面板是最小形态，且当前没有入口**：以原始形式显示已选择调用的参数／结果；Input/Output/Metadata 切换、Prev/Next 步进与 See-in-trajectory 深链接暂缓实现。工具行已不再是详情面板的点击目标，且没有任何手势接替它，因此 `ChatViewInjected.openDetails` 虽已实现却无人调用，该面板（含其终端卡片）在组装后的应用中不可达；其渲染仍由直接以选中态挂载它来覆盖。 - **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／分支／时钟）只挂在 text 输出下；分支仍是 chrome stub。 diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4f1cf3d328..ea8592962e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -938,6 +938,9 @@ importers: '@deepseek-ai/dsh-client-connection': specifier: workspace:^ version: link:../connection + '@deepseek-ai/dsh-compact': + specifier: workspace:^ + version: link:../../compact/compact '@deepseek-ai/dsh-client-ui-slots': specifier: workspace:^ version: link:../ui-slots @@ -969,9 +972,6 @@ importers: specifier: ~4.4.7 version: 4.4.7(@types/react@18.3.31)(immer@10.2.0)(react@18.3.1) devDependencies: - '@deepseek-ai/dsh-compact': - specifier: workspace:^ - version: link:../../compact/compact '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../support/invariants From e3ece4b22c3000f74774e8d34f9cc0615a324b6d Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Thu, 30 Jul 2026 18:11:00 +0800 Subject: [PATCH 06/50] test(web): isolate snapshots from user skills --- apps/web/tests/scaffold.ts | 12 ++++++++++++ .../tests/snapshots/code-mode-round/ui.expected.md | 1 - .../tests/snapshots/cordis-tool-round/ui.expected.md | 1 - .../tests/snapshots/fresh-round-trip/ui.expected.md | 1 - .../snapshots/lifecycle-chrome/reloaded.expected.md | 1 - .../snapshots/live-interactions/cancel.expected.md | 1 - .../live-interactions/error-auth.expected.md | 1 - .../snapshots/live-interactions/retry.expected.md | 1 - .../snapshots/question-composer/answered.expected.md | 1 - .../snapshots/queue-actions/editing.expected.md | 1 - .../web/tests/snapshots/queue-actions/ui.expected.md | 1 - .../tests/snapshots/steering/mid-steer.expected.md | 1 - .../web/tests/snapshots/steering/settled.expected.md | 1 - 13 files changed, 12 insertions(+), 12 deletions(-) diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts index 753cdc2953..4ede8ca908 100644 --- a/apps/web/tests/scaffold.ts +++ b/apps/web/tests/scaffold.ts @@ -10,6 +10,8 @@ // // Composition divergences from `dsh web`, all deliberate, all via include // patches over the SAME tree (never a second yml): temp persistenceRoot; +// user skill roots redirected to empty temp directories (project skill +// discovery remains real); // workspace-context disabled (recorded fixtures must not embed this repo's // AGENTS.md); session-title-llm disabled (its fire-and-forget title call // would race the loop for the session's replay cursor); webserver pinned to @@ -169,6 +171,16 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise Date: Thu, 30 Jul 2026 20:25:02 +0800 Subject: [PATCH 07/50] fix(web): let the pointer reach hover cards and row menus The workspace browser's two hover-raised popups both died on the way to them. HoverCard closed on the first pointerleave and rendered its card pointer-events:none, but the card sits 8px off the anchor, so every path to it crossed ground belonging to neither. The row action menus put closeOnPointerLeave's handler on the portaled list, so aiming back at the ... trigger that opened it, or overshooting a list edge, closed it with no window to come back. usePointerGrace owns one cancelable delayed close (200ms) shared by both atoms: leaving arms it, returning cancels it. The hover card becomes hit-testable so resting on it holds it open, and Menu moves pointer-leave dismissal to the wrapper span, where React's enter/leave traversal makes trigger and portaled list one region. Both gestures are pinned in the real browser lane; each fails without the corresponding fix. --- ...-07-30-hover-popup-pointer-grace.i18n.yaml | 6 ++ .../2026-07-30-hover-popup-pointer-grace.md | 35 ++++++++ ...2026-07-30-hover-popup-pointer-grace.zh.md | 35 ++++++++ apps/web/tests/workspace-management.e2e.ts | 76 +++++++++++++---- .../ui-primitives/src/HoverCard.module.css | 5 +- .../client/ui-primitives/src/HoverCard.tsx | 24 ++++-- packages/client/ui-primitives/src/Menu.tsx | 28 ++++++- .../client/ui-primitives/src/pointer-grace.ts | 53 ++++++++++++ .../client/ui-primitives/tests/atoms.spec.tsx | 84 ++++++++++++++++--- .../ui-primitives/tests/hover-card.spec.tsx | 33 +++++++- 10 files changed, 341 insertions(+), 38 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.md create mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.zh.md create mode 100644 packages/client/ui-primitives/src/pointer-grace.ts diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.i18n.yaml new file mode 100644 index 0000000000..b87f5de3b1 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.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-30-hover-popup-pointer-grace.md +2026-07-30-hover-popup-pointer-grace.md: e999fdea482c14b3b7864df4ba4cba55a89cd7b2 +2026-07-30-hover-popup-pointer-grace.zh.md: 100dfc5b37ed547a8615b2f0f9c3c225a1b592b5 diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.md b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.md new file mode 100644 index 0000000000..e999fdea48 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.md @@ -0,0 +1,35 @@ +# Agent Note: Hover popup pointer grace + +Status: implemented + +English | [中文](2026-07-30-hover-popup-pointer-grace.zh.md) + +## Problem + +Both popups the workspace browser rows raise floated out of reach of the pointer. `HoverCard` closed on the first `pointerleave` from its anchor and rendered its card `pointer-events: none`, but the card sits 8px off the anchor's right edge, so every path to it crossed ground belonging to neither and killed the card before it arrived — the full workspace path and session title it exists to show could be read only in passing. The row action menus passed `closeOnPointerLeave`, whose handler sat on the portaled list: aiming back at the `...` trigger that opened the list closed it, and so did any overshoot past a list edge, with no window to come back. + +## Decision + +`usePointerGrace` ([packages/client/ui-primitives/src/pointer-grace.ts](../../../../packages/client/ui-primitives/src/pointer-grace.ts)) owns one cancelable delayed close, shared by both atoms, with `POINTER_GRACE_MS` at 200. Leaving arms the close; coming back cancels it. Transit through an anchor-to-popup gap is therefore survivable, while a pointer that has genuinely moved on still dismisses the popup. + +`HoverCard` arms the grace on leave instead of closing, and its card no longer sets `pointer-events: none`, so resting on the card holds it open. Re-entering while already open cancels the pending close without restarting the dwell, which keeps the card from blinking when the pointer crosses the gap. A press inside the anchor and an owner flipping `disabled` still dismiss immediately, ahead of the grace. + +`Menu` moves pointer-leave dismissal from the portaled list to the wrapper span. React's enter/leave traversal runs over the React tree, so the trigger and the portaled list are one region there: crossing the 4px gap between them, or aiming back at the trigger, no longer counts as leaving. Leaving is only armed while the list is open, and an owner-driven close (selection, Escape, outside click) disarms a pending grace close in an effect keyed on `open` alone — folding that into the outside-click effect would cancel the grace on every re-render, since owners pass a fresh `onClose` closure each time. + +## Alternatives considered + +**Close the popups only on outside click and Escape.** Rejected because both popups are hover-raised and unlabeled as dismissible; leaving them up after the pointer has moved to another row would strand a card over unrelated content. + +**Widen the anchor's hit area to abut the popup.** Rejected because the 8px and 4px offsets are the design's, and an invisible bridge element would have to track every reposition the fixed-positioned popups already do on scroll and resize. + +**Keep the hover card `pointer-events: none` and only add the grace.** Rejected because the pointer resting on the card would then hit whatever is behind it, so the grace would expire and close the card the user had just reached. + +**Give each atom its own timer.** Rejected because the two closes are the same behavior with the same tuning; a shared hook keeps them from drifting apart. + +## Consequences + +The hover card is now hit-testable and covers 244px of whatever it overlays while shown, which is the price of being reachable; it still lives only as long as the pointer is on the row or the card. Row menus survive the round trip between trigger and list, and a menu that closes for its own reason cannot be reopened into a stale pending close. Menus without `closeOnPointerLeave` are untouched — the wrapper handlers are only attached when it is set. + +## Testing + +`packages/client/ui-primitives/tests/hover-card.spec.tsx` and `tests/atoms.spec.tsx` pin the grace boundary, cancel-on-return, no-second-dwell, disarm-on-owner-close, and the no-arming-while-closed case. The reachability gestures themselves — hovering onto the card, and moving between an open list and its trigger — are pinned in the real browser by `apps/web/tests/workspace-management.e2e.ts`, since they depend on hit testing and layout that jsdom does not model. diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.zh.md new file mode 100644 index 0000000000..100dfc5b37 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.zh.md @@ -0,0 +1,35 @@ +# Agent Note: 悬浮弹层的指针宽限期 + +Status: implemented + +[English](2026-07-30-hover-popup-pointer-grace.md) | 中文 + +## 问题 + +工作区浏览器行弹出的两种弹层都处于指针无法抵达的位置。`HoverCard` 在指针离开锚点的第一个 `pointerleave` 上就关闭，其卡片还设置了 `pointer-events: none`；但卡片位于锚点右边缘外 8px 处，因此通往卡片的每条路径都要穿过既不属于锚点也不属于卡片的区域，卡片在指针抵达之前就已被销毁——它本应展示的完整工作区路径和会话标题只能匆匆一瞥。行操作菜单传入了 `closeOnPointerLeave`，而其处理器挂在传送后的列表上：把指针移回打开该列表的 `...` 触发按钮会关闭列表，越过列表边缘的任何一次抖动同样如此，且没有任何折返窗口。 + +## 决策 + +`usePointerGrace`（[packages/client/ui-primitives/src/pointer-grace.ts](../../../../packages/client/ui-primitives/src/pointer-grace.ts)）持有唯一一个可取消的延迟关闭，由两个原子组件共享，`POINTER_GRACE_MS` 为 200。离开会启动关闭，折返则取消它。因此指针可以安全穿越锚点与弹层之间的间隙，而真正移开的指针仍会关闭弹层。 + +`HoverCard` 在离开时启动宽限期而不再立即关闭，其卡片也不再设置 `pointer-events: none`，因此指针停在卡片上即可让它保持打开。在已打开状态下重新进入只取消待执行的关闭，而不重启停留计时，从而避免指针穿越间隙时卡片闪烁。在锚点内按下指针以及所有者将 `disabled` 置真，仍会抢在宽限期之前立即关闭卡片。 + +`Menu` 把指针离开关闭的处理从传送后的列表移到包裹 span 上。React 的 enter/leave 遍历基于 React 树进行，因此触发按钮与传送后的列表在这里属于同一区域：穿越两者之间 4px 的间隙、或把指针移回触发按钮，都不再算作离开。只有在列表打开时才会启动离开关闭；由所有者驱动的关闭（选择、Escape、外部点击）会在一个仅以 `open` 为依赖的 effect 中解除待执行的宽限关闭——若把它折叠进外部点击的 effect，则每次重新渲染都会取消宽限期，因为所有者每次都传入新的 `onClose` 闭包。 + +## 考虑过的替代方案 + +**仅通过外部点击和 Escape 关闭这两种弹层。** 之所以否决：两者都由悬停唤起，且没有可见的关闭标识；在指针已移到其他行之后仍让它们停留，会把卡片遗留在无关内容之上。 + +**扩大锚点的命中区域，使其与弹层相接。** 之所以否决：8px 与 4px 的偏移来自设计稿，而一个不可见的桥接元素还必须跟随这两个固定定位弹层已经在滚动和缩放时执行的每一次重新定位。 + +**保留悬浮卡片的 `pointer-events: none`，只加入宽限期。** 之所以否决：那样指针停在卡片上时命中的是卡片背后的元素，宽限期仍会到期，并关闭用户刚刚够到的卡片。 + +**让两个原子组件各自持有计时器。** 之所以否决：这两处关闭是同一种行为、同一套调参；共享 hook 可以防止它们各自漂移。 + +## 后果 + +悬浮卡片现在可被命中，显示期间会遮挡其覆盖区域的 244px——这是可抵达性的代价；它依然只在指针位于行或卡片上时存在。行菜单现在能承受触发按钮与列表之间的往返，而因自身原因关闭的菜单也不会被残留的待执行关闭重新关掉。未设置 `closeOnPointerLeave` 的菜单不受影响——只有设置该属性时才会挂上包裹层处理器。 + +## 测试 + +`packages/client/ui-primitives/tests/hover-card.spec.tsx` 与 `tests/atoms.spec.tsx` 固定验证宽限期边界、折返取消、不重启停留计时、所有者关闭时解除待执行关闭，以及列表关闭时不启动关闭。可抵达性手势本身——把指针移到卡片上，以及在打开的列表与其触发按钮之间移动——由 `apps/web/tests/workspace-management.e2e.ts` 在真实浏览器中固定验证，因为它们依赖 jsdom 无法建模的命中测试与布局。 diff --git a/apps/web/tests/workspace-management.e2e.ts b/apps/web/tests/workspace-management.e2e.ts index e6a7f31f18..da09aaa77a 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 — the create-by-name dialog, the // rename round trip over the real wire (workspace.rename RPC + durable // registry), duplicate-name pre-check, the flat "In one list" view with its -// persisted group-by preference, and the session hover card. Zero model +// persisted group-by preference, and the pointer-reachability of the session +// hover card and the row action menu. Zero model // calls: workspace.create/rename are host RPCs with no model involvement, // and the one session row the flat/hover scenarios need comes from a seeded // fixture (the seeded-history seed reused verbatim — no new recording). @@ -26,7 +27,7 @@ const MODE = webSnapshotMode() const BROWSER_EXPECTED = join(SNAPSHOT_DIR, 'directory-browser.expected.md') const SEED_ID = 'workspace-management-web-e2e' -describe('web e2e: workspace management (create / rename / flat view / hover card)', () => { +describe('web e2e: workspace management (create / rename / flat view / hover affordances)', () => { let scaffold: WebScaffold let browser: Browser let page: Page @@ -384,14 +385,17 @@ describe('web e2e: workspace management (create / rename / flat view / hover car expect(tripwire.pageErrors).toEqual([]) }, 60_000) - it('shows the session hover card after a dwell on the row', async () => { - onTestFailed(() => saveFailureShot(page, 'web-e2e-ws-hover')) - // Expand Ungrouped to reveal the seeded session row, then dwell on it - // (the card opens after a 500ms hover delay, portaled to body). + /** + * Expand Ungrouped and return its seeded session row. The only visible child + * is the non-blank persisted Session; the blank Session created while + * adopting the Workspace stays hidden. + * @returns the session row locator, already present. + */ + async function seededSessionRow() { const ungroupedRow = page.getByText('Ungrouped', { exact: true }).locator('..').locator('..') const ungroupedSection = ungroupedRow.locator('..') - // Initial-current auto-expansion can race this following test's gesture; - // converge on expanded rather than assuming which update wins first. + // Initial-current auto-expansion can race this gesture; converge on + // expanded rather than assuming which update wins first. await expect.poll(async () => { if (await ungroupedRow.getAttribute('aria-expanded') !== 'true') { await page.getByText('Ungrouped', { exact: true }).click() @@ -399,20 +403,62 @@ describe('web e2e: workspace management (create / rename / flat view / hover car } return await ungroupedRow.getAttribute('aria-expanded') }, { timeout: 5_000 }).toBe('true') - // The only visible child is the non-blank persisted Session; the blank - // Session created while adopting the Workspace remains hidden. - const sessionRow = ungroupedSection.locator('[role="treeitem"]').nth(1) - await sessionRow.waitFor({ timeout: 10_000 }) + const row = ungroupedSection.locator('[role="treeitem"]').nth(1) + await row.waitFor({ timeout: 10_000 }) + return row + } + + it('shows the session hover card after a dwell on the row', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-ws-hover')) + // Dwell on the seeded row; the card opens after a 500ms hover delay, + // portaled to body. + const sessionRow = await seededSessionRow() await sessionRow.hover() - // Card content: the full title plus the Idle status line (display-only - // card; no aria role — text anchors are the stable selector). + // Card content: the full title plus the Idle status line (no aria role — + // text anchors are the stable selector). await expect.poll(() => page.getByText('Idle', { exact: true }).count(), { timeout: 5_000 }).toBeGreaterThanOrEqual(1) - // Leaving the anchor closes it with no delay. + // The card is REACHABLE: it sits 8px off the row, so getting to it means + // crossing ground that belongs to neither. Hovering it must not dismiss + // it — the regression this scenario guards. + const card = page.getByText('Idle', { exact: true }).locator('../../..') + await card.hover() + await page.waitForTimeout(600) + expect(await page.getByText('Idle', { exact: true }).count()).toBeGreaterThanOrEqual(1) + // Leaving anchor and card together closes it after the grace. await page.getByRole('button', { name: 'Settings' }).hover() await expect.poll(() => page.getByText('Idle', { exact: true }).count(), { timeout: 5_000 }).toBe(0) expect(tripwire.pageErrors).toEqual([]) }, 60_000) + it('keeps an open row menu up while the pointer moves between trigger and list', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-ws-row-menu')) + const sessionRow = await seededSessionRow() + // The trigger is display:none until its row hovers. + await sessionRow.hover() + const trigger = sessionRow.locator('button[aria-label^="Session actions for "]') + await trigger.click() + const item = page.getByRole('menuitem', { name: 'Rename' }) + await item.waitFor({ timeout: 5_000 }) + // Into the list, then back up to the trigger across the 4px gap below it: + // that return trip used to fire the list's pointerleave and close the + // menu, so a hesitating pointer lost it. Order matters — clicking leaves + // the pointer ON the trigger, so entering the list has to come first for + // the return to be a real departure. + await item.hover() + await page.waitForTimeout(300) + await trigger.hover() + await page.waitForTimeout(600) + expect(await page.getByRole('menuitem', { name: 'Rename' }).count()).toBe(1) + // ...and back down into the list, which must still be there to enter. + await item.hover() + await page.waitForTimeout(600) + expect(await page.getByRole('menuitem', { name: 'Rename' }).count()).toBe(1) + // Pointer-leave dismissal still applies once the pointer genuinely leaves. + await page.getByRole('button', { name: 'Settings' }).hover() + await expect.poll(() => page.getByRole('menuitem', { name: 'Rename' }).count(), { timeout: 5_000 }).toBe(0) + expect(tripwire.pageErrors).toEqual([]) + }, 60_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/packages/client/ui-primitives/src/HoverCard.module.css b/packages/client/ui-primitives/src/HoverCard.module.css index 8d8a52100e..ff1ac5509d 100644 --- a/packages/client/ui-primitives/src/HoverCard.module.css +++ b/packages/client/ui-primitives/src/HoverCard.module.css @@ -7,7 +7,9 @@ /* Preview card (figma session hover card): 244 wide, r12, pad 12/16, the * menu card's elevation. Surface is #2C2C2E in both themes (figma value, - * light/dark identical), so a component-level variable, not a theme token. */ + * light/dark identical), so a component-level variable, not a theme token. + * Hit-testable on purpose: resting the pointer on the card holds it open + * (HoverCard's grace close), which a `pointer-events: none` card cannot do. */ .card { --dsw-hovercard-bg: #2C2C2E; position: fixed; @@ -18,5 +20,4 @@ border-radius: 12px; background: var(--dsw-hovercard-bg); box-shadow: var(--dsw-shadow-lv3); - pointer-events: none; } diff --git a/packages/client/ui-primitives/src/HoverCard.tsx b/packages/client/ui-primitives/src/HoverCard.tsx index 1720a0b79c..3a1ce462b3 100644 --- a/packages/client/ui-primitives/src/HoverCard.tsx +++ b/packages/client/ui-primitives/src/HoverCard.tsx @@ -1,18 +1,24 @@ // HoverCard: delayed hover-preview card portaled to document.body. // Same portal mechanics as Menu: the wrapper span supplies the anchor rect, // the card is fixed-positioned at its right edge and repositions on -// scroll/resize while open. Display-only — the card ignores pointer events -// and closes the instant the pointer leaves the anchor (no close delay). +// scroll/resize while open. The card is reachable: it takes pointer events, +// and leaving the anchor only arms a grace-delayed close, so the pointer can +// cross the 8px gap and settle on the card to read a clipped path or title. +// The portaled card is a React child of the wrapper, so React's enter/leave +// traversal already treats it as inside — one pair of wrapper handlers covers +// anchor and card alike. import { useEffect, useLayoutEffect, useRef, useState } from 'react' import type { ReactNode } from 'react' import { createPortal } from 'react-dom' +import { usePointerGrace } from './pointer-grace.ts' import css from './HoverCard.module.css' /** * Render an anchor with a hover-triggered preview card. * @param props.anchor - the hover target (rendered in place inside a wrapper span). - * @param props.content - card content (display-only, no pointer interaction). + * @param props.content - card content; the pointer may rest on it, so it is + * readable and selectable, but it carries no dismissal affordance of its own. * @param props.openDelayMs - hover dwell before the card shows (default 500). * @param props.disabled - suppress opening; turning true closes an open card. * @returns anchor wrapper with the conditional portaled card. @@ -29,6 +35,8 @@ export function HoverCard({ anchor, content, openDelayMs = 500, disabled = false const [open, setOpen] = useState(false) const [pos, setPos] = useState<{ left: number; top: number } | null>(null) + const { arm: armClose, cancel: cancelClose } = usePointerGrace(() => { setOpen(false) }) + const clearTimer = () => { if (timerRef.current !== null) { clearTimeout(timerRef.current) @@ -40,8 +48,9 @@ export function HoverCard({ anchor, content, openDelayMs = 500, disabled = false useEffect(() => { if (!disabled) return clearTimer() + cancelClose() setOpen(false) - }, [disabled]) + }, [disabled, cancelClose]) useEffect(() => clearTimer, []) @@ -91,17 +100,22 @@ export function HoverCard({ anchor, content, openDelayMs = 500, disabled = false className={css.root} onPointerEnter={() => { if (disabled) return + // Coming back inside during the grace (the gap, or the card itself) + // keeps the current card rather than restarting the dwell. + cancelClose() + if (open) return clearTimer() timerRef.current = setTimeout(() => { setOpen(true) }, openDelayMs) }} onPointerLeave={() => { clearTimer() - setOpen(false) + armClose() }} // Any press inside the anchor (row click, menu trigger) dismisses the // card immediately, without waiting for the owner to flip `disabled`. onPointerDownCapture={() => { clearTimer() + cancelClose() setOpen(false) }} > diff --git a/packages/client/ui-primitives/src/Menu.tsx b/packages/client/ui-primitives/src/Menu.tsx index 747750363d..ea7e51b478 100644 --- a/packages/client/ui-primitives/src/Menu.tsx +++ b/packages/client/ui-primitives/src/Menu.tsx @@ -13,6 +13,7 @@ import type { CSSProperties, ReactNode } from 'react' import { createPortal } from 'react-dom' import clsx from 'clsx' import { IconCheckOutline16 } from './icons/index.tsx' +import { usePointerGrace } from './pointer-grace.ts' import css from './Menu.module.css' /** Selectable row (optionally with a nested submenu). */ @@ -69,8 +70,10 @@ const MEASURE_STYLE: CSSProperties = { visibility: 'hidden', left: 0, top: 0 } * from the anchor rect (repositions on scroll/resize while open). Use when an * ancestor's overflow clipping would crop the in-place list; default false * keeps the pure-CSS in-place behavior. - * @param props.closeOnPointerLeave - close the list when the pointer leaves - * it (default false keeps it open until outside click/Escape/selection). + * @param props.closeOnPointerLeave - close the list once the pointer has left + * both trigger and list for the pointer grace (default false keeps it open + * until outside click/Escape/selection). The grace makes the 4px trigger->list + * gap and a brief overshoot survivable; coming back cancels the close. * @param props.compact - use reduced menu typography and spacing. * @param props.getAnchorRect - portal mode only: supply the anchor rect * directly (e.g. from a host-owned trigger button) instead of measuring the @@ -102,6 +105,7 @@ export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align const listRef = useRef(null) const [openSubmenuId, setOpenSubmenuId] = useState(null) const [fixedPos, setFixedPos] = useState(null) + const { arm: armClose, cancel: cancelClose } = usePointerGrace(onClose) // Portal mode: fixed-position the list from the anchor rect before paint; // track the anchor while open (capture-phase scroll catches nested panes). @@ -179,6 +183,14 @@ export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align } }, [open, onClose]) + // A close from selection/Escape/outside click outruns a pending grace close; + // left armed it would shut a list reopened inside the grace window. Its own + // effect, not the listener effect above: that one re-runs on every `onClose` + // identity change and would cancel the grace mid-transit. + useEffect(() => { + if (!open) cancelClose() + }, [open, cancelClose]) + // The submenu card is absolutely positioned outside the list box; the // scroll clip would crop it, so only submenu-free menus get the height cap. const scrollable = !items.some(entry => !isSeparator(entry) && !isLabel(entry) && entry.submenu !== undefined && entry.submenu.length > 0) @@ -251,7 +263,6 @@ export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align className={clsx(css.list, compact && css.compactList, scrollable && css.scrollable, portal && css.portal, side === 'top' && !portal && css.sideTop, align === 'end' && !portal && css.alignEnd)} style={portal ? fixedPos ?? MEASURE_STYLE : undefined} role="menu" - onPointerLeave={closeOnPointerLeave ? () => { onClose() } : undefined} // React portals bubble synthetic events through the REACT tree: without // this stop, an item click re-fires the anchor row's own onClick // (open/toggle) after onSelect. @@ -268,8 +279,17 @@ export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align
) + // Pointer-leave dismissal watches the WRAPPER, not the list: React's + // enter/leave traversal runs over the React tree, so trigger and portaled + // list are one region here. Aiming back at the trigger, or crossing the 4px + // gap between them, therefore never counts as leaving. return ( - + { if (open) armClose() } : undefined} + > {anchor} {portal ? (list !== false && createPortal(list, document.body)) : list} diff --git a/packages/client/ui-primitives/src/pointer-grace.ts b/packages/client/ui-primitives/src/pointer-grace.ts new file mode 100644 index 0000000000..1619cfe66e --- /dev/null +++ b/packages/client/ui-primitives/src/pointer-grace.ts @@ -0,0 +1,53 @@ +// Shared close timing for pointer-dismissed popups (HoverCard, hover-closing +// Menu). Both float free of their anchor, so the pointer has to cross ground +// that belongs to neither on its way in; closing on the first pointerleave +// makes the popup unreachable. The grace turns that transit into a cancelable +// pending close. + +import { useCallback, useEffect, useRef } from 'react' + +/** + * Grace before a pointer-dismissed popup closes. Covers the anchor->popup gap + * (8px for HoverCard, 4px for Menu) at a hand's travel speed without leaving a + * popup lingering once the pointer has genuinely moved on. + */ +export const POINTER_GRACE_MS = 200 + +/** Cancelable delayed close for a pointer-dismissed popup. */ +export interface PointerGrace { + /** Schedule the close {@link POINTER_GRACE_MS} from now, replacing any pending one. */ + arm: () => void + /** Abort a pending close (the pointer came back). */ + cancel: () => void +} + +/** + * Delay a pointer-dismissed popup's close so the pointer can cross the gap + * between anchor and popup. A pending close is dropped on unmount. + * @param close - runs when the grace elapses with no re-entry; read at fire + * time, so callers may pass a fresh closure each render. + * @returns the {@link PointerGrace} handle. + */ +export function usePointerGrace(close: () => void): PointerGrace { + const timerRef = useRef | null>(null) + const closeRef = useRef(close) + closeRef.current = close + + const cancel = useCallback(() => { + if (timerRef.current === null) return + clearTimeout(timerRef.current) + timerRef.current = null + }, []) + + const arm = useCallback(() => { + cancel() + timerRef.current = setTimeout(() => { + timerRef.current = null + closeRef.current() + }, POINTER_GRACE_MS) + }, [cancel]) + + useEffect(() => cancel, [cancel]) + + return { arm, cancel } +} diff --git a/packages/client/ui-primitives/tests/atoms.spec.tsx b/packages/client/ui-primitives/tests/atoms.spec.tsx index 51b14faa17..8a9791a411 100644 --- a/packages/client/ui-primitives/tests/atoms.spec.tsx +++ b/packages/client/ui-primitives/tests/atoms.spec.tsx @@ -1,7 +1,8 @@ // @vitest-environment jsdom -import { cleanup, fireEvent, render, screen } from '@testing-library/react' +import { act, cleanup, fireEvent, render, screen } from '@testing-library/react' import { afterEach, describe, expect, it, vi } from 'vitest' import { Button, ConnectionBanner, Input, Menu, Modal, Pill } from '@deepseek-ai/dsh-client-ui-primitives' +import { POINTER_GRACE_MS } from '../src/pointer-grace.ts' afterEach(cleanup) @@ -160,16 +161,77 @@ describe('Menu', () => { expect(onSelect).toHaveBeenCalledWith('del') }) - it('closeOnPointerLeave closes when the pointer leaves the list; default stays open', () => { - const onClose = vi.fn() - const { rerender } = render( - trigger} items={items} onSelect={() => {}} onClose={onClose} />) - fireEvent.pointerLeave(screen.getByRole('menu')) - expect(onClose).toHaveBeenCalledTimes(1) - rerender( - trigger} items={items} onSelect={() => {}} onClose={onClose} />) - fireEvent.pointerLeave(screen.getByRole('menu')) - expect(onClose).toHaveBeenCalledTimes(1) + it('closeOnPointerLeave closes a grace after the pointer leaves trigger and list; default never does', () => { + vi.useFakeTimers() + try { + const onClose = vi.fn() + const { rerender } = render( + trigger} items={items} onSelect={() => {}} onClose={onClose} />) + const wrapper = screen.getByText('trigger').parentElement as HTMLElement + fireEvent.pointerLeave(wrapper) + // Still open through the grace: the pointer may be crossing the gap. + act(() => { vi.advanceTimersByTime(POINTER_GRACE_MS - 1) }) + expect(onClose).not.toHaveBeenCalled() + act(() => { vi.advanceTimersByTime(1) }) + expect(onClose).toHaveBeenCalledTimes(1) + rerender( + trigger} items={items} onSelect={() => {}} onClose={onClose} />) + fireEvent.pointerLeave(wrapper) + act(() => { vi.advanceTimersByTime(POINTER_GRACE_MS * 10) }) + expect(onClose).toHaveBeenCalledTimes(1) + } finally { + vi.useRealTimers() + } + }) + + it('coming back inside the grace keeps the list open (trigger and list are one region)', () => { + vi.useFakeTimers() + try { + const onClose = vi.fn() + render( + trigger} items={items} onSelect={() => {}} onClose={onClose} />) + const wrapper = screen.getByText('trigger').parentElement as HTMLElement + fireEvent.pointerLeave(wrapper) + act(() => { vi.advanceTimersByTime(POINTER_GRACE_MS - 50) }) + fireEvent.pointerEnter(wrapper) + act(() => { vi.advanceTimersByTime(POINTER_GRACE_MS * 10) }) + expect(onClose).not.toHaveBeenCalled() + } finally { + vi.useRealTimers() + } + }) + + it('a close from selection disarms the pending grace close', () => { + vi.useFakeTimers() + try { + const onClose = vi.fn() + const { rerender } = render( + trigger} items={items} onSelect={() => {}} onClose={onClose} />) + const wrapper = screen.getByText('trigger').parentElement as HTMLElement + fireEvent.pointerLeave(wrapper) + // The owner closes for its own reason (selection/Escape) mid-grace; the + // armed timer must not survive to shut a list reopened right after. + rerender( + trigger} items={items} onSelect={() => {}} onClose={onClose} />) + act(() => { vi.advanceTimersByTime(POINTER_GRACE_MS * 10) }) + expect(onClose).not.toHaveBeenCalled() + } finally { + vi.useRealTimers() + } + }) + + it('leaving a closed list arms nothing', () => { + vi.useFakeTimers() + try { + const onClose = vi.fn() + render( + trigger} items={items} onSelect={() => {}} onClose={onClose} />) + fireEvent.pointerLeave(screen.getByText('trigger').parentElement as HTMLElement) + act(() => { vi.advanceTimersByTime(POINTER_GRACE_MS * 10) }) + expect(onClose).not.toHaveBeenCalled() + } finally { + vi.useRealTimers() + } }) it('a list click does not bubble to the anchor row (portal synthetic-event path)', () => { diff --git a/packages/client/ui-primitives/tests/hover-card.spec.tsx b/packages/client/ui-primitives/tests/hover-card.spec.tsx index ce599c0258..3826fdf79a 100644 --- a/packages/client/ui-primitives/tests/hover-card.spec.tsx +++ b/packages/client/ui-primitives/tests/hover-card.spec.tsx @@ -2,6 +2,7 @@ import { act, cleanup, fireEvent, render, screen } from '@testing-library/react' import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' import { HoverCard } from '@deepseek-ai/dsh-client-ui-primitives' +import { POINTER_GRACE_MS } from '../src/pointer-grace.ts' afterEach(cleanup) beforeEach(() => { vi.useFakeTimers() }) @@ -54,18 +55,47 @@ describe('HoverCard', () => { expect(screen.queryByText('card body')).toBeNull() }) - it('pointerleave closes an open card immediately; re-enter restarts the dwell', () => { + it('pointerleave closes an open card a grace later; re-enter after that restarts the dwell', () => { const { wrapper } = mount() fireEvent.pointerEnter(wrapper) act(() => { vi.advanceTimersByTime(500) }) expect(screen.getByText('card body')).toBeTruthy() fireEvent.pointerLeave(wrapper) + act(() => { vi.advanceTimersByTime(POINTER_GRACE_MS - 1) }) + expect(screen.getByText('card body')).toBeTruthy() + act(() => { vi.advanceTimersByTime(1) }) expect(screen.queryByText('card body')).toBeNull() fireEvent.pointerEnter(wrapper) act(() => { vi.advanceTimersByTime(500) }) expect(screen.getByText('card body')).toBeTruthy() }) + it('reaching the card inside the grace keeps it open without restarting the dwell', () => { + // The portaled card is a React child of the wrapper, so the pointer + // arriving on it re-enters the wrapper — the gesture the 8px anchor gap + // used to make impossible. + const { wrapper } = mount() + fireEvent.pointerEnter(wrapper) + act(() => { vi.advanceTimersByTime(500) }) + fireEvent.pointerLeave(wrapper) + act(() => { vi.advanceTimersByTime(POINTER_GRACE_MS - 50) }) + fireEvent.pointerEnter(wrapper) + act(() => { vi.advanceTimersByTime(POINTER_GRACE_MS * 10) }) + expect(screen.getByText('card body')).toBeTruthy() + }) + + it('re-entering while open does not queue a second dwell', () => { + const { wrapper } = mount() + fireEvent.pointerEnter(wrapper) + act(() => { vi.advanceTimersByTime(500) }) + fireEvent.pointerEnter(wrapper) + fireEvent.pointerLeave(wrapper) + act(() => { vi.advanceTimersByTime(POINTER_GRACE_MS) }) + // A dwell restarted by the redundant enter would reopen the card here. + act(() => { vi.advanceTimersByTime(500) }) + expect(screen.queryByText('card body')).toBeNull() + }) + it('a press inside the anchor dismisses the card without waiting for disabled', () => { const { wrapper } = mount() fireEvent.pointerEnter(wrapper) @@ -135,6 +165,7 @@ describe('HoverCard', () => { expect(card.style.left).toBe('308px') expect(card.style.top).toBe('90px') fireEvent.pointerLeave(wrapper) + act(() => { vi.advanceTimersByTime(POINTER_GRACE_MS) }) expect(screen.queryByText('card body')).toBeNull() }) From 19606bc331cf51caed1bd222fe83530731db3ba2 Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Thu, 30 Jul 2026 07:27:13 -0700 Subject: [PATCH 08/50] docs: generate THIRD_PARTY_NOTICES.md and gate it in doc-sync Replace the hand-written inventory with scripts/gen-third-party-notices.ts, verified fresh by a doc-sync leaf gate. Tier by declaring workspace area rather than manifest section, so test-support runtime declarations stay dev-only and every mountable plugin's dependencies are disclosed as runtime; list the pnpm-patched packages; point the Python closure at uv.lock. Re-record the translation-prompt snapshot the README link invalidated. --- ...30-generated-third-party-notices.i18n.yaml | 6 + ...026-07-30-generated-third-party-notices.md | 47 +++ ...-07-30-generated-third-party-notices.zh.md | 47 +++ THIRD_PARTY_NOTICES.md | 54 ++- package.json | 2 + scripts/gen-third-party-notices.spec.ts | 69 ++++ scripts/gen-third-party-notices.ts | 384 ++++++++++++++++++ scripts/run-gates.ts | 1 + .../request-response.expected.json | 4 +- 9 files changed, 594 insertions(+), 20 deletions(-) create mode 100644 .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml create mode 100644 .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md create mode 100644 .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md create mode 100644 scripts/gen-third-party-notices.spec.ts create mode 100644 scripts/gen-third-party-notices.ts diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml new file mode 100644 index 0000000000..32d76bbc9c --- /dev/null +++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.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/process/2026-07-30-generated-third-party-notices.md +2026-07-30-generated-third-party-notices.md: 5b85abf5716d79213f6937b938d3f0267f7627f3 +2026-07-30-generated-third-party-notices.zh.md: 26b3e6e88ec038d9107c9b78c85a8c45a1916805 diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md new file mode 100644 index 0000000000..5b85abf571 --- /dev/null +++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md @@ -0,0 +1,47 @@ +# Agent Note: Generated third-party notices + +Status: implemented + +English | [中文](2026-07-30-generated-third-party-notices.zh.md) + +## Problem + +Open-sourcing this repository requires disclosing the third-party software it depends on, with each project's license. The disclosure has to be complete, has to stay true as dependencies change, and has to say something a reader can act on — which of these packages end up on a user's machine, and which only build and test the repository. + +A hand-written inventory answers none of those durably. Roughly a hundred rows of names and license strings derived from manifests drift silently the moment a package is added, removed, or relicensed, and nothing in `doc-sync` would notice. + +## Decision + +[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) is generated by [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) from the workspace manifests, `vendor/README.md`, the `pyproject.toml` files, and `pnpm-workspace.yaml`. `pnpm run verify-third-party-notices` runs the generator with `--check` as a `doc-sync` leaf gate, so a dependency change that skips regeneration fails the same way a stale catalog does. The root README pair links the file from its License section. + +The file discloses **direct** dependencies only. The complete npm closure with pinned versions already lives in `pnpm-lock.yaml` (`pnpm licenses list` renders it) and the Python closure in `python/sdk/uv.lock`; re-materializing either as prose would be a second, worse copy. + +**Tiering is by declaring area, not by manifest section.** A package is a runtime dependency when any manifest outside `DEV_ONLY_AREAS` — the root manifest, `packages/support/`, `packages/client/test-runtime/`, `website/`, `examples/`, `native/` — names it under `dependencies` or `optionalDependencies`. Section names alone are wrong in both directions: a test-support package declares `vitest` under `dependencies` without shipping it, and the `bin/dsh` launcher execs through `tsx`, which no manifest declares as a runtime dependency at all (the generator marks it runtime explicitly). + +The runtime tier deliberately covers **every mountable plugin**, not just what the CLI, Web UI, and Python runtime load by default. `scripts/install.sh` installs the repository itself, so a user's `cordis.yml` can mount any plugin package; `@modelcontextprotocol/sdk` and the OpenTelemetry packages reach real users even though no default assembly imports them. Under-disclosure is the costly direction for a legal notice. + +License and repository metadata come from the installed pnpm store, so the generator requires an installed tree and fails loud when a package resolves to neither, rather than emitting an empty cell. `OVERRIDES` carries the packages whose published manifest cannot answer — Rust-built npm bins that omit `license`, and the `modelcontextprotocol/servers` packages whose repository is mid MIT→Apache-2.0 relicensing, so their effective terms are per-contribution. Vendored packages are cross-checked against `vendor/README.md` and rejected if any is not MIT, and `pnpm-workspace.yaml`'s `patchedDependencies` are listed under the runtime table because pnpm applies those patches at install time — shipped artifacts carry modified copies of `@earendil-works/pi-tui` and `node-pty`, and the patch files are the record of what changed. + +## Testing + +[`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) pins the tiering rule against fixture manifests — including the two cases that motivate it, a `dependencies` entry of a test-support package and a plugin package no app mounts — and pins that the vendored-table parser reads the committed manifest and yields nothing when the table shape changes, which is what makes the generator fail loud rather than emit an empty section. + +## Alternatives considered + +**Keep the hand-written file and review it at release time.** Reviewing a hundred derived rows by eye is exactly the work a generator does correctly, and the file's own claim — that it lists every direct dependency — would be unverified between releases. + +**Enumerate the full transitive closure.** The closure is thousands of packages, already recorded in the lock files with exact versions, and would bury the direct dependencies that a reader actually evaluates. The file points at the lock files and the `pnpm licenses list` renderer instead. + +**Tier by manifest section (`dependencies` vs `devDependencies`).** Mechanically simple and wrong on real data in both directions, as the tiering paragraph above records. + +**Tier by reachability from the shipped assemblies only** (`apps/*` plus `python/sdk-runtime`). This produces a tighter runtime tier, but classifies the MCP client and the OpenTelemetry exporter as development-only even though a user running the installed repository can mount them. It understates the disclosure, which is the wrong direction to err for a legal notice. + +**Emit the notices as a bilingual pair.** Every other root document is paired, but the file is a table of upstream package names, SPDX identifiers, and URLs; the translatable surface is a handful of section blurbs. `scripts/translation-pairing.ts` scopes discovery to `README*`, `.agents/notes/**`, `docs/**`, and `python/**`, so a root non-README file is outside the bilingual corpus by construction, and the README pair carries the bilingual entry points into it. + +## Consequences + +Adding or removing a dependency now requires running `pnpm run gen-third-party-notices` and committing the result; `doc-sync` fails otherwise. That is the intended cost — the disclosure cannot silently go stale. + +The generator needs an installed tree, which makes it heavier than a pure-source generator, and a new package with unusable published metadata needs an `OVERRIDES` entry rather than silently rendering a blank license. Both failures are loud and name the remedy. + +The tiering rule is a policy encoded in one constant. Adding a workspace area that never ships — a second test-infrastructure tier, another site — requires extending `DEV_ONLY_AREAS`, or its dependencies will be disclosed as runtime. diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md new file mode 100644 index 0000000000..26b3e6e88e --- /dev/null +++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md @@ -0,0 +1,47 @@ +# Agent Note: Generated third-party notices + +Status: implemented + +[English](2026-07-30-generated-third-party-notices.md) | 中文 + +## Problem + +本仓库开源需要披露所依赖的第三方软件及各自的许可证。这份披露必须完整，必须随依赖变化保持为真，还必须给出读者用得上的信息：哪些包最终会进到用户机器上，哪些只用于构建和测试。 + +手写清单无法长期满足其中任何一条。约一百行从各清单文件推导出来的包名与许可证标识，只要有依赖新增、移除或换用许可证就会悄悄失真，而 `doc-sync` 不会察觉。 + +## Decision + +[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) 由 [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) 依据各工作区清单、`vendor/README.md`、`pyproject.toml` 与 `pnpm-workspace.yaml` 生成。`pnpm run verify-third-party-notices` 以 `--check` 运行生成器，作为 `doc-sync` 的叶子门禁；依赖变了却没重新生成，会像目录过期一样直接失败。根 README 双语两侧都从「许可证」一节链到该文件。 + +文件只披露**直接**依赖。完整的 npm 闭包连同锁定版本已记录在 `pnpm-lock.yaml`（`pnpm licenses list` 可渲染），Python 闭包记录在 `python/sdk/uv.lock`；再用散文誊一遍只会得到一份更差的副本。 + +**分层依据是声明方所在区域，而非清单字段名。** 只要 `DEV_ONLY_AREAS` 之外的任一清单——即根清单、`packages/support/`、`packages/client/test-runtime/`、`website/`、`examples/`、`native/` 之外——在 `dependencies` 或 `optionalDependencies` 里点名某个包，它就是运行时依赖。单看字段名在两个方向上都会出错：测试支撑包把 `vitest` 写在 `dependencies` 里却并不交付它；而 `bin/dsh` 启动器 exec 经过的 `tsx`，根本没有任何清单把它声明为运行时依赖，只能由生成器显式标记。 + +运行时层刻意覆盖**所有可挂载的插件**，而不止 CLI、Web UI 与 Python 运行时默认加载的那些。`scripts/install.sh` 安装的就是仓库本身，用户的 `cordis.yml` 可以挂载任何插件包；`@modelcontextprotocol/sdk` 与 OpenTelemetry 系列即使没有任何默认装配引入，也会触达真实用户。对法务披露而言，披露不足才是代价更高的那个方向。 + +许可证与仓库地址取自已安装的 pnpm store，因此生成器要求工作树已安装依赖；某个包两处都解析不到时直接失败，而不是留下空单元格。`OVERRIDES` 收录已发布清单答不上来的包：用 Rust 构建、发布时省略 `license` 字段的 npm 可执行包，以及 `modelcontextprotocol/servers` 系列——该仓库正处在 MIT 向 Apache-2.0 的重新许可过程中，实际条款按贡献逐条而定。被源码收编的包会与 `vendor/README.md` 交叉核对，出现非 MIT 即报错；`pnpm-workspace.yaml` 的 `patchedDependencies` 列在运行时表格之后，因为 pnpm 在安装期就会打上这些补丁——交付产物携带的是改动过的 `@earendil-works/pi-tui` 与 `node-pty`，补丁文件本身就是改动的完整记录。 + +## Testing + +[`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 用夹具清单钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它同时钉住被收编包的表格解析器能读出已提交的清单表，且表格形态一变就解析为空——正是这一点让生成器直接失败，而不是产出一个空章节。 + +## Alternatives considered + +**保留手写文件，发版时人工过一遍。** 用肉眼审阅上百行推导数据，恰恰是生成器能做对的活；而且在两次发版之间，文件自称「列出全部直接依赖」这句话无人验证。 + +**列出完整传递闭包。** 闭包有数千个包，锁文件里已带精确版本，铺开只会淹没读者真正要评估的直接依赖。文件转而指向锁文件与 `pnpm licenses list`。 + +**按清单字段分层（`dependencies` 与 `devDependencies`）。** 机械上最省事，但在真实数据上两个方向都会出错，理由见上文分层段落。 + +**只按已交付装配的可达性分层**（`apps/*` 加 `python/sdk-runtime`）。这样得到的运行时层更紧凑，但会把 MCP 客户端与 OpenTelemetry 导出器判为仅开发用途——而运行已安装仓库的用户完全可以挂载它们。这会低估披露，对法务通告来说错在了更危险的一侧。 + +**把披露文件做成双语对。** 其他根文档都是成对的，但这份文件是上游包名、SPDX 标识与网址构成的表格，可翻译的只有寥寥几段章节导语。`scripts/translation-pairing.ts` 的发现范围限定在 `README*`、`.agents/notes/**`、`docs/**` 与 `python/**`，根目录下的非 README 文件在构造上就不属于双语语料；双语入口由 README 对承担。 + +## Consequences + +此后增删依赖都需要运行 `pnpm run gen-third-party-notices` 并提交结果，否则 `doc-sync` 失败。这正是预期成本——披露不可能再悄悄过期。 + +生成器需要已安装的工作树，因此比纯源码生成器更重；发布元数据不可用的新包需要补一条 `OVERRIDES`，而不是默默渲染出空白许可证。这两类失败都会明确报错并指出补救方式。 + +分层规则是编码在一个常量里的政策。若新增了不参与交付的工作区区域——第二层测试基础设施、另一个站点——就要同步扩展 `DEV_ONLY_AREAS`，否则其依赖会被当作运行时依赖披露出去。 diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index bfbe5608b0..651133723d 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -1,8 +1,11 @@ + + # Third-Party Notices DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the third-party open-source software listed below. Each project remains under its own license; nothing in this file changes those terms. -This file lists **direct** dependencies declared by the workspace. The complete transitive closure, with exact pinned versions, is recorded in [`pnpm-lock.yaml`](pnpm-lock.yaml) and can be inspected with `pnpm licenses list`. +This file lists **direct** dependencies declared by the workspace, generated from the workspace manifests by `scripts/gen-third-party-notices.ts` and verified fresh by `pnpm run verify-third-party-notices` (part of `doc-sync`). The complete npm transitive closure, with exact pinned versions, is recorded in [`pnpm-lock.yaml`](pnpm-lock.yaml) (inspect it with `pnpm licenses list`); the Python closure is recorded in [`python/sdk/uv.lock`](python/sdk/uv.lock). ## Vendored source (`vendor/`) @@ -10,19 +13,19 @@ The Cordis framework and its foundation libraries are source-vendored into this | Package | Upstream | License | | --- | --- | --- | -| `cordis` | https://github.com/cordiverse/cordis | MIT | -| `@cordisjs/plugin-loader` | https://github.com/cordiverse/cordis | MIT | -| `@cordisjs/plugin-include` | https://github.com/deepseek-harness/cordis | MIT | -| `@cordisjs/plugin-group` | https://github.com/deepseek-harness/cordis | MIT | -| `@cordisjs/plugin-timer` | https://github.com/deepseek-harness/cordis | MIT | -| `@cordisjs/plugin-hmr` | https://github.com/deepseek-harness/cordis | MIT | -| `@cordisjs/plugin-logger-console` | https://github.com/deepseek-harness/cordis | MIT | -| `cosmokit` | https://github.com/deepseek-harness/cosmokit | MIT | -| `schemastery` | https://github.com/deepseek-harness/schemastery | MIT | +| `cosmokit` | [github.com/deepseek-harness/cosmokit](https://github.com/deepseek-harness/cosmokit) | MIT | +| `schemastery` | [github.com/deepseek-harness/schemastery](https://github.com/deepseek-harness/schemastery) | MIT | +| `cordis` | [github.com/cordiverse/cordis](https://github.com/cordiverse/cordis) | MIT | +| `@cordisjs/plugin-loader` | [github.com/cordiverse/cordis](https://github.com/cordiverse/cordis) | MIT | +| `@cordisjs/plugin-include` | [github.com/deepseek-harness/cordis](https://github.com/deepseek-harness/cordis) | MIT | +| `@cordisjs/plugin-group` | [github.com/deepseek-harness/cordis](https://github.com/deepseek-harness/cordis) | MIT | +| `@cordisjs/plugin-timer` | [github.com/deepseek-harness/cordis](https://github.com/deepseek-harness/cordis) | MIT | +| `@cordisjs/plugin-hmr` | [github.com/deepseek-harness/cordis](https://github.com/deepseek-harness/cordis) | MIT | +| `@cordisjs/plugin-logger-console` | [github.com/deepseek-harness/cordis](https://github.com/deepseek-harness/cordis) | MIT | ## Runtime npm dependencies -Direct dependencies that ship in at least one runtime surface (CLI/TUI, Web UI, SDK runtime, or the website at serve time). +External packages that a workspace package resolves at runtime. `scripts/install.sh` installs this repository itself, so the tier covers every plugin a user can mount from `cordis.yml` — not only what the `dsh` CLI/TUI, the Web UI, and the Python SDK runtime load by default. | Package | License | | --- | --- | @@ -42,15 +45,12 @@ Direct dependencies that ship in at least one runtime surface (CLI/TUI, Web UI, | [`@opentelemetry/sdk-logs`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | | [`@shikijs/langs`](https://github.com/shikijs/shiki) | MIT | | [`@standard-schema/spec`](https://github.com/standard-schema/standard-schema) | MIT | -| [`@testing-library/dom`](https://github.com/testing-library/dom-testing-library) | MIT | -| [`@testing-library/react`](https://github.com/testing-library/react-testing-library) | MIT | | [`anser`](https://github.com/IonicaBizau/anser) | MIT | | [`chokidar`](https://github.com/paulmillr/chokidar) | MIT | | [`clsx`](https://github.com/lukeed/clsx) | MIT | | [`commander`](https://github.com/tj/commander.js) | MIT | | [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause | | [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT | -| [`execa`](https://github.com/sindresorhus/execa) | MIT | | [`handlebars`](https://github.com/handlebars-lang/handlebars.js) | MIT | | [`immer`](https://github.com/immerjs/immer) | MIT | | [`js-yaml`](https://github.com/nodeca/js-yaml) | MIT | @@ -73,14 +73,18 @@ Direct dependencies that ship in at least one runtime surface (CLI/TUI, Web UI, | [`turndown`](https://github.com/mixmark-io/turndown) | MIT | | [`typescript`](https://github.com/microsoft/TypeScript) | Apache-2.0 | | [`use-sync-external-store`](https://github.com/facebook/react) | MIT | -| [`vitest`](https://github.com/vitest-dev/vitest) | MIT | | [`yaml`](https://github.com/eemeli/yaml) | ISC | | [`zod`](https://github.com/colinhacks/zod) | MIT | | [`zustand`](https://github.com/pmndrs/zustand) | MIT | +pnpm applies local patches to the following packages at install time, so shipped artifacts carry modified copies; each patch file is the complete record of the modification: + +- `@earendil-works/pi-tui@0.80.7` — [`patches/@earendil-works__pi-tui@0.80.7.patch`](patches/@earendil-works__pi-tui@0.80.7.patch) +- `node-pty@1.1.0` — [`patches/node-pty@1.1.0.patch`](patches/node-pty@1.1.0.patch) + ## Development-only npm dependencies -Direct dependencies used for building, linting, testing, and generating the documentation site. They are not part of any shipped runtime artifact. +External packages declared only by repository tooling, test infrastructure, the documentation site, the demo leaves, or the native launcher's build workspace. They are not part of any shipped runtime artifact. | Package | License | | --- | --- | @@ -88,7 +92,17 @@ Direct dependencies used for building, linting, testing, and generating the docu | [`@modelcontextprotocol/server-everything`](https://github.com/modelcontextprotocol/servers) | MIT / Apache-2.0 | | [`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers) | MIT / Apache-2.0 | | [`@stylistic/eslint-plugin`](https://github.com/eslint-stylistic/eslint-stylistic) | MIT | -| [`@types/*`](https://github.com/DefinitelyTyped/DefinitelyTyped) (babel__code-frame, js-yaml, jsdom, mdast, node, picomatch, react, react-dom, turndown) | MIT | +| [`@testing-library/dom`](https://github.com/testing-library/dom-testing-library) | MIT | +| [`@testing-library/react`](https://github.com/testing-library/react-testing-library) | MIT | +| [`@types/babel__code-frame`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT | +| [`@types/js-yaml`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT | +| [`@types/jsdom`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT | +| [`@types/mdast`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT | +| [`@types/node`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT | +| [`@types/picomatch`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT | +| [`@types/react`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT | +| [`@types/react-dom`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT | +| [`@types/turndown`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT | | [`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint) | MIT | | [`@vitejs/plugin-react`](https://github.com/vitejs/vite-plugin-react) | MIT | | [`@vitest/coverage-v8`](https://github.com/vitest-dev/vitest) | MIT | @@ -101,6 +115,7 @@ Direct dependencies used for building, linting, testing, and generating the docu | [`esbuild`](https://github.com/evanw/esbuild) | MIT | | [`eslint`](https://github.com/eslint/eslint) | MIT | | [`eslint-plugin-sonarjs`](https://github.com/SonarSource/SonarJS) | LGPL-3.0-only | +| [`execa`](https://github.com/sindresorhus/execa) | MIT | | [`fast-check`](https://github.com/dubzzz/fast-check) | MIT | | [`jscpd`](https://github.com/kucherenko/jscpd) | MIT | | [`jsdom`](https://github.com/jsdom/jsdom) | MIT | @@ -118,15 +133,18 @@ Direct dependencies used for building, linting, testing, and generating the docu | [`vite-tsconfig-paths`](https://github.com/aleclarson/vite-tsconfig-paths) | MIT | | [`vitepress`](https://github.com/vuejs/vitepress) | MIT | | [`vitepress-plugin-mermaid`](https://github.com/emersonbottero/vitepress-plugin-mermaid) | MIT | +| [`vitest`](https://github.com/vitest-dev/vitest) | MIT | `eslint-plugin-sonarjs` (LGPL-3.0-only) and `lightningcss` (MPL-2.0) run only as development tooling; their code is not linked into or distributed with any DeepSeek Harness artifact. ## Python SDK dependencies (`python/`) +Direct dependencies of the `pyproject.toml` manifests, plus `uv` as the development workflow tool. + | Package | License | Role | | --- | --- | --- | -| [`pydantic`](https://github.com/pydantic/pydantic) | MIT | runtime dependency of `deepseek-harness` | | [`hatchling`](https://github.com/pypa/hatch) | MIT | build backend | +| [`pydantic`](https://github.com/pydantic/pydantic) | MIT | runtime dependency of `deepseek-harness` | | [`pytest`](https://github.com/pytest-dev/pytest) | MIT | test-only | | [`uv`](https://github.com/astral-sh/uv) | MIT / Apache-2.0 | development workflow tool | diff --git a/package.json b/package.json index fc315cb146..535d1f4c52 100644 --- a/package.json +++ b/package.json @@ -91,6 +91,8 @@ "verify-doc-graphs": "tsx scripts/gen-doc-graphs.ts --check", "gen-persistence-catalog": "tsx scripts/gen-persistence-catalog.ts", "verify-persistence-catalog": "tsx scripts/gen-persistence-catalog.ts --check", + "gen-third-party-notices": "tsx scripts/gen-third-party-notices.ts", + "verify-third-party-notices": "tsx scripts/gen-third-party-notices.ts --check", "gen-module-graph": "tsx scripts/gen-module-graph.ts", "gen-scoped-events": "tsx scripts/gen-scoped-events.ts", "verify-scoped-events": "tsx scripts/gen-scoped-events.ts --check", diff --git a/scripts/gen-third-party-notices.spec.ts b/scripts/gen-third-party-notices.spec.ts new file mode 100644 index 0000000000..57c28ae151 --- /dev/null +++ b/scripts/gen-third-party-notices.spec.ts @@ -0,0 +1,69 @@ +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' +import { describe, expect, it } from 'vitest' +import { type Manifest, parseVendoredRows, tierExternalDeps } from './gen-third-party-notices.ts' + +const root = resolve(import.meta.dirname, '..') + +/** Build the (manifests, names) pair `tierExternalDeps` consumes. */ +function workspace(entries: Record): { manifests: Map; names: Set } { + const manifests = new Map(Object.entries(entries)) + const names = new Set() + for (const manifest of manifests.values()) { + if (manifest.name !== undefined) names.add(manifest.name) + } + return { manifests, names } +} + +describe('tierExternalDeps', () => { + it('tiers by declaring area, not by the declaring section name', () => { + const { manifests, names } = workspace({ + // Root tooling and test infrastructure never ship, whichever section declares them. + 'package.json': { dependencies: { 'root-runtime-looking': '^1' }, devDependencies: { 'lint-tool': '^1' } }, + 'packages/support/loader-smoke/package.json': { name: '@deepseek-ai/dsh-loader-smoke', dependencies: { 'smoke-helper': '^1' } }, + 'packages/client/test-runtime/package.json': { name: '@deepseek-ai/dsh-client-test-runtime', dependencies: { 'test-lib': '^1' } }, + 'website/package.json': { devDependencies: { 'site-tool': '^1' } }, + // A plugin package's runtime dependency ships even when no app mounts it by default. + 'packages/mcp/mcp-client/package.json': { name: '@deepseek-ai/dsh-mcp-client', dependencies: { 'protocol-sdk': '^1' }, devDependencies: { 'protocol-fixture-server': '^1' } }, + 'apps/cli/package.json': { name: '@deepseek-ai/dsh-cli', dependencies: { 'cli-lib': '^1', '@deepseek-ai/dsh-mcp-client': 'workspace:^' } }, + }) + + expect(tierExternalDeps(manifests, names)).toEqual(new Map([ + ['tsx', true], + ['root-runtime-looking', false], + ['lint-tool', false], + ['smoke-helper', false], + ['test-lib', false], + ['site-tool', false], + ['protocol-sdk', true], + ['protocol-fixture-server', false], + ['cli-lib', true], + ])) + }) + + it('keeps a package runtime when any shipping area declares it, and excludes workspace links', () => { + const { manifests, names } = workspace({ + 'package.json': { devDependencies: { shared: '^1' } }, + 'packages/ui/tui/package.json': { name: '@deepseek-ai/dsh-tui', dependencies: { shared: '^1', '@deepseek-ai/dsh-cli': 'workspace:^' } }, + 'apps/cli/package.json': { name: '@deepseek-ai/dsh-cli' }, + }) + + expect(tierExternalDeps(manifests, names).get('shared')).toBe(true) + expect(tierExternalDeps(manifests, names).has('@deepseek-ai/dsh-cli')).toBe(false) + }) +}) + +describe('parseVendoredRows', () => { + it('reads the committed vendor manifest table', () => { + const rows = parseVendoredRows(readFileSync(resolve(root, 'vendor/README.md'), 'utf8')) + + expect(rows.length).toBeGreaterThan(0) + expect(rows).toContainEqual({ npmName: 'cordis', upstream: 'https://github.com/cordiverse/cordis' }) + // The upstream column carries a trailing package path for some rows; it is not part of the URL. + expect(rows.every(row => /^https:\/\/\S+$/.test(row.upstream))).toBe(true) + }) + + it('yields nothing when the table shape changes, so the generator fails loud', () => { + expect(parseVendoredRows('| `cordis/` | cordis | 4.0.0 | https://example.com | `abc123` |\n')).toEqual([]) + }) +}) diff --git a/scripts/gen-third-party-notices.ts b/scripts/gen-third-party-notices.ts new file mode 100644 index 0000000000..16cbe6153c --- /dev/null +++ b/scripts/gen-third-party-notices.ts @@ -0,0 +1,384 @@ +/** + * Generate `THIRD_PARTY_NOTICES.md` from the workspace manifests: every + * external dependency named by a workspace `package.json`, the vendored-package + * manifest in `vendor/README.md`, the Python `pyproject.toml` files, and the + * pnpm patch list. License and repository metadata come from the installed + * store, so the tree must be installed. `--check` verifies the committed + * artifact. Tier policy and ownership live in + * `.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md`. + */ + +import { existsSync, globSync, readdirSync, readFileSync, writeFileSync } from 'node:fs' +import { resolve } from 'node:path' +import * as yaml from 'js-yaml' + +const root = resolve(import.meta.dirname, '..') +const OUT = 'THIRD_PARTY_NOTICES.md' + +/** Dependency-declaration kinds a consumer resolves at runtime. */ +const RUNTIME_KINDS = ['dependencies', 'optionalDependencies'] as const +/** All manifest sections that name an external package this file must disclose. */ +const ALL_KINDS = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'] as const + +/** + * Workspace areas that never reach a user: repository tooling and gates (the + * root manifest), test infrastructure, the documentation site, the runnable + * demo leaves, and the native launcher's build workspace. A runtime + * declaration by anything outside these areas is a disclosure-relevant + * runtime dependency, because `scripts/install.sh` installs the repository + * itself and any plugin package can be mounted from a user's `cordis.yml`. + */ +const DEV_ONLY_AREAS = [ + 'package.json', + 'packages/support/', + 'packages/client/test-runtime/', + 'website/', + 'examples/', + 'native/', +] as const + +/** + * First-party packages released from sibling repositories under the project's + * own license: reachable from workspace manifests but not third-party. + */ +const FIRST_PARTY = new Set(['node-addon-landlock-run']) + +/** + * Metadata overrides where the installed manifest is wrong or unreachable. + * Each entry documents why the store cannot answer. + */ +const OVERRIDES: Record = { + // Rust workspaces publishing npm bins without `license` in package.json. + 'oxlint': { license: 'MIT', repo: 'https://github.com/oxc-project/oxc' }, + 'oxlint-tsgolint': { license: 'MIT', repo: 'https://github.com/oxc-project/tsgolint' }, + // `license: SEE LICENSE IN LICENSE`: the servers repo is mid MIT→Apache-2.0 + // relicensing, so the effective terms are per-contribution. + '@modelcontextprotocol/server-everything': { license: 'MIT / Apache-2.0', repo: 'https://github.com/modelcontextprotocol/servers' }, + '@modelcontextprotocol/server-filesystem': { license: 'MIT / Apache-2.0', repo: 'https://github.com/modelcontextprotocol/servers' }, + // No repository field in the published manifest. + 'node-addon-require-builtin': { repo: 'https://www.npmjs.com/package/node-addon-require-builtin' }, +} + +/** + * Python dependencies are few and named directly in `pyproject.toml` files + * without installed metadata to harvest, so license/repo are recorded here and + * the generator fails when a manifest names a package this map misses. + */ +const PYTHON_METADATA: Record = { + pydantic: { license: 'MIT', repo: 'https://github.com/pydantic/pydantic', role: 'runtime dependency of `deepseek-harness`' }, + hatchling: { license: 'MIT', repo: 'https://github.com/pypa/hatch', role: 'build backend' }, + pytest: { license: 'MIT', repo: 'https://github.com/pytest-dev/pytest', role: 'test-only' }, +} + +/** Tools fetched by scripts at build time, keyed by the pin the script owns. */ +const BUILD_TIME_TOOLS = [ + { + name: '@yao-pkg/pkg', + license: 'MIT', + repo: 'https://github.com/yao-pkg/pkg', + role: 'invoked by `scripts/build-exe-for-python-sdk.ts` to assemble the single-file SDK runtime executable', + pinSource: 'scripts/build-exe-for-python-sdk.ts', + }, +] + +/** The `package.json` fields this generator reads. */ +export interface Manifest { + name?: string + private?: boolean + license?: string + dependencies?: Record + devDependencies?: Record + optionalDependencies?: Record + peerDependencies?: Record +} + +/** One disclosed external npm dependency. */ +interface ExternalDep { + name: string + license: string + repo: string + /** True when some shipped workspace consumer reaches it through runtime dependency edges. */ + runtime: boolean +} + +/** Read and parse a workspace-relative `package.json`. */ +function readManifest(rel: string): Manifest { + return JSON.parse(readFileSync(resolve(root, rel), 'utf8')) as Manifest +} + +/** Every workspace manifest, keyed by path, plus the set of workspace package names. */ +function loadWorkspaceManifests(): { manifests: Map; names: Set } { + const patterns = ['package.json', 'vendor/*/package.json', 'packages/*/*/package.json', 'apps/*/package.json', 'website/package.json', 'examples/package.json', 'python/sdk-runtime/package.json', 'native/landlock-run/package.json', 'native/landlock-run/*/package.json'] + const manifests = new Map() + const names = new Set() + for (const pattern of patterns) { + for (const path of globSync(pattern, { cwd: root })) { + const manifest = readManifest(path) + manifests.set(path, manifest) + if (manifest.name !== undefined) names.add(manifest.name) + } + } + if (manifests.size < 100) throw new Error(`gen-third-party-notices: only ${manifests.size} workspace manifests found; the glob set is stale.`) + return { manifests, names } +} + +/** License and repository URL for an installed external package, from the pnpm store. */ +function installedMetadata(name: string): { license: string; repo: string } { + const override = OVERRIDES[name] + let manifest: (Manifest & { license?: string; repository?: string | { url?: string }; homepage?: string }) | undefined + const direct = resolve(root, 'node_modules', name, 'package.json') + if (existsSync(direct)) { + manifest = JSON.parse(readFileSync(direct, 'utf8')) as typeof manifest + } else { + const prefix = `${name.replace('/', '+')}@` + const entry = readdirSync(resolve(root, 'node_modules/.pnpm')).find(dir => dir.startsWith(prefix)) + if (entry !== undefined) { + manifest = JSON.parse(readFileSync(resolve(root, 'node_modules/.pnpm', entry, 'node_modules', name, 'package.json'), 'utf8')) as typeof manifest + } + } + const license = override?.license ?? manifest?.license + const rawRepo = typeof manifest?.repository === 'string' ? manifest.repository : manifest?.repository?.url ?? manifest?.homepage + const repo = override?.repo ?? normalizeRepo(rawRepo) + if (license === undefined || repo === undefined) { + throw new Error(`gen-third-party-notices: cannot resolve ${license === undefined ? 'license' : 'repository'} for ${name}; install the tree or add an OVERRIDES entry.`) + } + return { license, repo } +} + +/** Normalize a manifest repository/homepage value to a browsable https URL. */ +function normalizeRepo(raw: string | undefined): string | undefined { + if (raw === undefined || raw === '') return undefined + let url = raw + .replace(/^git\+ssh:\/\/git@/, 'https://') + .replace(/^git\+/, '') + .replace(/^git:\/\//, 'https://') + .replace(/^github:/, 'https://github.com/') + .replace(/\.git$/, '') + if (!url.startsWith('http')) url = `https://github.com/${url}` + return url +} + +/** + * External npm dependencies, tiered by which workspace area declares them at + * runtime: a package is runtime when any manifest outside `DEV_ONLY_AREAS` + * names it in `dependencies`/`optionalDependencies`. A package declared only + * by tooling, test infrastructure, the website, or the demo leaves — whatever + * the declaring section is called — is development-only. + */ +function collectNpmDeps(): ExternalDep[] { + const { manifests, names } = loadWorkspaceManifests() + return [...tierExternalDeps(manifests, names)] + .filter(([name]) => !FIRST_PARTY.has(name)) + .sort(([a], [b]) => a.localeCompare(b)) + .map(([name, runtime]) => ({ name, ...installedMetadata(name), runtime })) +} + +/** + * Tier every external dependency the workspace declares. + * @param manifests - workspace manifests keyed by repository-relative path. + * @param names - every workspace package name, which never counts as external. + * @returns each external package mapped to whether it is a runtime dependency. + */ +export function tierExternalDeps(manifests: Map, names: Set): Map { + const tiers = new Map() + // `tsx` is runtime by fiat: `bin/dsh` execs the CLI through its ESM hook. + tiers.set('tsx', true) + for (const [path, manifest] of manifests) { + const devOnly = DEV_ONLY_AREAS.some(area => (area.endsWith('/') ? path.startsWith(area) : path === area)) + for (const kind of ALL_KINDS) { + for (const [dep, range] of Object.entries(manifest[kind] ?? {})) { + if (names.has(dep) || range.startsWith('workspace:')) continue + const runtime = !devOnly && (RUNTIME_KINDS as readonly string[]).includes(kind) + tiers.set(dep, (tiers.get(dep) ?? false) || runtime) + } + } + } + return tiers +} + +/** A vendored package row parsed out of the `vendor/README.md` manifest table. */ +export interface VendoredRow { + npmName: string + upstream: string +} + +/** + * Parse the vendored-package manifest table out of `vendor/README.md`. + * @param text - the complete `vendor/README.md` contents. + * @returns one row per manifest-table entry, in table order. + */ +export function parseVendoredRows(text: string): VendoredRow[] { + const rows: VendoredRow[] = [] + for (const line of text.split('\n')) { + const match = /^\| \x60\S+\/\x60 \| \x60([^\x60]+)\x60 \| \S+ \| (https:\/\/\S+?)(?: \([^)]*\))? \| \x60[0-9a-f]+\x60 \|$/.exec(line) + if (match === null) continue + const [, npmName, upstream] = match + if (npmName === undefined || upstream === undefined) continue + rows.push({ npmName, upstream }) + } + return rows +} + +/** Parse the vendored manifest table and confirm every vendored package is MIT. */ +function collectVendored(): VendoredRow[] { + const rows = parseVendoredRows(readFileSync(resolve(root, 'vendor/README.md'), 'utf8')) + if (rows.length === 0) throw new Error('gen-third-party-notices: no vendored rows parsed from vendor/README.md; its table format changed.') + for (const row of rows) { + const manifest = readManifest(`vendor/${vendorDir(row.npmName)}/package.json`) + if (manifest.license !== 'MIT') { + throw new Error(`gen-third-party-notices: vendored ${row.npmName} declares license ${JSON.stringify(manifest.license)}; the vendored section assumes MIT throughout.`) + } + } + return rows +} + +/** The vendor/ directory of a vendored npm name (manifest table order is authoritative for names). */ +function vendorDir(npmName: string): string { + const dirs = readdirSync(resolve(root, 'vendor'), { withFileTypes: true }).filter(entry => entry.isDirectory()).map(entry => entry.name) + for (const dir of dirs) { + const manifest = readManifest(`vendor/${dir}/package.json`) + if (manifest.name === npmName) return dir + } + throw new Error(`gen-third-party-notices: vendored package ${npmName} from vendor/README.md has no vendor/ directory.`) +} + +/** Direct Python dependencies named by the `pyproject.toml` manifests under `python/`. */ +function collectPython(): { name: string; license: string; repo: string; role: string }[] { + const found = new Set() + for (const path of ['python/sdk/pyproject.toml', 'python/sdk-runtime/pyproject.toml']) { + const text = readFileSync(resolve(root, path), 'utf8') + for (const match of text.matchAll(/"([a-zA-Z][a-zA-Z0-9._-]*)\s*(?:>=|==|~=|<|>|\[)/g)) { + const name = match[1] + if (name === undefined || name.startsWith('deepseek')) continue + found.add(name) + } + } + return [...found].sort((a, b) => a.localeCompare(b)).map((name) => { + const metadata = PYTHON_METADATA[name] + if (metadata === undefined) throw new Error(`gen-third-party-notices: python dependency ${name} is missing from PYTHON_METADATA.`) + return { name, ...metadata } + }) +} + +/** pnpm-patched external packages, from `pnpm-workspace.yaml`. */ +function collectPatched(): { spec: string; patch: string }[] { + const workspace = yaml.load(readFileSync(resolve(root, 'pnpm-workspace.yaml'), 'utf8')) as { patchedDependencies?: Record } + return Object.entries(workspace.patchedDependencies ?? {}).map(([spec, patch]) => ({ spec, patch })) +} + +/** Verify each build-time tool pin still appears in its owning script. */ +function verifyBuildTimePins(): void { + for (const tool of BUILD_TIME_TOOLS) { + const text = readFileSync(resolve(root, tool.pinSource), 'utf8') + if (!text.includes(tool.name)) { + throw new Error(`gen-third-party-notices: ${tool.pinSource} no longer references ${tool.name}; update BUILD_TIME_TOOLS.`) + } + } +} + +/** Render one npm dependency table. */ +function renderNpmTable(deps: ExternalDep[]): string { + const lines = ['| Package | License |', '| --- | --- |'] + for (const dep of deps) lines.push(`| [\`${dep.name}\`](${dep.repo}) | ${dep.license} |`) + return lines.join('\n') +} + +/** Render the complete notices document. */ +function render(): string { + verifyBuildTimePins() + const npm = collectNpmDeps() + const runtimeDeps = npm.filter(dep => dep.runtime) + const devDeps = npm.filter(dep => !dep.runtime) + const vendored = collectVendored() + const python = collectPython() + const patched = collectPatched() + + const nonPermissiveDev = devDeps.filter(dep => dep.license.startsWith('LGPL') || dep.license.startsWith('MPL')) + const patchedLines = patched.map(({ spec, patch }) => `- \`${spec}\` — [\`${patch}\`](${patch})`) + + return ` + +# Third-Party Notices + +DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the third-party open-source software listed below. Each project remains under its own license; nothing in this file changes those terms. + +This file lists **direct** dependencies declared by the workspace, generated from the workspace manifests by \`scripts/gen-third-party-notices.ts\` and verified fresh by \`pnpm run verify-third-party-notices\` (part of \`doc-sync\`). The complete npm transitive closure, with exact pinned versions, is recorded in [\`pnpm-lock.yaml\`](pnpm-lock.yaml) (inspect it with \`pnpm licenses list\`); the Python closure is recorded in [\`python/sdk/uv.lock\`](python/sdk/uv.lock). + +## Vendored source (\`vendor/\`) + +The Cordis framework and its foundation libraries are source-vendored into this repository rather than consumed from npm. All are MIT-licensed; each directory preserves its upstream \`LICENSE\` file. Exact upstream commits and local modifications are recorded in [\`vendor/README.md\`](vendor/README.md). + +| Package | Upstream | License | +| --- | --- | --- | +${vendored.map(row => `| \`${row.npmName}\` | [${row.upstream.replace('https://', '')}](${row.upstream}) | MIT |`).join('\n')} + +## Runtime npm dependencies + +External packages that a workspace package resolves at runtime. \`scripts/install.sh\` installs this repository itself, so the tier covers every plugin a user can mount from \`cordis.yml\` — not only what the \`dsh\` CLI/TUI, the Web UI, and the Python SDK runtime load by default. + +${renderNpmTable(runtimeDeps)} + +pnpm applies local patches to the following packages at install time, so shipped artifacts carry modified copies; each patch file is the complete record of the modification: + +${patchedLines.join('\n')} + +## Development-only npm dependencies + +External packages declared only by repository tooling, test infrastructure, the documentation site, the demo leaves, or the native launcher's build workspace. They are not part of any shipped runtime artifact. + +${renderNpmTable(devDeps)} + +${nonPermissiveDev.map(dep => `\`${dep.name}\` (${dep.license})`).join(' and ')} run only as development tooling; their code is not linked into or distributed with any DeepSeek Harness artifact. + +## Python SDK dependencies (\`python/\`) + +Direct dependencies of the \`pyproject.toml\` manifests, plus \`uv\` as the development workflow tool. + +| Package | License | Role | +| --- | --- | --- | +${python.map(dep => `| [\`${dep.name}\`](${dep.repo}) | ${dep.license} | ${dep.role} |`).join('\n')} +| [\`uv\`](https://github.com/astral-sh/uv) | MIT / Apache-2.0 | development workflow tool | + +## Fetched at build time + +| Package | License | Role | +| --- | --- | --- | +${BUILD_TIME_TOOLS.map(tool => `| [\`${tool.name}\`](${tool.repo}) | ${tool.license} | ${tool.role} |`).join('\n')} + +## First-party sibling releases + +\`node-addon-landlock-run\` (and its platform packages) is released from a DeepSeek Harness sibling repository under BSD 3-Clause. It is listed here for completeness; it is first-party, not third-party. +` +} + +/** CLI entry: default writes the notices, `--check` fails if the committed copy + * is stale. Guarded behind an entry-point check so importing this module for + * tests neither regenerates the committed file nor calls process.exit. */ +function main(): void { + const content = render() + if (process.argv.includes('--check')) { + let committed: string | null = null + try { + committed = readFileSync(resolve(root, OUT), 'utf8') + } catch { + // Only ENOENT (not yet generated) is expected; a present-but-unreadable + // file is not a state this repo produces, and the remedy is the same. + committed = null + } + if (committed === content) { + console.log(`gen-third-party-notices: ${OUT} is up to date.`) + process.exit(0) + } + console.error(`gen-third-party-notices: ${OUT} is stale. Run \`pnpm run gen-third-party-notices\` and commit ${OUT}.`) + process.exit(1) + } + + writeFileSync(resolve(root, OUT), content) + console.log(`gen-third-party-notices: wrote ${OUT}.`) +} + +// Run only when invoked as a script, not when imported by a test. +if (process.argv[1] !== undefined && import.meta.filename === resolve(process.argv[1])) { + main() +} diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index 167d226ff8..a5c1870a51 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -472,6 +472,7 @@ function docSyncLeafGates(options: { pnpmScript('tool-catalog', 'verify-tool-catalog', { label: 'tool catalog' }), pnpmScript('config-catalog', 'verify-config-catalog', { label: 'config catalog' }), pnpmScript('persistence-catalog', 'verify-persistence-catalog', { label: 'persistence catalog' }), + pnpmScript('third-party-notices', 'verify-third-party-notices', { label: 'third-party notices' }), pnpmScript('doc-graphs', 'verify-doc-graphs', { label: 'doc graphs' }), pnpmScript('scoped-events', 'verify-scoped-events', { label: 'scoped events' }), pnpmScript('markdown-wrap', 'verify-md-wrap', { label: 'markdown wrap' }), diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json index 78255907c3..e4eb2a3e39 100644 --- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json +++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json @@ -8,11 +8,11 @@ }, { "role": "user", - "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Install\n\nInstall `dsh` with one command:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh\n```\n\nThe installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, and prompts for a DeepSeek API key.\n\nThe installer keeps every checkout under `~/.dsh/source`: the master clone at `~/.dsh/source/master` and each install's staging checkout as a git worktree `~/.dsh/source/staging-`. The stable symlink `~/.dsh/source/current` points at the active staging worktree, and `dsh` in `~/.local/bin` links to `current/bin/dsh`, so an upgrade repoints one symlink and the `dsh` on PATH never moves. Re-running the command adds a fresh staging worktree from an updated master and repoints `current` at it. See [`scripts/install.sh`](scripts/install.sh) for alternate install locations and other options.\n\n## Use DeepSeek Harness\n\n### Web UI\n\nFor the recommended local interface, build the frontend after installation and after each update, then start the Web UI. Resolve the running checkout from the `dsh` launcher so the command holds regardless of which staging worktree is current (the launcher resolves through the stable `current` symlink):\n\n```sh\ndsh_bin=$(cd \"$(dirname \"$(command -v dsh)\")\" && pwd -P)/$(basename \"$(command -v dsh)\")\nwhile [ -L \"$dsh_bin\" ]; do\n link=$(readlink \"$dsh_bin\")\n case $link in /*) dsh_bin=$link ;; *) dsh_bin=$(cd \"$(dirname \"$dsh_bin\")\" && cd \"$(dirname \"$link\")\" && pwd -P)/$(basename \"$link\") ;; esac\ndone\ndsh_dir=$(cd \"$(dirname \"$dsh_bin\")/..\" && pwd -P)\npnpm --dir \"$dsh_dir\" run build && pnpm --dir \"$dsh_dir\" run build:web\ndsh web\n```\n\nThe Web UI is served at `http://127.0.0.1:3080` by default.\n\n### TUI\n\nStart the full-screen terminal interface:\n\n```sh\ndsh\n```\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\ndsh -p \"summarize this workspace\"\n```\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell execution; reusable skills; task tracking; subagents and workflows; persistent sessions; and context compaction. The TUI also includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/cordis/tool-cordis/README.md).\n\n## Community\n\nFollow DeepSeek Harness on Twitter for project updates.\n\n## Development\n\n```sh\npnpm install\npnpm run test:coverage\n```\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\nDeepSeek Harness is currently pre-release.\n\n## License\n\n[BSD 3-Clause](LICENSE)\n" + "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Install\n\nInstall `dsh` with one command:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh\n```\n\nThe installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, and prompts for a DeepSeek API key.\n\nThe installer keeps every checkout under `~/.dsh/source`: the master clone at `~/.dsh/source/master` and each install's staging checkout as a git worktree `~/.dsh/source/staging-`. The stable symlink `~/.dsh/source/current` points at the active staging worktree, and `dsh` in `~/.local/bin` links to `current/bin/dsh`, so an upgrade repoints one symlink and the `dsh` on PATH never moves. Re-running the command adds a fresh staging worktree from an updated master and repoints `current` at it. See [`scripts/install.sh`](scripts/install.sh) for alternate install locations and other options.\n\n## Use DeepSeek Harness\n\n### Web UI\n\nFor the recommended local interface, build the frontend after installation and after each update, then start the Web UI. Resolve the running checkout from the `dsh` launcher so the command holds regardless of which staging worktree is current (the launcher resolves through the stable `current` symlink):\n\n```sh\ndsh_bin=$(cd \"$(dirname \"$(command -v dsh)\")\" && pwd -P)/$(basename \"$(command -v dsh)\")\nwhile [ -L \"$dsh_bin\" ]; do\n link=$(readlink \"$dsh_bin\")\n case $link in /*) dsh_bin=$link ;; *) dsh_bin=$(cd \"$(dirname \"$dsh_bin\")\" && cd \"$(dirname \"$link\")\" && pwd -P)/$(basename \"$link\") ;; esac\ndone\ndsh_dir=$(cd \"$(dirname \"$dsh_bin\")/..\" && pwd -P)\npnpm --dir \"$dsh_dir\" run build && pnpm --dir \"$dsh_dir\" run build:web\ndsh web\n```\n\nThe Web UI is served at `http://127.0.0.1:3080` by default.\n\n### TUI\n\nStart the full-screen terminal interface:\n\n```sh\ndsh\n```\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\ndsh -p \"summarize this workspace\"\n```\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell execution; reusable skills; task tracking; subagents and workflows; persistent sessions; and context compaction. The TUI also includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/cordis/tool-cordis/README.md).\n\n## Community\n\nFollow DeepSeek Harness on Twitter for project updates.\n\n## Development\n\n```sh\npnpm install\npnpm run test:coverage\n```\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\nDeepSeek Harness is currently pre-release.\n\n## License\n\n[BSD 3-Clause](LICENSE)\n\nThird-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n" }, { "role": "assistant", - "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 安装\n\n使用一条命令安装 `dsh`：\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥。\n\n安装器会把所有检出都放在 `~/.dsh/source` 下：master 克隆位于 `~/.dsh/source/master`，每次安装的 staging 检出是一个 git worktree `~/.dsh/source/staging-<时间戳>`。稳定符号链接 `~/.dsh/source/current` 指向当前生效的 staging worktree，`~/.local/bin` 中的 `dsh` 链接到 `current/bin/dsh`，因此升级只需重指一个符号链接，PATH 上的 `dsh` 从不移动。再次运行该命令会基于更新后的 master 新增一个 staging worktree，并把 `current` 重指到它。其他安装位置和选项见 [`scripts/install.sh`](scripts/install.sh)。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI。安装完成后以及每次更新后，请先构建前端，再启动 Web UI。通过 `dsh` 启动器解析当前运行的检出，这样无论当前是哪个 staging worktree，命令都成立（启动器会经由稳定的 `current` 符号链接解析）：\n\n```sh\ndsh_bin=$(cd \"$(dirname \"$(command -v dsh)\")\" && pwd -P)/$(basename \"$(command -v dsh)\")\nwhile [ -L \"$dsh_bin\" ]; do\n link=$(readlink \"$dsh_bin\")\n case $link in /*) dsh_bin=$link ;; *) dsh_bin=$(cd \"$(dirname \"$dsh_bin\")\" && cd \"$(dirname \"$link\")\" && pwd -P)/$(basename \"$link\") ;; esac\ndone\ndsh_dir=$(cd \"$(dirname \"$dsh_bin\")/..\" && pwd -P)\npnpm --dir \"$dsh_dir\" run build && pnpm --dir \"$dsh_dir\" run build:web\ndsh web\n```\n\nWeb UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### TUI\n\n启动全屏终端界面：\n\n```sh\ndsh\n```\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh -p \"summarize this workspace\"\n```\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 执行、可复用 skill（技能）、任务跟踪、subagent 与工作流、持久化会话，以及上下文压缩（context compaction）。TUI 还包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/cordis/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 DeepSeek Harness 微信社区申请页面 申请加入。\n\n

\n \"DeepSeek\n

\n\n## 开发\n\n```sh\npnpm install\npnpm run test:coverage\n```\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于预发布阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n" + "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 安装\n\n使用一条命令安装 `dsh`：\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥。\n\n安装器会把所有检出都放在 `~/.dsh/source` 下：master 克隆位于 `~/.dsh/source/master`，每次安装的 staging 检出是一个 git worktree `~/.dsh/source/staging-<时间戳>`。稳定符号链接 `~/.dsh/source/current` 指向当前生效的 staging worktree，`~/.local/bin` 中的 `dsh` 链接到 `current/bin/dsh`，因此升级只需重指一个符号链接，PATH 上的 `dsh` 从不移动。再次运行该命令会基于更新后的 master 新增一个 staging worktree，并把 `current` 重指到它。其他安装位置和选项见 [`scripts/install.sh`](scripts/install.sh)。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI。安装完成后以及每次更新后，请先构建前端，再启动 Web UI。通过 `dsh` 启动器解析当前运行的检出，这样无论当前是哪个 staging worktree，命令都成立（启动器会经由稳定的 `current` 符号链接解析）：\n\n```sh\ndsh_bin=$(cd \"$(dirname \"$(command -v dsh)\")\" && pwd -P)/$(basename \"$(command -v dsh)\")\nwhile [ -L \"$dsh_bin\" ]; do\n link=$(readlink \"$dsh_bin\")\n case $link in /*) dsh_bin=$link ;; *) dsh_bin=$(cd \"$(dirname \"$dsh_bin\")\" && cd \"$(dirname \"$link\")\" && pwd -P)/$(basename \"$link\") ;; esac\ndone\ndsh_dir=$(cd \"$(dirname \"$dsh_bin\")/..\" && pwd -P)\npnpm --dir \"$dsh_dir\" run build && pnpm --dir \"$dsh_dir\" run build:web\ndsh web\n```\n\nWeb UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### TUI\n\n启动全屏终端界面：\n\n```sh\ndsh\n```\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh -p \"summarize this workspace\"\n```\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 执行、可复用 skill（技能）、任务跟踪、subagent 与工作流、持久化会话，以及上下文压缩（context compaction）。TUI 还包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/cordis/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 DeepSeek Harness 微信社区申请页面 申请加入。\n\n

\n \"DeepSeek\n

\n\n## 开发\n\n```sh\npnpm install\npnpm run test:coverage\n```\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于预发布阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n" }, { "role": "user", From 04c73df2f69f8939ffa84361bbc9549a8560094d Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Thu, 30 Jul 2026 07:56:13 -0700 Subject: [PATCH 09/50] docs: keep notices fresh at commit time instead of a new CI gate Regenerate THIRD_PARTY_NOTICES.md from a pre-commit job whenever a manifest, lock file, vendor manifest, or pyproject is staged, and assert the committed bytes inside the generator spec the test lane already runs. Drops the separate doc-sync gate: no extra CI process, and a dependency edit no longer bounces back from CI to rerun a generator. --- ...026-07-30-generated-third-party-notices.i18n.yaml | 4 ++-- .../2026-07-30-generated-third-party-notices.md | 12 ++++++++---- .../2026-07-30-generated-third-party-notices.zh.md | 12 ++++++++---- lefthook.yml | 6 ++++++ scripts/gen-third-party-notices.spec.ts | 12 +++++++++++- scripts/gen-third-party-notices.ts | 7 +++++-- scripts/run-gates.ts | 1 - 7 files changed, 40 insertions(+), 14 deletions(-) diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml index 32d76bbc9c..d410427440 100644 --- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml +++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.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/process/2026-07-30-generated-third-party-notices.md -2026-07-30-generated-third-party-notices.md: 5b85abf5716d79213f6937b938d3f0267f7627f3 -2026-07-30-generated-third-party-notices.zh.md: 26b3e6e88ec038d9107c9b78c85a8c45a1916805 +2026-07-30-generated-third-party-notices.md: 2a669be4c8dcf92beb08c1305098e1baa7626ef4 +2026-07-30-generated-third-party-notices.zh.md: 990d15238a2939c54b4242016f9986e3f58a260b diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md index 5b85abf571..2a669be4c8 100644 --- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md +++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md @@ -8,11 +8,13 @@ English | [中文](2026-07-30-generated-third-party-notices.zh.md) Open-sourcing this repository requires disclosing the third-party software it depends on, with each project's license. The disclosure has to be complete, has to stay true as dependencies change, and has to say something a reader can act on — which of these packages end up on a user's machine, and which only build and test the repository. -A hand-written inventory answers none of those durably. Roughly a hundred rows of names and license strings derived from manifests drift silently the moment a package is added, removed, or relicensed, and nothing in `doc-sync` would notice. +A hand-written inventory answers none of those durably. Roughly a hundred rows of names and license strings derived from manifests drift silently the moment a package is added, removed, or relicensed, and nothing would notice. ## Decision -[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) is generated by [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) from the workspace manifests, `vendor/README.md`, the `pyproject.toml` files, and `pnpm-workspace.yaml`. `pnpm run verify-third-party-notices` runs the generator with `--check` as a `doc-sync` leaf gate, so a dependency change that skips regeneration fails the same way a stale catalog does. The root README pair links the file from its License section. +[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) is generated by [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) from the workspace manifests, `vendor/README.md`, the `pyproject.toml` files, and `pnpm-workspace.yaml`. The root README pair links the file from its License section. + +**Freshness is maintained, not merely enforced.** A pre-commit job regenerates the file and stages it whenever a manifest, lock file, `vendor/README.md`, or `pyproject.toml` is staged, so an unrelated dependency edit never has to come back and rerun a generator. The committed bytes are then asserted inside [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts), which the test lane already runs — the check adds no gate process, no scheduler slot, and no separate CI step. `pnpm run verify-third-party-notices` remains available for a standalone check. The file discloses **direct** dependencies only. The complete npm closure with pinned versions already lives in `pnpm-lock.yaml` (`pnpm licenses list` renders it) and the Python closure in `python/sdk/uv.lock`; re-materializing either as prose would be a second, worse copy. @@ -24,12 +26,14 @@ License and repository metadata come from the installed pnpm store, so the gener ## Testing -[`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) pins the tiering rule against fixture manifests — including the two cases that motivate it, a `dependencies` entry of a test-support package and a plugin package no app mounts — and pins that the vendored-table parser reads the committed manifest and yields nothing when the table shape changes, which is what makes the generator fail loud rather than emit an empty section. +The same spec that asserts freshness pins the tiering rule against fixture manifests — including the two cases that motivate it, a `dependencies` entry of a test-support package and a plugin package no app mounts — and pins that the vendored-table parser reads the committed manifest and yields nothing when the table shape changes, which is what makes the generator fail loud rather than emit an empty section. ## Alternatives considered **Keep the hand-written file and review it at release time.** Reviewing a hundred derived rows by eye is exactly the work a generator does correctly, and the file's own claim — that it lists every direct dependency — would be unverified between releases. +**Verify through a dedicated `doc-sync` gate.** That is how every other generated artifact here is checked, and it was the first shape of this change. It costs a gate process and a scheduler slot in a matrix that is already long, and — worse — its only failure mode is telling a contributor, minutes after they pushed an unrelated dependency bump, to go rerun a generator. Regenerating at commit time removes the interruption, and the assertion inside a spec the test lane already runs keeps the guarantee at no additional CI cost. + **Enumerate the full transitive closure.** The closure is thousands of packages, already recorded in the lock files with exact versions, and would bury the direct dependencies that a reader actually evaluates. The file points at the lock files and the `pnpm licenses list` renderer instead. **Tier by manifest section (`dependencies` vs `devDependencies`).** Mechanically simple and wrong on real data in both directions, as the tiering paragraph above records. @@ -40,7 +44,7 @@ License and repository metadata come from the installed pnpm store, so the gener ## Consequences -Adding or removing a dependency now requires running `pnpm run gen-third-party-notices` and committing the result; `doc-sync` fails otherwise. That is the intended cost — the disclosure cannot silently go stale. +A dependency edit now carries a regenerated notices file into the same commit. Contributors pay one generator run — about a second — on commits that touch a manifest, and nothing on any other commit. Committing with hooks disabled defers the cost to a test-lane failure that names the command. The generator needs an installed tree, which makes it heavier than a pure-source generator, and a new package with unusable published metadata needs an `OVERRIDES` entry rather than silently rendering a blank license. Both failures are loud and name the remedy. diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md index 26b3e6e88e..990d15238a 100644 --- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md +++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md @@ -8,11 +8,13 @@ Status: implemented 本仓库开源需要披露所依赖的第三方软件及各自的许可证。这份披露必须完整，必须随依赖变化保持为真，还必须给出读者用得上的信息：哪些包最终会进到用户机器上，哪些只用于构建和测试。 -手写清单无法长期满足其中任何一条。约一百行从各清单文件推导出来的包名与许可证标识，只要有依赖新增、移除或换用许可证就会悄悄失真，而 `doc-sync` 不会察觉。 +手写清单无法长期满足其中任何一条。约一百行从各清单文件推导出来的包名与许可证标识，只要有依赖新增、移除或换用许可证就会悄悄失真，而没有任何检查会察觉。 ## Decision -[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) 由 [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) 依据各工作区清单、`vendor/README.md`、`pyproject.toml` 与 `pnpm-workspace.yaml` 生成。`pnpm run verify-third-party-notices` 以 `--check` 运行生成器，作为 `doc-sync` 的叶子门禁；依赖变了却没重新生成，会像目录过期一样直接失败。根 README 双语两侧都从「许可证」一节链到该文件。 +[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) 由 [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) 依据各工作区清单、`vendor/README.md`、`pyproject.toml` 与 `pnpm-workspace.yaml` 生成。根 README 双语两侧都从「许可证」一节链到该文件。 + +**新鲜度靠维护而非拦截。** 只要暂存了清单文件、锁文件、`vendor/README.md` 或 `pyproject.toml`，pre-commit 任务就会重新生成并一并入库，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。 文件只披露**直接**依赖。完整的 npm 闭包连同锁定版本已记录在 `pnpm-lock.yaml`（`pnpm licenses list` 可渲染），Python 闭包记录在 `python/sdk/uv.lock`；再用散文誊一遍只会得到一份更差的副本。 @@ -24,12 +26,14 @@ Status: implemented ## Testing -[`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 用夹具清单钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它同时钉住被收编包的表格解析器能读出已提交的清单表，且表格形态一变就解析为空——正是这一点让生成器直接失败，而不是产出一个空章节。 +断言新鲜度的同一个 spec 也用夹具清单钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它同时钉住被收编包的表格解析器能读出已提交的清单表，且表格形态一变就解析为空——正是这一点让生成器直接失败，而不是产出一个空章节。 ## Alternatives considered **保留手写文件，发版时人工过一遍。** 用肉眼审阅上百行推导数据，恰恰是生成器能做对的活；而且在两次发版之间，文件自称「列出全部直接依赖」这句话无人验证。 +**用专门的 `doc-sync` 门禁校验。** 仓库里其他生成产物都是这么把关的，本次改动最初也是这个形态。但它要在本已冗长的矩阵里再占一个门禁进程和一个调度位；更糟的是，它唯一的失败方式，就是在别人推完一个无关的依赖升级几分钟后，通知对方回去重跑一次生成器。改为提交时重新生成消除了这次打断，而把断言放进测试 lane 本就会跑的 spec 里，则以零额外 CI 成本保住了这项保证。 + **列出完整传递闭包。** 闭包有数千个包，锁文件里已带精确版本，铺开只会淹没读者真正要评估的直接依赖。文件转而指向锁文件与 `pnpm licenses list`。 **按清单字段分层（`dependencies` 与 `devDependencies`）。** 机械上最省事，但在真实数据上两个方向都会出错，理由见上文分层段落。 @@ -40,7 +44,7 @@ Status: implemented ## Consequences -此后增删依赖都需要运行 `pnpm run gen-third-party-notices` 并提交结果，否则 `doc-sync` 失败。这正是预期成本——披露不可能再悄悄过期。 +此后改动依赖时，重新生成的披露文件会随同一个提交入库。触及清单文件的提交多付一次生成器运行——约一秒；其余提交不受影响。若禁用钩子提交，代价推迟为一次测试 lane 失败，其报错会指明补救命令。 生成器需要已安装的工作树，因此比纯源码生成器更重；发布元数据不可用的新包需要补一条 `OVERRIDES`，而不是默默渲染出空白许可证。这两类失败都会明确报错并指出补救方式。 diff --git a/lefthook.yml b/lefthook.yml index 1a4e004842..b5f9d09fe8 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -18,6 +18,12 @@ pre-commit: run: node_modules/.bin/tsx scripts/run-oxlint.ts --fix --no-error-on-unmatched-pattern {staged_files} stage_fixed: true + # Regenerate rather than reject: a dependency edit that forgot the notices + # would otherwise fail the test lane long after the commit. + - name: third-party notices (staged) + glob: '{package.json,*/package.json,*/*/package.json,*/*/*/package.json,pnpm-workspace.yaml,pnpm-lock.yaml,vendor/README.md,python/*/pyproject.toml}' + run: node_modules/.bin/tsx scripts/gen-third-party-notices.ts && git add THIRD_PARTY_NOTICES.md + - name: whitespace (staged) run: git diff --cached --check diff --git a/scripts/gen-third-party-notices.spec.ts b/scripts/gen-third-party-notices.spec.ts index 57c28ae151..9900364bd3 100644 --- a/scripts/gen-third-party-notices.spec.ts +++ b/scripts/gen-third-party-notices.spec.ts @@ -1,10 +1,20 @@ import { readFileSync } from 'node:fs' import { resolve } from 'node:path' import { describe, expect, it } from 'vitest' -import { type Manifest, parseVendoredRows, tierExternalDeps } from './gen-third-party-notices.ts' +import { type Manifest, parseVendoredRows, render, tierExternalDeps } from './gen-third-party-notices.ts' const root = resolve(import.meta.dirname, '..') +describe('THIRD_PARTY_NOTICES.md', () => { + // Freshness lives here rather than in its own doc-sync gate: this spec file + // already runs in the test lane, so the check costs no extra CI process. + // Pre-commit regenerates the file whenever a manifest is staged, so reaching + // this assertion means the notices were committed without that hook. + it('matches what the generator produces from the current manifests', () => { + expect(readFileSync(resolve(root, 'THIRD_PARTY_NOTICES.md'), 'utf8'), 'stale notices — run `pnpm run gen-third-party-notices`').toBe(render()) + }) +}) + /** Build the (manifests, names) pair `tierExternalDeps` consumes. */ function workspace(entries: Record): { manifests: Map; names: Set } { const manifests = new Map(Object.entries(entries)) diff --git a/scripts/gen-third-party-notices.ts b/scripts/gen-third-party-notices.ts index 16cbe6153c..243ed2d3ad 100644 --- a/scripts/gen-third-party-notices.ts +++ b/scripts/gen-third-party-notices.ts @@ -283,8 +283,11 @@ function renderNpmTable(deps: ExternalDep[]): string { return lines.join('\n') } -/** Render the complete notices document. */ -function render(): string { +/** + * Render the complete notices document. + * @returns the exact bytes `THIRD_PARTY_NOTICES.md` must hold. + */ +export function render(): string { verifyBuildTimePins() const npm = collectNpmDeps() const runtimeDeps = npm.filter(dep => dep.runtime) diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index a5c1870a51..167d226ff8 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -472,7 +472,6 @@ function docSyncLeafGates(options: { pnpmScript('tool-catalog', 'verify-tool-catalog', { label: 'tool catalog' }), pnpmScript('config-catalog', 'verify-config-catalog', { label: 'config catalog' }), pnpmScript('persistence-catalog', 'verify-persistence-catalog', { label: 'persistence catalog' }), - pnpmScript('third-party-notices', 'verify-third-party-notices', { label: 'third-party notices' }), pnpmScript('doc-graphs', 'verify-doc-graphs', { label: 'doc graphs' }), pnpmScript('scoped-events', 'verify-scoped-events', { label: 'scoped events' }), pnpmScript('markdown-wrap', 'verify-md-wrap', { label: 'markdown wrap' }), From cc9172415758fe7efdc752b46019fafce88119b9 Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Thu, 30 Jul 2026 23:43:53 +0800 Subject: [PATCH 10/50] Fix invariant startup gate after CI sync --- .github/workflows/ci.yml | 9 +- .../client/connection/tests/node-half.spec.ts | 20 +-- .../runtime/tests/slots-service.spec.ts | 4 +- scripts/test-invariants.spec.ts | 166 +++++++++++++++++- scripts/test-invariants.ts | 61 +++++-- vitest.config.ts | 23 +-- 6 files changed, 235 insertions(+), 48 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1f6ec52f0a..e607d83bdc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -105,11 +105,10 @@ jobs: || 'dsh-ubuntu-24-04-16core' }} name: node 24 / coverage env: - # Failover shrinks the worker bound: the hosted 32-core runner is - # exclusive to one job, but the failover pool shares one 64-core VM - # across six always-on runner instances, and the timing-sensitive - # process suites have documented aggregate-contention failures. - # 8 × 6 instances = 48 workers worst case on 64 cores. + # The hosted 16-core runner uses six coverage workers. The failover pool + # shares one 64-core VM across six always-on runner instances, so each + # instance may use eight while keeping the worst case at 8 × 6 = 48 + # workers; process-bound suites remain isolated in forks. DSH_COVERAGE_MAX_WORKERS: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '8' || '6' }} DSH_GATE_CONCURRENCY: '3' steps: diff --git a/packages/client/connection/tests/node-half.spec.ts b/packages/client/connection/tests/node-half.spec.ts index 2c7fd0b281..9efa9cbd51 100644 --- a/packages/client/connection/tests/node-half.spec.ts +++ b/packages/client/connection/tests/node-half.spec.ts @@ -59,23 +59,9 @@ describe('connection node half', () => { const ctx = new Context() ctx.provide('httpServer', fakeHttpServer(routes) as HttpServerService) ctx.provide('apiProxy', {} as unknown as ApiProxy) - // The apply throw also escapes cordis as a late rejection — the shape the - // boot's installFailLoud is contracted to catch. Capture it so the run - // stays clean, same pattern as the webserver bind-failure test. - const rejections: unknown[] = [] - const onUnhandled = (err: unknown): void => { rejections.push(err) } - process.on('unhandledRejection', onUnhandled) - try { - const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.internal/path'] }) - await expect(fiber.await()).rejects.toThrow(/not a bare host\[:port\] authority/) - expect(routes).toHaveLength(0) - for (let i = 0; i < 100 && rejections.length === 0; i++) { - await new Promise(resolve => setTimeout(resolve, 10)) - } - expect(rejections.map(String).join('\n')).toContain('not a bare host[:port] authority') - } finally { - process.off('unhandledRejection', onUnhandled) - } + const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.internal/path'] }) + await expect(fiber).rejects.toThrow(/not a bare host\[:port\] authority/) + expect(routes).toHaveLength(0) }) it('registers the /api prefix route and removes it with the fiber', async () => { diff --git a/packages/client/runtime/tests/slots-service.spec.ts b/packages/client/runtime/tests/slots-service.spec.ts index 07e03b6e9d..b2e510a26f 100644 --- a/packages/client/runtime/tests/slots-service.spec.ts +++ b/packages/client/runtime/tests/slots-service.spec.ts @@ -41,8 +41,8 @@ interface Bench { async function boot(): Promise { const ctx = new Context() - ctx.plugin(SlotsService) - await ctx.fiber.await() + const fiber = ctx.plugin(SlotsService) + await fiber // Service accessor (ctx.get reads the reflect store, which Service-class // plugins do not write; the accessor is the product path). const svc = ctx.slots diff --git a/scripts/test-invariants.spec.ts b/scripts/test-invariants.spec.ts index 0fb6aeb201..e2406837ca 100644 --- a/scripts/test-invariants.spec.ts +++ b/scripts/test-invariants.spec.ts @@ -1,11 +1,14 @@ import { describe, expect, it, vi } from 'vitest' -import { Context, Service } from 'cordis' +import { Context, FiberState, Service } from 'cordis' import Loader from '@cordisjs/plugin-loader' +import InvariantService from '@deepseek-ai/dsh-invariants' import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants' import { packageInvariantOwners } from './package-invariants.ts' import { + TEST_INVARIANT_READY_SERVICE, testInvariantCompanionPaths, testInvariantCompanions, + type TestInvariantCompanion, usesManualInvariantTree, } from './test-invariants.ts' @@ -21,6 +24,32 @@ class TestInvariantProbe extends Service { } } +function deferred(): { readonly promise: Promise; readonly resolve: () => void } { + let resolve!: () => void + const promise = new Promise((done) => { + resolve = done + }) + return { promise, resolve } +} + +async function withFakeCompanions( + create: (path: string, index: number) => () => Promise, + run: () => Promise, +): Promise { + const mutable = testInvariantCompanions as Record Promise> + const originals = Object.entries(mutable) + for (const [index, [path]] of originals.entries()) { + mutable[path] = create(path, index) + } + try { + await run() + } finally { + for (const [path, load] of originals) { + mutable[path] = load + } + } +} + describe('global test invariant host', () => { it('uses one exhaustive topology to reserve every package name with enabled checks', async () => { const ctx = new Context() @@ -85,4 +114,139 @@ describe('global test invariant host', () => { expect(usesManualInvariantTree('/repo/packages/examples/agent-spine-demo/tests/agent-core.spec.ts')).toBe(true) expect(usesManualInvariantTree('/repo/packages/core/session/tests/session.spec.ts')).toBe(false) }) + + it('holds a root plugin until every lazy companion is active, then permits nested startup', async () => { + const delayedStarted = deferred() + const releaseDelayed = deferred() + const order: string[] = [] + let delayedCompanion: TestInvariantCompanion | undefined + + await withFakeCompanions( + (path, index) => async () => { + const companion: TestInvariantCompanion = { + name: `test-invariant-${index}`, + inject: ['invariants'], + async apply() { + order.push(`companion-start:${path}`) + if (index === 0) { + delayedStarted.resolve() + await releaseDelayed.promise + } + order.push(`companion-active:${path}`) + return () => {} + }, + } + if (index === 0) delayedCompanion = companion + return companion + }, + async () => { + const ctx = new Context() + ctx.provide('testInvariantTargetDependency', true) + let nestedFiber: ReturnType | undefined + const nestedApply = vi.fn(function nestedApply() { + order.push('nested') + }) + const targetApply = Object.assign(vi.fn(function targetApply(targetCtx: Context) { + order.push('target') + nestedFiber = targetCtx.plugin(nestedApply) + }), { + inject: ['testInvariantTargetDependency'], + }) + + const targetFiber = ctx.plugin(targetApply) + expect(ctx.registry.get(targetApply)?.callback).toBe(targetApply) + expect(targetFiber.inject).toEqual({ + testInvariantTargetDependency: null, + [TEST_INVARIANT_READY_SERVICE]: null, + }) + + await delayedStarted.promise + await Promise.resolve() + await Promise.resolve() + expect(targetApply).not.toHaveBeenCalled() + + releaseDelayed.resolve() + await targetFiber + if (nestedFiber === undefined) throw new Error('target did not register its nested plugin') + await nestedFiber + + expect(targetFiber.state).toBe(FiberState.ACTIVE) + expect(targetApply).toHaveBeenCalledOnce() + expect(nestedApply).toHaveBeenCalledOnce() + const targetIndex = order.indexOf('target') + expect(targetIndex).toBeGreaterThan(-1) + expect(order.slice(0, targetIndex)).toHaveLength(Object.keys(testInvariantCompanions).length * 2) + expect(order.at(-1)).toBe('nested') + + if (delayedCompanion === undefined) throw new Error('delayed companion did not load') + await ctx.plugin(InvariantService, { enabled: true }) + await ctx.plugin(delayedCompanion) + expect(ctx.registry.get(InvariantService)?.fibers).toHaveLength(1) + expect(ctx.registry.get(delayedCompanion)?.fibers).toHaveLength(1) + }, + ) + }) + + it.each(['load', 'startup'] as const)( + 'rejects a target when a lazy companion fails during %s without starting the target', + async (phase) => { + const failure = new Error(`test invariant companion ${phase} failed`) + await withFakeCompanions( + (_path, index) => phase === 'load' && index === 0 + ? async () => { throw failure } + : async () => ({ + name: `test-invariant-${index}`, + inject: ['invariants'], + async apply() { + if (phase === 'startup' && index === 0) throw failure + return () => {} + }, + }), + async () => { + const ctx = new Context() + const targetApply = vi.fn(function targetApply() {}) + const targetFiber = ctx.plugin(targetApply) + + await expect(targetFiber).rejects.toBe(failure) + expect(targetApply).not.toHaveBeenCalled() + expect(targetFiber.state).toBe(FiberState.PENDING) + await expect(targetFiber.dispose()).resolves.toBeUndefined() + expect(targetFiber.state).toBe(FiberState.DISPOSED) + }, + ) + }, + ) + + it('disposes a pending target without waiting for companion readiness', async () => { + const delayedStarted = deferred() + const releaseDelayed = deferred() + + await withFakeCompanions( + (_path, index) => async () => ({ + name: `test-invariant-${index}`, + inject: ['invariants'], + async apply() { + if (index === 0) { + delayedStarted.resolve() + await releaseDelayed.promise + } + return () => {} + }, + }), + async () => { + const ctx = new Context() + const targetApply = vi.fn(function targetApply() {}) + const targetFiber = ctx.plugin(targetApply) + + await delayedStarted.promise + await expect(targetFiber.dispose()).resolves.toBeUndefined() + expect(targetFiber.state).toBe(FiberState.DISPOSED) + expect(targetApply).not.toHaveBeenCalled() + + releaseDelayed.resolve() + await targetFiber + expect(targetApply).not.toHaveBeenCalled() + }, + ) + }) }) diff --git a/scripts/test-invariants.ts b/scripts/test-invariants.ts index 62c0102588..00f24e6d2f 100644 --- a/scripts/test-invariants.ts +++ b/scripts/test-invariants.ts @@ -6,7 +6,7 @@ */ import { expect } from 'vitest' -import { RegistryService } from 'cordis' +import { FiberState, Inject, RegistryService } from 'cordis' import type { Context, Plugin } from 'cordis' import InvariantService from '@deepseek-ai/dsh-invariants' @@ -25,6 +25,9 @@ export interface TestInvariantCompanion { apply(ctx: Context): Promise<() => void> } +/** Private service dependency that holds ordinary root plugins until invariant startup completes. */ +export const TEST_INVARIANT_READY_SERVICE = 'testInvariantReady' + /** * Every package companion as a lazy loader keyed by glob path. Ordinary tests * load only their owner's module; the exhaustive topology test loads and @@ -47,6 +50,7 @@ interface InvariantHost { } type PluginFiber = ReturnType +type PluginCallback = Plugin.Function | Plugin.Constructor const hosts = new WeakMap() // oxlint-disable-next-line typescript/unbound-method -- every call below supplies its RegistryService receiver explicitly. @@ -64,10 +68,18 @@ RegistryService.prototype.plugin = function(plugin: Plugin, config?: unknown, ge return this.ctx === root ? joinInvariantStartup(existing, host.ready) : existing } - const fiber = originalPlugin.call(this, plugin, config, getOuterStack) - // A root-level await is the test's composition boundary. Nested plugin - // fibers must not await their own companion parent through the global host. - if (this.ctx !== root) return fiber + // Nested plugins run inside a target that already crossed the root barrier. + // Adding the same root-owned dependency there would make child lifecycle + // depend on an unrelated isolation scope and can deadlock companion startup. + if (this.ctx !== root) return originalPlugin.call(this, plugin, config, getOuterStack) + if (callback === undefined) return originalPlugin.call(this, plugin, config, getOuterStack) + + const fiber = originalPlugin.call( + this, + withInvariantReadiness(plugin, callback as PluginCallback), + config, + getOuterStack, + ) return joinInvariantStartup(fiber, host.ready) } @@ -126,8 +138,8 @@ function startInvariantHost(root: Context): InvariantHost { const serviceFiber = mount(InvariantService, { enabled: true }) const testPath = expect.getState().testPath ?? '' const companionPaths = testInvariantCompanionPaths(testPath) - const ready = serviceFiber.await().then(async () => { - const companionFibers = await Promise.all(companionPaths.map(async (path) => { + const ready = requireActive(serviceFiber, 'invariant service').then(async () => { + const companions = await Promise.all(companionPaths.map(async (path) => { const load = testInvariantCompanions[path] if (load === undefined) { throw new Error(`test invariants: selected companion vanished at ${path}`) @@ -136,20 +148,43 @@ function startInvariantHost(root: Context): InvariantHost { if (!companion.inject.includes('invariants')) { throw new Error(`test invariants: ${path} must inject the invariant service`) } - return mount(companion) + return { companion, path } })) - await Promise.all(companionFibers.map(fiber => fiber.await())) + const companionFibers = companions.map(({ companion, path }) => ({ + fiber: mount(companion), + path, + })) + await Promise.all(companionFibers.map(({ fiber, path }) => requireActive(fiber, path))) + root.provide(TEST_INVARIANT_READY_SERVICE, true) }) const host = { byCallback, ready } hosts.set(root, host) return host } +async function requireActive(fiber: PluginFiber, label: string): Promise { + await fiber.await() + if (fiber.state !== FiberState.ACTIVE) { + throw new Error(`test invariants: ${label} settled without becoming active`) + } +} + +function withInvariantReadiness(plugin: Plugin, callback: PluginCallback): Plugin.Object { + return { + apply: callback as Plugin.Function, + inject: { + ...Inject.resolve(plugin.inject), + [TEST_INVARIANT_READY_SERVICE]: null, + }, + ...(plugin.name === undefined ? {} : { name: plugin.name }), + ...(plugin.Config === undefined ? {} : { Config: plugin.Config }), + ...(plugin.provide === undefined ? {} : { provide: plugin.provide }), + ...(plugin.intercept === undefined ? {} : { intercept: plugin.intercept }), + } +} + function joinInvariantStartup(fiber: PluginFiber, invariantReady: Promise): PluginFiber { - const readiness = fiber.await().then(async (loaded) => { - await invariantReady - return loaded - }) + const readiness = invariantReady.then(() => fiber.await()) const joined = Object.create(fiber) as PluginFiber joined.then = readiness.then.bind(readiness) return joined diff --git a/vitest.config.ts b/vitest.config.ts index aa3e2b441b..0f4aac1e31 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -37,9 +37,9 @@ const testIncludes = [ 'scripts/**/*.spec.ts', ] -// These suites exercise process-global state, process APIs, or timing-sensitive process I/O -// that worker threads cannot isolate reliably under aggregate gate contention. -// Keep the narrow exception in forks while the rest of the inventory avoids per-file processes. +// These suites exercise process-global state, process APIs, or timing-sensitive process I/O. +// Keep them in a separate project so Windows, whose main pool uses threads, +// still contains them in forks; POSIX uses forks for both projects. const processBoundTests = [ 'packages/subprocess/subprocess-local/tests/spawn.spec.ts', 'packages/context/time-context/tests/time-context.spec.ts', @@ -55,8 +55,9 @@ export default defineConfig({ // .tsx: client component specs (jsdom via per-file @vitest-environment pragma). include: testIncludes, exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`), - // One coverage invocation aggregates both projects. Most suites use threads - // for lower startup/IPC overhead; only explicit process-bound suites fork. + // One coverage invocation aggregates both projects. POSIX uses forks to + // contain the Node CJS-lexer abort; Windows keeps threads for the main + // inventory and forks only the explicit process-bound project. projects: [ { plugins: [pathsPlugin()], @@ -156,11 +157,13 @@ export default defineConfig({ 'packages/client/ui-sidebar/src/client/index.ts', 'packages/client/ui-skill/src/client/index.ts', 'packages/client/ui-workspace/src/client/index.ts', - // Typert generator: correctness is pinned by its fixture suites and - // the byte-for-byte catalog reproduction test; per-file coverage - // would put whole-workspace compiler analysis under v8 - // instrumentation — the coverage lane's longest tail. - 'packages/typert/generator/src/*.ts', + // These three whole-workspace Typert passes are pinned by fixture and + // byte-for-byte catalog tests; v8 instrumentation makes them the + // coverage lane's longest tail. The generator's lighter modules and + // future source files retain the 100% per-file threshold. + 'packages/typert/generator/src/analyzer.ts', + 'packages/typert/generator/src/renderer.ts', + 'packages/typert/generator/src/cordis-catalog.ts', 'packages/host/apiproxy/src/index.ts', 'packages/host/apiproxy/src/invariant.ts', 'packages/host/apiproxy/src/api-proxy.ts', From 573a062afd85569f8fa892e78de543750f41a6bd Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Thu, 30 Jul 2026 23:54:21 +0800 Subject: [PATCH 11/50] Gate derived test contexts on invariant readiness --- scripts/test-invariants.spec.ts | 51 ++++++++++++++++++++++++++++++++- scripts/test-invariants.ts | 28 ++++++++++++++---- 2 files changed, 72 insertions(+), 7 deletions(-) diff --git a/scripts/test-invariants.spec.ts b/scripts/test-invariants.spec.ts index e2406837ca..40c93fe9ad 100644 --- a/scripts/test-invariants.spec.ts +++ b/scripts/test-invariants.spec.ts @@ -120,18 +120,20 @@ describe('global test invariant host', () => { const releaseDelayed = deferred() const order: string[] = [] let delayedCompanion: TestInvariantCompanion | undefined + const companionNestedApply = vi.fn(function companionNestedApply() {}) await withFakeCompanions( (path, index) => async () => { const companion: TestInvariantCompanion = { name: `test-invariant-${index}`, inject: ['invariants'], - async apply() { + async apply(companionCtx) { order.push(`companion-start:${path}`) if (index === 0) { delayedStarted.resolve() await releaseDelayed.promise } + if (index === 1) await companionCtx.plugin(companionNestedApply) order.push(`companion-active:${path}`) return () => {} }, @@ -173,6 +175,7 @@ describe('global test invariant host', () => { expect(targetFiber.state).toBe(FiberState.ACTIVE) expect(targetApply).toHaveBeenCalledOnce() expect(nestedApply).toHaveBeenCalledOnce() + expect(companionNestedApply).toHaveBeenCalledOnce() const targetIndex = order.indexOf('target') expect(targetIndex).toBeGreaterThan(-1) expect(order.slice(0, targetIndex)).toHaveLength(Object.keys(testInvariantCompanions).length * 2) @@ -187,6 +190,52 @@ describe('global test invariant host', () => { ) }) + it('holds plugins registered on a root-derived context until companion readiness', async () => { + const delayedStarted = deferred() + const releaseDelayed = deferred() + + await withFakeCompanions( + (_path, index) => async () => ({ + name: `test-invariant-${index}`, + inject: ['invariants'], + async apply() { + if (index === 0) { + delayedStarted.resolve() + await releaseDelayed.promise + } + return () => {} + }, + }), + async () => { + const ctx = new Context() + const rootApply = vi.fn(function rootApply() {}) + const derivedApply = vi.fn(function derivedApply() {}) + const derived = ctx.extend() + .isolate('testInvariantDerived') + .intercept('testInvariantDerived', {}) + + const rootFiber = ctx.plugin(rootApply) + const derivedFiber = derived.plugin(derivedApply) + + await delayedStarted.promise + await Promise.resolve() + await Promise.resolve() + expect(rootApply).not.toHaveBeenCalled() + expect(derivedApply).not.toHaveBeenCalled() + expect(derivedFiber.inject).toEqual({ + [TEST_INVARIANT_READY_SERVICE]: null, + }) + + releaseDelayed.resolve() + await Promise.all([rootFiber, derivedFiber]) + expect(rootFiber.state).toBe(FiberState.ACTIVE) + expect(derivedFiber.state).toBe(FiberState.ACTIVE) + expect(rootApply).toHaveBeenCalledOnce() + expect(derivedApply).toHaveBeenCalledOnce() + }, + ) + }) + it.each(['load', 'startup'] as const)( 'rejects a target when a lazy companion fails during %s without starting the target', async (phase) => { diff --git a/scripts/test-invariants.ts b/scripts/test-invariants.ts index 00f24e6d2f..2ba460a9da 100644 --- a/scripts/test-invariants.ts +++ b/scripts/test-invariants.ts @@ -46,6 +46,7 @@ const MANUAL_INVARIANT_TEST_EXCEPTIONS = [ interface InvariantHost { readonly byCallback: ReadonlyMap + readonly barrierOwners: WeakSet readonly ready: Promise } @@ -65,13 +66,15 @@ RegistryService.prototype.plugin = function(plugin: Plugin, config?: unknown, ge const callback = this.resolve(plugin) const existing = callback === undefined ? undefined : host.byCallback.get(callback) if (existing !== undefined) { - return this.ctx === root ? joinInvariantStartup(existing, host.ready) : existing + return hasBarrierOwner(host, this.ctx) ? existing : joinInvariantStartup(existing, host.ready) } - // Nested plugins run inside a target that already crossed the root barrier. - // Adding the same root-owned dependency there would make child lifecycle - // depend on an unrelated isolation scope and can deadlock companion startup. - if (this.ctx !== root) return originalPlugin.call(this, plugin, config, getOuterStack) + // Causal descendants of a gated target have already crossed the barrier. + // Host service and companion descendants also bypass it so their own startup + // cannot depend on the readiness they are responsible for providing. + if (hasBarrierOwner(host, this.ctx)) { + return originalPlugin.call(this, plugin, config, getOuterStack) + } if (callback === undefined) return originalPlugin.call(this, plugin, config, getOuterStack) const fiber = originalPlugin.call( @@ -80,6 +83,7 @@ RegistryService.prototype.plugin = function(plugin: Plugin, config?: unknown, ge config, getOuterStack, ) + host.barrierOwners.add(fiber.ctx.fiber) return joinInvariantStartup(fiber, host.ready) } @@ -120,11 +124,13 @@ export function testInvariantCompanionPaths(testPath: string): string[] { function startInvariantHost(root: Context): InvariantHost { const byCallback = new Map() + const barrierOwners = new WeakSet() const mount = (plugin: Plugin, config?: unknown): PluginFiber => { const fiber = originalPlugin.call(root.registry, plugin, config) const callback = root.registry.resolve(plugin) if (callback === undefined) throw new Error('test invariants: companion is not a valid Cordis plugin') byCallback.set(callback, fiber) + barrierOwners.add(fiber.ctx.fiber) return fiber } @@ -157,11 +163,21 @@ function startInvariantHost(root: Context): InvariantHost { await Promise.all(companionFibers.map(({ fiber, path }) => requireActive(fiber, path))) root.provide(TEST_INVARIANT_READY_SERVICE, true) }) - const host = { byCallback, ready } + const host = { byCallback, barrierOwners, ready } hosts.set(root, host) return host } +function hasBarrierOwner(host: InvariantHost, ctx: Context): boolean { + let fiber = ctx.fiber + while (true) { + if (host.barrierOwners.has(fiber)) return true + const parent = fiber.parent.fiber + if (parent === fiber) return false + fiber = parent + } +} + async function requireActive(fiber: PluginFiber, label: string): Promise { await fiber.await() if (fiber.state !== FiberState.ACTIVE) { From ed41269e04e706cba15ae463f451a8c657b9bbaf Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Thu, 30 Jul 2026 23:57:58 +0800 Subject: [PATCH 12/50] Keep pending invariant children behind readiness --- scripts/test-invariants.spec.ts | 45 +++++++++++++++++++++++++++++++++ scripts/test-invariants.ts | 7 ++++- 2 files changed, 51 insertions(+), 1 deletion(-) diff --git a/scripts/test-invariants.spec.ts b/scripts/test-invariants.spec.ts index 40c93fe9ad..18c3a7f860 100644 --- a/scripts/test-invariants.spec.ts +++ b/scripts/test-invariants.spec.ts @@ -236,6 +236,51 @@ describe('global test invariant host', () => { ) }) + it('holds a child registered externally on a pending target context', async () => { + const delayedStarted = deferred() + const releaseDelayed = deferred() + + await withFakeCompanions( + (_path, index) => async () => ({ + name: `test-invariant-${index}`, + inject: ['invariants'], + async apply() { + if (index === 0) { + delayedStarted.resolve() + await releaseDelayed.promise + } + return () => {} + }, + }), + async () => { + const ctx = new Context() + const targetApply = vi.fn(function targetApply() {}) + const childApply = vi.fn(function childApply() {}) + + const targetFiber = ctx.plugin(targetApply) + const childFiber = targetFiber.ctx.plugin(childApply) + + await delayedStarted.promise + await Promise.resolve() + await Promise.resolve() + expect(targetFiber.state).toBe(FiberState.PENDING) + expect(childFiber.state).toBe(FiberState.PENDING) + expect(targetApply).not.toHaveBeenCalled() + expect(childApply).not.toHaveBeenCalled() + expect(childFiber.inject).toEqual({ + [TEST_INVARIANT_READY_SERVICE]: null, + }) + + releaseDelayed.resolve() + await Promise.all([targetFiber, childFiber]) + expect(targetFiber.state).toBe(FiberState.ACTIVE) + expect(childFiber.state).toBe(FiberState.ACTIVE) + expect(targetApply).toHaveBeenCalledOnce() + expect(childApply).toHaveBeenCalledOnce() + }, + ) + }) + it.each(['load', 'startup'] as const)( 'rejects a target when a lazy companion fails during %s without starting the target', async (phase) => { diff --git a/scripts/test-invariants.ts b/scripts/test-invariants.ts index 2ba460a9da..8ebf7a6243 100644 --- a/scripts/test-invariants.ts +++ b/scripts/test-invariants.ts @@ -171,7 +171,12 @@ function startInvariantHost(root: Context): InvariantHost { function hasBarrierOwner(host: InvariantHost, ctx: Context): boolean { let fiber = ctx.fiber while (true) { - if (host.barrierOwners.has(fiber)) return true + if ( + host.barrierOwners.has(fiber) + && (fiber.state === FiberState.LOADING || fiber.state === FiberState.ACTIVE) + ) { + return true + } const parent = fiber.parent.fiber if (parent === fiber) return false fiber = parent From 6427660dca8d3c729d97d3701728c9c47d84df52 Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Thu, 30 Jul 2026 09:23:00 -0700 Subject: [PATCH 13/50] docs: fix notices template claim and close generator omission paths The template still described the removed doc-sync gate; it now states the pre-commit + test-lane mechanism that actually runs. Read the nested native/landlock-run/packages manifests, accept PEP 508 requirements with no version or with a marker, and reject a vendor/README.md table that stops covering a vendored directory instead of dropping it silently. Extend the pre-commit glob to the generator and the build-time pin source; record the deletion trigger gap the test lane backstops. --- ...30-generated-third-party-notices.i18n.yaml | 4 +- ...026-07-30-generated-third-party-notices.md | 4 +- ...-07-30-generated-third-party-notices.zh.md | 4 +- THIRD_PARTY_NOTICES.md | 4 +- lefthook.yml | 8 +- scripts/gen-third-party-notices.spec.ts | 27 ++++++- scripts/gen-third-party-notices.ts | 75 ++++++++++++++----- 7 files changed, 98 insertions(+), 28 deletions(-) diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml index d410427440..288517e61e 100644 --- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml +++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.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/process/2026-07-30-generated-third-party-notices.md -2026-07-30-generated-third-party-notices.md: 2a669be4c8dcf92beb08c1305098e1baa7626ef4 -2026-07-30-generated-third-party-notices.zh.md: 990d15238a2939c54b4242016f9986e3f58a260b +2026-07-30-generated-third-party-notices.md: 53d75d1464b4ddd3cab0eeaa291dc6d41da10503 +2026-07-30-generated-third-party-notices.zh.md: b55982d94a6d9d9f9b5f6fb98a36ea1471f5eb6c diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md index 2a669be4c8..53d75d1464 100644 --- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md +++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md @@ -14,7 +14,9 @@ A hand-written inventory answers none of those durably. Roughly a hundred rows o [`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) is generated by [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) from the workspace manifests, `vendor/README.md`, the `pyproject.toml` files, and `pnpm-workspace.yaml`. The root README pair links the file from its License section. -**Freshness is maintained, not merely enforced.** A pre-commit job regenerates the file and stages it whenever a manifest, lock file, `vendor/README.md`, or `pyproject.toml` is staged, so an unrelated dependency edit never has to come back and rerun a generator. The committed bytes are then asserted inside [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts), which the test lane already runs — the check adds no gate process, no scheduler slot, and no separate CI step. `pnpm run verify-third-party-notices` remains available for a standalone check. +**Freshness is maintained, not merely enforced.** A pre-commit job regenerates the file and stages it whenever a generator input is staged — any manifest, either lock file, `vendor/README.md`, a `pyproject.toml`, the generator itself, or the script holding the build-time pin — so an unrelated dependency edit never has to come back and rerun a generator. The committed bytes are then asserted inside [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts), which the test lane already runs — the check adds no gate process, no scheduler slot, and no separate CI step. `pnpm run verify-third-party-notices` remains available for a standalone check. + +One trigger gap is accepted rather than worked around: lefthook inspects only files present on disk, so **deleting** a manifest runs no job, and removing a package reaches the assertion in the test lane instead. Reconstructing the staged file list to include deletions was tried and does not work — lefthook filters the list against the working tree either way. The assertion is the backstop for exactly this case. The file discloses **direct** dependencies only. The complete npm closure with pinned versions already lives in `pnpm-lock.yaml` (`pnpm licenses list` renders it) and the Python closure in `python/sdk/uv.lock`; re-materializing either as prose would be a second, worse copy. diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md index 990d15238a..b55982d94a 100644 --- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md +++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md @@ -14,7 +14,9 @@ Status: implemented [`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) 由 [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) 依据各工作区清单、`vendor/README.md`、`pyproject.toml` 与 `pnpm-workspace.yaml` 生成。根 README 双语两侧都从「许可证」一节链到该文件。 -**新鲜度靠维护而非拦截。** 只要暂存了清单文件、锁文件、`vendor/README.md` 或 `pyproject.toml`，pre-commit 任务就会重新生成并一并入库，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。 +**新鲜度靠维护而非拦截。** 只要暂存了生成器的任一输入——任何清单文件、两个锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成并一并入库，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。 + +有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除**清单文件不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。 文件只披露**直接**依赖。完整的 npm 闭包连同锁定版本已记录在 `pnpm-lock.yaml`（`pnpm licenses list` 可渲染），Python 闭包记录在 `python/sdk/uv.lock`；再用散文誊一遍只会得到一份更差的副本。 diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 651133723d..67e2ebae30 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -5,7 +5,9 @@ DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the third-party open-source software listed below. Each project remains under its own license; nothing in this file changes those terms. -This file lists **direct** dependencies declared by the workspace, generated from the workspace manifests by `scripts/gen-third-party-notices.ts` and verified fresh by `pnpm run verify-third-party-notices` (part of `doc-sync`). The complete npm transitive closure, with exact pinned versions, is recorded in [`pnpm-lock.yaml`](pnpm-lock.yaml) (inspect it with `pnpm licenses list`); the Python closure is recorded in [`python/sdk/uv.lock`](python/sdk/uv.lock). +This file lists **direct** dependencies declared by the workspace. It is generated from the workspace manifests by `scripts/gen-third-party-notices.ts`: a pre-commit hook regenerates it whenever a manifest changes, and `scripts/gen-third-party-notices.spec.ts` asserts in the test lane that the committed bytes match. Run `pnpm run verify-third-party-notices` for the standalone check. + +The complete npm transitive closure, with exact pinned versions, is recorded in [`pnpm-lock.yaml`](pnpm-lock.yaml) — inspect it with `pnpm licenses list`. The Python closure is recorded in [`python/sdk/uv.lock`](python/sdk/uv.lock), and the Landlock launcher workspace keeps its own in [`native/landlock-run/pnpm-lock.yaml`](native/landlock-run/pnpm-lock.yaml). ## Vendored source (`vendor/`) diff --git a/lefthook.yml b/lefthook.yml index b5f9d09fe8..900a6e52bf 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -19,9 +19,13 @@ pre-commit: stage_fixed: true # Regenerate rather than reject: a dependency edit that forgot the notices - # would otherwise fail the test lane long after the commit. + # would otherwise fail the test lane long after the commit. The glob matches + # every input the generator reads, including the generator itself and the + # build-time pin source. Deleting a manifest cannot trigger this job — + # lefthook only inspects files present on disk — so that one case still + # falls through to the freshness assertion in the test lane. - name: third-party notices (staged) - glob: '{package.json,*/package.json,*/*/package.json,*/*/*/package.json,pnpm-workspace.yaml,pnpm-lock.yaml,vendor/README.md,python/*/pyproject.toml}' + glob: '{package.json,*/package.json,*/*/package.json,*/*/*/package.json,pnpm-workspace.yaml,pnpm-lock.yaml,vendor/README.md,python/*/pyproject.toml,scripts/gen-third-party-notices.ts,scripts/build-exe-for-python-sdk.ts}' run: node_modules/.bin/tsx scripts/gen-third-party-notices.ts && git add THIRD_PARTY_NOTICES.md - name: whitespace (staged) diff --git a/scripts/gen-third-party-notices.spec.ts b/scripts/gen-third-party-notices.spec.ts index 9900364bd3..bd2107d044 100644 --- a/scripts/gen-third-party-notices.spec.ts +++ b/scripts/gen-third-party-notices.spec.ts @@ -1,7 +1,7 @@ -import { readFileSync } from 'node:fs' +import { readdirSync, readFileSync } from 'node:fs' import { resolve } from 'node:path' import { describe, expect, it } from 'vitest' -import { type Manifest, parseVendoredRows, render, tierExternalDeps } from './gen-third-party-notices.ts' +import { type Manifest, parsePythonRequirements, parseVendoredRows, render, tierExternalDeps } from './gen-third-party-notices.ts' const root = resolve(import.meta.dirname, '..') @@ -76,4 +76,27 @@ describe('parseVendoredRows', () => { it('yields nothing when the table shape changes, so the generator fails loud', () => { expect(parseVendoredRows('| `cordis/` | cordis | 4.0.0 | https://example.com | `abc123` |\n')).toEqual([]) }) + + it('covers every vendored directory, so no package can drop out of the notices', () => { + const parsed = new Set(parseVendoredRows(readFileSync(resolve(root, 'vendor/README.md'), 'utf8')).map(row => row.npmName)) + const onDisk = readdirSync(resolve(root, 'vendor'), { withFileTypes: true }) + .filter(entry => entry.isDirectory()) + .map(entry => (JSON.parse(readFileSync(resolve(root, 'vendor', entry.name, 'package.json'), 'utf8')) as Manifest).name) + + expect([...onDisk].sort()).toEqual([...parsed].sort()) + }) +}) + +describe('parsePythonRequirements', () => { + it('reads names whether or not the requirement carries a version, extras, or a marker', () => { + expect(parsePythonRequirements('"pydantic>=2.12", "requests", "httpx[http2]", "tomli ; python_version < \'3.11\'", "hatchling >= 1.24.0"')) + .toEqual(['pydantic', 'requests', 'httpx', 'tomli', 'hatchling']) + }) + + it('reads the committed manifests', () => { + const text = readFileSync(resolve(root, 'python/sdk/pyproject.toml'), 'utf8') + const block = /dependencies\s*=\s*\[([^\]]*)\]/.exec(text)?.[1] ?? '' + + expect(parsePythonRequirements(block)).toContain('pydantic') + }) }) diff --git a/scripts/gen-third-party-notices.ts b/scripts/gen-third-party-notices.ts index 243ed2d3ad..a33f0671fd 100644 --- a/scripts/gen-third-party-notices.ts +++ b/scripts/gen-third-party-notices.ts @@ -41,7 +41,11 @@ const DEV_ONLY_AREAS = [ * First-party packages released from sibling repositories under the project's * own license: reachable from workspace manifests but not third-party. */ -const FIRST_PARTY = new Set(['node-addon-landlock-run']) +const FIRST_PARTY = new Set([ + 'node-addon-landlock-run', + 'node-addon-landlock-run-linux-arm64', + 'node-addon-landlock-run-linux-x64', +]) /** * Metadata overrides where the installed manifest is wrong or unreachable. @@ -108,7 +112,9 @@ function readManifest(rel: string): Manifest { /** Every workspace manifest, keyed by path, plus the set of workspace package names. */ function loadWorkspaceManifests(): { manifests: Map; names: Set } { - const patterns = ['package.json', 'vendor/*/package.json', 'packages/*/*/package.json', 'apps/*/package.json', 'website/package.json', 'examples/package.json', 'python/sdk-runtime/package.json', 'native/landlock-run/package.json', 'native/landlock-run/*/package.json'] + // `native/landlock-run` is a nested workspace with its own lock file; its + // leaf manifests live one level deeper than this repository's own tiers. + const patterns = ['package.json', 'vendor/*/package.json', 'packages/*/*/package.json', 'apps/*/package.json', 'website/package.json', 'examples/package.json', 'python/sdk-runtime/package.json', 'native/landlock-run/package.json', 'native/landlock-run/packages/*/package.json'] const manifests = new Map() const names = new Set() for (const pattern of patterns) { @@ -219,27 +225,51 @@ export function parseVendoredRows(text: string): VendoredRow[] { return rows } -/** Parse the vendored manifest table and confirm every vendored package is MIT. */ +/** + * Parse the vendored manifest table and confirm it accounts for every vendored + * directory. The `vendor/` tree — not the table — is the set that must be + * disclosed, so a row that stops matching the table format is a hard error + * rather than a package that quietly vanishes from the notices. + */ function collectVendored(): VendoredRow[] { const rows = parseVendoredRows(readFileSync(resolve(root, 'vendor/README.md'), 'utf8')) - if (rows.length === 0) throw new Error('gen-third-party-notices: no vendored rows parsed from vendor/README.md; its table format changed.') + const onDisk = new Map() + for (const entry of readdirSync(resolve(root, 'vendor'), { withFileTypes: true })) { + if (!entry.isDirectory()) continue + const manifest = readManifest(`vendor/${entry.name}/package.json`) + if (manifest.name !== undefined) onDisk.set(manifest.name, entry.name) + } + + const parsed = new Set(rows.map(row => row.npmName)) + const missing = [...onDisk.keys()].filter(name => !parsed.has(name)) + if (missing.length > 0) { + throw new Error(`gen-third-party-notices: vendor/README.md has no manifest-table row for ${missing.join(', ')}; its table format changed or the sync is incomplete.`) + } for (const row of rows) { - const manifest = readManifest(`vendor/${vendorDir(row.npmName)}/package.json`) - if (manifest.license !== 'MIT') { - throw new Error(`gen-third-party-notices: vendored ${row.npmName} declares license ${JSON.stringify(manifest.license)}; the vendored section assumes MIT throughout.`) + const dir = onDisk.get(row.npmName) + if (dir === undefined) throw new Error(`gen-third-party-notices: vendored package ${row.npmName} from vendor/README.md has no vendor/ directory.`) + const license = readManifest(`vendor/${dir}/package.json`).license + if (license !== 'MIT') { + throw new Error(`gen-third-party-notices: vendored ${row.npmName} declares license ${JSON.stringify(license)}; the vendored section assumes MIT throughout.`) } } return rows } -/** The vendor/ directory of a vendored npm name (manifest table order is authoritative for names). */ -function vendorDir(npmName: string): string { - const dirs = readdirSync(resolve(root, 'vendor'), { withFileTypes: true }).filter(entry => entry.isDirectory()).map(entry => entry.name) - for (const dir of dirs) { - const manifest = readManifest(`vendor/${dir}/package.json`) - if (manifest.name === npmName) return dir +/** + * Extract the distribution names from one `pyproject.toml` requirement array. + * PEP 508 makes every part after the name optional, so a bare `"requests"` and + * a marker-only `"requests; python_version < '3.11'"` must both be found. + * @param block - the bracketed array text of a requirement list. + * @returns each requirement's distribution name, in file order. + */ +export function parsePythonRequirements(block: string): string[] { + const names: string[] = [] + for (const match of block.matchAll(/"\s*([a-zA-Z][a-zA-Z0-9._-]*)\s*(?:\[[^\]]*\])?\s*(?:[<>=!~;@].*?)?"/g)) { + const name = match[1] + if (name !== undefined) names.push(name) } - throw new Error(`gen-third-party-notices: vendored package ${npmName} from vendor/README.md has no vendor/ directory.`) + return names } /** Direct Python dependencies named by the `pyproject.toml` manifests under `python/`. */ @@ -247,10 +277,15 @@ function collectPython(): { name: string; license: string; repo: string; role: s const found = new Set() for (const path of ['python/sdk/pyproject.toml', 'python/sdk-runtime/pyproject.toml']) { const text = readFileSync(resolve(root, path), 'utf8') - for (const match of text.matchAll(/"([a-zA-Z][a-zA-Z0-9._-]*)\s*(?:>=|==|~=|<|>|\[)/g)) { - const name = match[1] - if (name === undefined || name.startsWith('deepseek')) continue - found.add(name) + // Requirement arrays only: `[project] name`/`readme` and `[tool.*]` string + // values would otherwise read as dependencies. + for (const block of text.matchAll(/(?:^|\n)\s*(?:requires|dependencies|test|dev|lint)\s*=\s*\[([^\]]*)\]/g)) { + const body = block[1] + if (body === undefined) continue + for (const name of parsePythonRequirements(body)) { + if (name.startsWith('deepseek')) continue + found.add(name) + } } } return [...found].sort((a, b) => a.localeCompare(b)).map((name) => { @@ -306,7 +341,9 @@ export function render(): string { DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the third-party open-source software listed below. Each project remains under its own license; nothing in this file changes those terms. -This file lists **direct** dependencies declared by the workspace, generated from the workspace manifests by \`scripts/gen-third-party-notices.ts\` and verified fresh by \`pnpm run verify-third-party-notices\` (part of \`doc-sync\`). The complete npm transitive closure, with exact pinned versions, is recorded in [\`pnpm-lock.yaml\`](pnpm-lock.yaml) (inspect it with \`pnpm licenses list\`); the Python closure is recorded in [\`python/sdk/uv.lock\`](python/sdk/uv.lock). +This file lists **direct** dependencies declared by the workspace. It is generated from the workspace manifests by \`scripts/gen-third-party-notices.ts\`: a pre-commit hook regenerates it whenever a manifest changes, and \`scripts/gen-third-party-notices.spec.ts\` asserts in the test lane that the committed bytes match. Run \`pnpm run verify-third-party-notices\` for the standalone check. + +The complete npm transitive closure, with exact pinned versions, is recorded in [\`pnpm-lock.yaml\`](pnpm-lock.yaml) — inspect it with \`pnpm licenses list\`. The Python closure is recorded in [\`python/sdk/uv.lock\`](python/sdk/uv.lock), and the Landlock launcher workspace keeps its own in [\`native/landlock-run/pnpm-lock.yaml\`](native/landlock-run/pnpm-lock.yaml). ## Vendored source (\`vendor/\`) From 096fe8b6d7f13794e41ef70a9b3e2f090cebd68e Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Fri, 31 Jul 2026 00:41:48 +0800 Subject: [PATCH 14/50] Deduplicate invariant barrier fixtures --- scripts/test-invariants.spec.ts | 87 +++++++++++++-------------------- 1 file changed, 33 insertions(+), 54 deletions(-) diff --git a/scripts/test-invariants.spec.ts b/scripts/test-invariants.spec.ts index 18c3a7f860..edea360095 100644 --- a/scripts/test-invariants.spec.ts +++ b/scripts/test-invariants.spec.ts @@ -50,6 +50,27 @@ async function withFakeCompanions( } } +async function withDelayedFirstCompanion( + run: (control: { readonly started: Promise; readonly release: () => void }) => Promise, +): Promise { + const started = deferred() + const release = deferred() + await withFakeCompanions( + (_path, index) => async () => ({ + name: `test-invariant-${index}`, + inject: ['invariants'], + async apply() { + if (index === 0) { + started.resolve() + await release.promise + } + return () => {} + }, + }), + () => run({ started: started.promise, release: release.resolve }), + ) +} + describe('global test invariant host', () => { it('uses one exhaustive topology to reserve every package name with enabled checks', async () => { const ctx = new Context() @@ -191,22 +212,8 @@ describe('global test invariant host', () => { }) it('holds plugins registered on a root-derived context until companion readiness', async () => { - const delayedStarted = deferred() - const releaseDelayed = deferred() - - await withFakeCompanions( - (_path, index) => async () => ({ - name: `test-invariant-${index}`, - inject: ['invariants'], - async apply() { - if (index === 0) { - delayedStarted.resolve() - await releaseDelayed.promise - } - return () => {} - }, - }), - async () => { + await withDelayedFirstCompanion( + async ({ started, release }) => { const ctx = new Context() const rootApply = vi.fn(function rootApply() {}) const derivedApply = vi.fn(function derivedApply() {}) @@ -217,7 +224,7 @@ describe('global test invariant host', () => { const rootFiber = ctx.plugin(rootApply) const derivedFiber = derived.plugin(derivedApply) - await delayedStarted.promise + await started await Promise.resolve() await Promise.resolve() expect(rootApply).not.toHaveBeenCalled() @@ -226,7 +233,7 @@ describe('global test invariant host', () => { [TEST_INVARIANT_READY_SERVICE]: null, }) - releaseDelayed.resolve() + release() await Promise.all([rootFiber, derivedFiber]) expect(rootFiber.state).toBe(FiberState.ACTIVE) expect(derivedFiber.state).toBe(FiberState.ACTIVE) @@ -237,22 +244,8 @@ describe('global test invariant host', () => { }) it('holds a child registered externally on a pending target context', async () => { - const delayedStarted = deferred() - const releaseDelayed = deferred() - - await withFakeCompanions( - (_path, index) => async () => ({ - name: `test-invariant-${index}`, - inject: ['invariants'], - async apply() { - if (index === 0) { - delayedStarted.resolve() - await releaseDelayed.promise - } - return () => {} - }, - }), - async () => { + await withDelayedFirstCompanion( + async ({ started, release }) => { const ctx = new Context() const targetApply = vi.fn(function targetApply() {}) const childApply = vi.fn(function childApply() {}) @@ -260,7 +253,7 @@ describe('global test invariant host', () => { const targetFiber = ctx.plugin(targetApply) const childFiber = targetFiber.ctx.plugin(childApply) - await delayedStarted.promise + await started await Promise.resolve() await Promise.resolve() expect(targetFiber.state).toBe(FiberState.PENDING) @@ -271,7 +264,7 @@ describe('global test invariant host', () => { [TEST_INVARIANT_READY_SERVICE]: null, }) - releaseDelayed.resolve() + release() await Promise.all([targetFiber, childFiber]) expect(targetFiber.state).toBe(FiberState.ACTIVE) expect(childFiber.state).toBe(FiberState.ACTIVE) @@ -312,32 +305,18 @@ describe('global test invariant host', () => { ) it('disposes a pending target without waiting for companion readiness', async () => { - const delayedStarted = deferred() - const releaseDelayed = deferred() - - await withFakeCompanions( - (_path, index) => async () => ({ - name: `test-invariant-${index}`, - inject: ['invariants'], - async apply() { - if (index === 0) { - delayedStarted.resolve() - await releaseDelayed.promise - } - return () => {} - }, - }), - async () => { + await withDelayedFirstCompanion( + async ({ started, release }) => { const ctx = new Context() const targetApply = vi.fn(function targetApply() {}) const targetFiber = ctx.plugin(targetApply) - await delayedStarted.promise + await started await expect(targetFiber.dispose()).resolves.toBeUndefined() expect(targetFiber.state).toBe(FiberState.DISPOSED) expect(targetApply).not.toHaveBeenCalled() - releaseDelayed.resolve() + release() await targetFiber expect(targetApply).not.toHaveBeenCalled() }, From ed5a82f93072da451f4d187fcaf61a9aed8476b8 Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Fri, 31 Jul 2026 01:04:21 +0800 Subject: [PATCH 15/50] Fix invariant config validation readiness --- scripts/test-invariants.spec.ts | 32 +++++++++++++++++++++++++++++++- scripts/test-invariants.ts | 23 +++++++++++++++++++---- 2 files changed, 50 insertions(+), 5 deletions(-) diff --git a/scripts/test-invariants.spec.ts b/scripts/test-invariants.spec.ts index edea360095..d2582d3c68 100644 --- a/scripts/test-invariants.spec.ts +++ b/scripts/test-invariants.spec.ts @@ -1,6 +1,7 @@ import { describe, expect, it, vi } from 'vitest' -import { Context, FiberState, Service } from 'cordis' +import { Context, FiberState, Service, ValidationError } from 'cordis' import Loader from '@cordisjs/plugin-loader' +import z from 'schemastery' import InvariantService from '@deepseek-ai/dsh-invariants' import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants' import { packageInvariantOwners } from './package-invariants.ts' @@ -136,6 +137,35 @@ describe('global test invariant host', () => { expect(usesManualInvariantTree('/repo/packages/core/session/tests/session.spec.ts')).toBe(false) }) + it('preserves config validation failures without starting the rejected plugin', async () => { + const ctx = new Context() + const apply = vi.fn(function invalidConfigApply() { + throw new Error('invalid plugin apply executed') + }) + const plugin = { + apply, + Config: z.object({ + requiredValue: z.string().required(), + }), + } + + const fiber = ctx.plugin(plugin, {}) + const firstError: unknown = await fiber.then( + () => undefined, + (error: unknown) => error, + ) + expect(firstError).toBeInstanceOf(ValidationError) + expect(firstError).toHaveProperty('message', expect.stringMatching(/requiredValue/)) + await ctx.plugin(TestInvariantProbe) + const secondError: unknown = await fiber.then( + () => undefined, + (error: unknown) => error, + ) + expect(secondError).toBe(firstError) + expect(fiber.state).toBe(FiberState.DISPOSED) + expect(apply).not.toHaveBeenCalled() + }) + it('holds a root plugin until every lazy companion is active, then permits nested startup', async () => { const delayedStarted = deferred() const releaseDelayed = deferred() diff --git a/scripts/test-invariants.ts b/scripts/test-invariants.ts index 8ebf7a6243..a0fc6f295e 100644 --- a/scripts/test-invariants.ts +++ b/scripts/test-invariants.ts @@ -75,7 +75,9 @@ RegistryService.prototype.plugin = function(plugin: Plugin, config?: unknown, ge if (hasBarrierOwner(host, this.ctx)) { return originalPlugin.call(this, plugin, config, getOuterStack) } - if (callback === undefined) return originalPlugin.call(this, plugin, config, getOuterStack) + if (callback === undefined) { + return originalPlugin.call(this, plugin, config, getOuterStack) + } const fiber = originalPlugin.call( this, @@ -84,7 +86,7 @@ RegistryService.prototype.plugin = function(plugin: Plugin, config?: unknown, ge getOuterStack, ) host.barrierOwners.add(fiber.ctx.fiber) - return joinInvariantStartup(fiber, host.ready) + return joinInvariantStartup(fiber, host.ready, true) } /** @@ -204,8 +206,21 @@ function withInvariantReadiness(plugin: Plugin, callback: PluginCallback): Plugi } } -function joinInvariantStartup(fiber: PluginFiber, invariantReady: Promise): PluginFiber { - const readiness = invariantReady.then(() => fiber.await()) +function joinInvariantStartup( + fiber: PluginFiber, + invariantReady: Promise, + disposePendingFailure = false, +): PluginFiber { + const initialized = disposePendingFailure + ? fiber.await().catch(async (error: unknown) => { + // Config validation is the only failure recorded while a gated fiber + // is still PENDING. Dispose it before readiness publication can + // refresh the rejected fiber with its uninitialized config. + if (fiber.state === FiberState.PENDING) await fiber.dispose() + throw error + }) + : Promise.resolve() + const readiness = initialized.then(() => invariantReady).then(() => fiber.await()) const joined = Object.create(fiber) as PluginFiber joined.then = readiness.then.bind(readiness) return joined From 9853e74d0e2111f621430757ca1778d5d6ec7a13 Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Fri, 31 Jul 2026 01:18:10 +0800 Subject: [PATCH 16/50] Close invariant readiness validation race --- scripts/test-invariants.spec.ts | 82 ++++++++++++++++++++++++++------- scripts/test-invariants.ts | 13 +++--- 2 files changed, 73 insertions(+), 22 deletions(-) diff --git a/scripts/test-invariants.spec.ts b/scripts/test-invariants.spec.ts index d2582d3c68..b119f9657b 100644 --- a/scripts/test-invariants.spec.ts +++ b/scripts/test-invariants.spec.ts @@ -33,6 +33,28 @@ function deferred(): { readonly promise: Promise; readonly resolve: () => return { promise, resolve } } +function requiredConfig() { + return z.object({ + requiredValue: z.string().required(), + }) +} + +function invalidConfigApply(): never { + throw new Error('invalid plugin apply executed') +} + +async function rejectionOf(fiber: ReturnType): Promise { + return fiber.then( + () => undefined, + (error: unknown) => error, + ) +} + +function expectRequiredConfigValidation(error: unknown): void { + expect(error).toBeInstanceOf(ValidationError) + expect(error).toHaveProperty('message', expect.stringMatching(/requiredValue/)) +} + async function withFakeCompanions( create: (path: string, index: number) => () => Promise, run: () => Promise, @@ -139,33 +161,61 @@ describe('global test invariant host', () => { it('preserves config validation failures without starting the rejected plugin', async () => { const ctx = new Context() - const apply = vi.fn(function invalidConfigApply() { - throw new Error('invalid plugin apply executed') - }) + const apply = vi.fn(invalidConfigApply) const plugin = { apply, - Config: z.object({ - requiredValue: z.string().required(), - }), + Config: requiredConfig(), } const fiber = ctx.plugin(plugin, {}) - const firstError: unknown = await fiber.then( - () => undefined, - (error: unknown) => error, - ) - expect(firstError).toBeInstanceOf(ValidationError) - expect(firstError).toHaveProperty('message', expect.stringMatching(/requiredValue/)) + const firstError = await rejectionOf(fiber) + expectRequiredConfigValidation(firstError) await ctx.plugin(TestInvariantProbe) - const secondError: unknown = await fiber.then( - () => undefined, - (error: unknown) => error, - ) + const secondError = await rejectionOf(fiber) expect(secondError).toBe(firstError) expect(fiber.state).toBe(FiberState.DISPOSED) expect(apply).not.toHaveBeenCalled() }) + it('disposes invalid config when readiness refresh wins the rejection-handler race', async () => { + await withDelayedFirstCompanion( + async ({ started, release }) => { + const ctx = new Context() + const apply = vi.fn(invalidConfigApply) + let disposeQueuedReadiness: (() => void) | undefined + const plugin = { + apply, + Config: z.intersect([ + z.transform(z.any(), () => { + queueMicrotask(() => { + disposeQueuedReadiness = ctx.provide(TEST_INVARIANT_READY_SERVICE, true) + }) + return {} + }, true), + requiredConfig(), + ]), + } + + const fiber = ctx.plugin(plugin, {}) + const firstError = await rejectionOf(fiber) + expectRequiredConfigValidation(firstError) + expect(fiber.state).toBe(FiberState.DISPOSED) + expect(apply).not.toHaveBeenCalled() + + await started + if (disposeQueuedReadiness === undefined) throw new Error('queued readiness was not published') + disposeQueuedReadiness() + release() + await ctx.plugin(TestInvariantProbe) + + const secondError = await rejectionOf(fiber) + expect(secondError).toBe(firstError) + expect(fiber.state).toBe(FiberState.DISPOSED) + expect(apply).not.toHaveBeenCalled() + }, + ) + }) + it('holds a root plugin until every lazy companion is active, then permits nested startup', async () => { const delayedStarted = deferred() const releaseDelayed = deferred() diff --git a/scripts/test-invariants.ts b/scripts/test-invariants.ts index a0fc6f295e..649e680cc2 100644 --- a/scripts/test-invariants.ts +++ b/scripts/test-invariants.ts @@ -85,8 +85,9 @@ RegistryService.prototype.plugin = function(plugin: Plugin, config?: unknown, ge config, getOuterStack, ) + const initiallyPending = fiber.state === FiberState.PENDING host.barrierOwners.add(fiber.ctx.fiber) - return joinInvariantStartup(fiber, host.ready, true) + return joinInvariantStartup(fiber, host.ready, initiallyPending) } /** @@ -209,14 +210,14 @@ function withInvariantReadiness(plugin: Plugin, callback: PluginCallback): Plugi function joinInvariantStartup( fiber: PluginFiber, invariantReady: Promise, - disposePendingFailure = false, + disposeInitialFailure = false, ): PluginFiber { - const initialized = disposePendingFailure + const initialized = disposeInitialFailure ? fiber.await().catch(async (error: unknown) => { // Config validation is the only failure recorded while a gated fiber - // is still PENDING. Dispose it before readiness publication can - // refresh the rejected fiber with its uninitialized config. - if (fiber.state === FiberState.PENDING) await fiber.dispose() + // is initially PENDING. Dispose it even if queued readiness publication + // changes its state before this rejection handler runs. + await fiber.dispose() throw error }) : Promise.resolve() From 44bd19056c808722d59d64f5a2d1e6649d08dc80 Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Thu, 30 Jul 2026 10:28:16 -0700 Subject: [PATCH 17/50] docs: close the remaining silent-omission paths in the notices generator Derive the manifest set from each pnpm-workspace.yaml members list, so a new member area is read when declared. Locate Python requirement arrays by TOML table and scan them quote-aware, so author-named dependency groups and extras-bearing requirements are no longer dropped. Search the nested Landlock store for metadata, reject a non-permissive runtime license outright, and omit the dev-tooling sentence when it has no subject. --- ...30-generated-third-party-notices.i18n.yaml | 4 +- ...026-07-30-generated-third-party-notices.md | 6 +- ...-07-30-generated-third-party-notices.zh.md | 6 +- THIRD_PARTY_NOTICES.md | 1 + lefthook.yml | 2 +- scripts/gen-third-party-notices.spec.ts | 60 ++++++- scripts/gen-third-party-notices.ts | 163 +++++++++++++++--- 7 files changed, 205 insertions(+), 37 deletions(-) diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml index 288517e61e..d65dae2802 100644 --- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml +++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.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/process/2026-07-30-generated-third-party-notices.md -2026-07-30-generated-third-party-notices.md: 53d75d1464b4ddd3cab0eeaa291dc6d41da10503 -2026-07-30-generated-third-party-notices.zh.md: b55982d94a6d9d9f9b5f6fb98a36ea1471f5eb6c +2026-07-30-generated-third-party-notices.md: e480954d29d5dc09ef8ecd4069059a1f0c8b1043 +2026-07-30-generated-third-party-notices.zh.md: 78ba7250e797c57048078d1b4f62b7a9a5d9d561 diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md index 53d75d1464..e480954d29 100644 --- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md +++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md @@ -14,7 +14,7 @@ A hand-written inventory answers none of those durably. Roughly a hundred rows o [`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) is generated by [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) from the workspace manifests, `vendor/README.md`, the `pyproject.toml` files, and `pnpm-workspace.yaml`. The root README pair links the file from its License section. -**Freshness is maintained, not merely enforced.** A pre-commit job regenerates the file and stages it whenever a generator input is staged — any manifest, either lock file, `vendor/README.md`, a `pyproject.toml`, the generator itself, or the script holding the build-time pin — so an unrelated dependency edit never has to come back and rerun a generator. The committed bytes are then asserted inside [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts), which the test lane already runs — the check adds no gate process, no scheduler slot, and no separate CI step. `pnpm run verify-third-party-notices` remains available for a standalone check. +**Freshness is maintained, not merely enforced.** A pre-commit job regenerates the file and stages it whenever a generator input is staged — any manifest, a workspace declaration, the root lock file, `vendor/README.md`, a `pyproject.toml`, the generator itself, or the script holding the build-time pin — so an unrelated dependency edit never has to come back and rerun a generator. The committed bytes are then asserted inside [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts), which the test lane already runs — the check adds no gate process, no scheduler slot, and no separate CI step. `pnpm run verify-third-party-notices` remains available for a standalone check. One trigger gap is accepted rather than worked around: lefthook inspects only files present on disk, so **deleting** a manifest runs no job, and removing a package reaches the assertion in the test lane instead. Reconstructing the staged file list to include deletions was tried and does not work — lefthook filters the list against the working tree either way. The assertion is the backstop for exactly this case. @@ -24,11 +24,11 @@ The file discloses **direct** dependencies only. The complete npm closure with p The runtime tier deliberately covers **every mountable plugin**, not just what the CLI, Web UI, and Python runtime load by default. `scripts/install.sh` installs the repository itself, so a user's `cordis.yml` can mount any plugin package; `@modelcontextprotocol/sdk` and the OpenTelemetry packages reach real users even though no default assembly imports them. Under-disclosure is the costly direction for a legal notice. -License and repository metadata come from the installed pnpm store, so the generator requires an installed tree and fails loud when a package resolves to neither, rather than emitting an empty cell. `OVERRIDES` carries the packages whose published manifest cannot answer — Rust-built npm bins that omit `license`, and the `modelcontextprotocol/servers` packages whose repository is mid MIT→Apache-2.0 relicensing, so their effective terms are per-contribution. Vendored packages are cross-checked against `vendor/README.md` and rejected if any is not MIT, and `pnpm-workspace.yaml`'s `patchedDependencies` are listed under the runtime table because pnpm applies those patches at install time — shipped artifacts carry modified copies of `@earendil-works/pi-tui` and `node-pty`, and the patch files are the record of what changed. +The manifest set is derived from the `packages:` members each `pnpm-workspace.yaml` declares — the root one and the nested Landlock workspace's — so a new member area is read the day it is declared rather than the day someone remembers to extend a list. License and repository metadata come from the installed pnpm stores, both the root one and the Landlock workspace's, so the generator requires an installed tree and fails loud when a package resolves to neither, rather than emitting an empty cell. `OVERRIDES` carries the packages whose published manifest cannot answer — Rust-built npm bins that omit `license`, and the `modelcontextprotocol/servers` packages whose repository is mid MIT→Apache-2.0 relicensing, so their effective terms are per-contribution. A runtime dependency whose license is not on the permissive list is a hard error: shipping copyleft is a distribution decision, not something a regenerated table may absorb silently. Vendored packages are cross-checked against `vendor/README.md` and rejected if any is not MIT, and `pnpm-workspace.yaml`'s `patchedDependencies` are listed under the runtime table because pnpm applies those patches at install time — shipped artifacts carry modified copies of `@earendil-works/pi-tui` and `node-pty`, and the patch files are the record of what changed. ## Testing -The same spec that asserts freshness pins the tiering rule against fixture manifests — including the two cases that motivate it, a `dependencies` entry of a test-support package and a plugin package no app mounts — and pins that the vendored-table parser reads the committed manifest and yields nothing when the table shape changes, which is what makes the generator fail loud rather than emit an empty section. +The same spec that asserts freshness pins the tiering rule against fixture manifests — including the two cases that motivate it, a `dependencies` entry of a test-support package and a plugin package no app mounts. It also pins the parsers against the shapes that would otherwise drop a package without a word: a `vendor/README.md` table that stops covering a vendored directory, a requirement array holding extras (`"httpx[http2]"`), a requirement with no version at all, an author-named `[dependency-groups]` table, and a workspace member area absent from any hardcoded list. Each of those is a silent-omission path, which is the failure mode a disclosure file cannot afford. ## Alternatives considered diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md index b55982d94a..78ba7250e7 100644 --- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md +++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md @@ -14,7 +14,7 @@ Status: implemented [`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) 由 [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) 依据各工作区清单、`vendor/README.md`、`pyproject.toml` 与 `pnpm-workspace.yaml` 生成。根 README 双语两侧都从「许可证」一节链到该文件。 -**新鲜度靠维护而非拦截。** 只要暂存了生成器的任一输入——任何清单文件、两个锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成并一并入库，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。 +**新鲜度靠维护而非拦截。** 只要暂存了生成器的任一输入——任何清单文件、工作区声明、根锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成并一并入库，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。 有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除**清单文件不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。 @@ -24,11 +24,11 @@ Status: implemented 运行时层刻意覆盖**所有可挂载的插件**，而不止 CLI、Web UI 与 Python 运行时默认加载的那些。`scripts/install.sh` 安装的就是仓库本身，用户的 `cordis.yml` 可以挂载任何插件包；`@modelcontextprotocol/sdk` 与 OpenTelemetry 系列即使没有任何默认装配引入，也会触达真实用户。对法务披露而言，披露不足才是代价更高的那个方向。 -许可证与仓库地址取自已安装的 pnpm store，因此生成器要求工作树已安装依赖；某个包两处都解析不到时直接失败，而不是留下空单元格。`OVERRIDES` 收录已发布清单答不上来的包：用 Rust 构建、发布时省略 `license` 字段的 npm 可执行包，以及 `modelcontextprotocol/servers` 系列——该仓库正处在 MIT 向 Apache-2.0 的重新许可过程中，实际条款按贡献逐条而定。被源码收编的包会与 `vendor/README.md` 交叉核对，出现非 MIT 即报错；`pnpm-workspace.yaml` 的 `patchedDependencies` 列在运行时表格之后，因为 pnpm 在安装期就会打上这些补丁——交付产物携带的是改动过的 `@earendil-works/pi-tui` 与 `node-pty`，补丁文件本身就是改动的完整记录。 +清单集合由两个 `pnpm-workspace.yaml`——根工作区与嵌套的 Landlock 工作区——各自声明的 `packages:` 成员派生，因此新增成员区域在声明当天就会被读取，而不必等谁想起来去补一份列表。许可证与仓库地址取自已安装的 pnpm store，根 store 与 Landlock 工作区的 store 都会查；某个包两处都解析不到时直接失败，而不是留下空单元格。`OVERRIDES` 收录已发布清单答不上来的包：用 Rust 构建、发布时省略 `license` 字段的 npm 可执行包，以及 `modelcontextprotocol/servers` 系列——该仓库正处在 MIT 向 Apache-2.0 的重新许可过程中，实际条款按贡献逐条而定。运行时依赖的许可证若不在宽松清单内即为硬失败：交付 copyleft 是一项分发决策，不该被一次重新生成悄悄吸收。被源码收编的包会与 `vendor/README.md` 交叉核对，出现非 MIT 即报错；`pnpm-workspace.yaml` 的 `patchedDependencies` 列在运行时表格之后，因为 pnpm 在安装期就会打上这些补丁——交付产物携带的是改动过的 `@earendil-works/pi-tui` 与 `node-pty`，补丁文件本身就是改动的完整记录。 ## Testing -断言新鲜度的同一个 spec 也用夹具清单钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它同时钉住被收编包的表格解析器能读出已提交的清单表，且表格形态一变就解析为空——正是这一点让生成器直接失败，而不是产出一个空章节。 +断言新鲜度的同一个 spec 也用夹具清单钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它还把各解析器钉在那些原本会让某个包无声消失的形态上：不再覆盖全部收编目录的 `vendor/README.md` 表、含 extras 的依赖数组（`"httpx[http2]"`）、完全不带版本的依赖、作者自取名字的 `[dependency-groups]` 表，以及任何硬编码列表都不含的工作区成员区域。这些都是静默漏报路径——正是披露文件最担不起的失败方式。 ## Alternatives considered diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 67e2ebae30..1b2bdbfe63 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -139,6 +139,7 @@ External packages declared only by repository tooling, test infrastructure, the `eslint-plugin-sonarjs` (LGPL-3.0-only) and `lightningcss` (MPL-2.0) run only as development tooling; their code is not linked into or distributed with any DeepSeek Harness artifact. + ## Python SDK dependencies (`python/`) Direct dependencies of the `pyproject.toml` manifests, plus `uv` as the development workflow tool. diff --git a/lefthook.yml b/lefthook.yml index 900a6e52bf..bdab57a9a3 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -25,7 +25,7 @@ pre-commit: # lefthook only inspects files present on disk — so that one case still # falls through to the freshness assertion in the test lane. - name: third-party notices (staged) - glob: '{package.json,*/package.json,*/*/package.json,*/*/*/package.json,pnpm-workspace.yaml,pnpm-lock.yaml,vendor/README.md,python/*/pyproject.toml,scripts/gen-third-party-notices.ts,scripts/build-exe-for-python-sdk.ts}' + glob: '{package.json,*/package.json,*/*/package.json,*/*/*/package.json,*/*/*/*/package.json,pnpm-workspace.yaml,*/*/pnpm-workspace.yaml,pnpm-lock.yaml,vendor/README.md,python/*/pyproject.toml,scripts/gen-third-party-notices.ts,scripts/build-exe-for-python-sdk.ts}' run: node_modules/.bin/tsx scripts/gen-third-party-notices.ts && git add THIRD_PARTY_NOTICES.md - name: whitespace (staged) diff --git a/scripts/gen-third-party-notices.spec.ts b/scripts/gen-third-party-notices.spec.ts index bd2107d044..29db79e3ff 100644 --- a/scripts/gen-third-party-notices.spec.ts +++ b/scripts/gen-third-party-notices.spec.ts @@ -1,7 +1,7 @@ import { readdirSync, readFileSync } from 'node:fs' import { resolve } from 'node:path' import { describe, expect, it } from 'vitest' -import { type Manifest, parsePythonRequirements, parseVendoredRows, render, tierExternalDeps } from './gen-third-party-notices.ts' +import { isPermissive, type Manifest, manifestPatterns, parsePyprojectRequirements, parsePythonRequirements, parseVendoredRows, render, tierExternalDeps } from './gen-third-party-notices.ts' const root = resolve(import.meta.dirname, '..') @@ -94,9 +94,61 @@ describe('parsePythonRequirements', () => { }) it('reads the committed manifests', () => { - const text = readFileSync(resolve(root, 'python/sdk/pyproject.toml'), 'utf8') - const block = /dependencies\s*=\s*\[([^\]]*)\]/.exec(text)?.[1] ?? '' + expect(parsePyprojectRequirements(readFileSync(resolve(root, 'python/sdk/pyproject.toml'), 'utf8'))).toContain('pydantic') + }) +}) - expect(parsePythonRequirements(block)).toContain('pydantic') +describe('parsePyprojectRequirements', () => { + it('locates requirement arrays by TOML table, so author-named groups are not missed', () => { + expect(parsePyprojectRequirements([ + '[build-system]', + 'requires = ["hatchling>=1.24.0"]', + '', + '[project]', + 'name = "not-a-requirement"', + 'dependencies = ["pydantic>=2.12"]', + '', + '[project.optional-dependencies]', + 'cli = ["click"]', + '', + '[dependency-groups]', + 'docs = ["sphinx>=7"]', + '', + '[tool.hatch.build.targets.wheel]', + 'packages = ["src/deepseek_harness"]', + '', + '[tool.pytest.ini_options]', + 'testpaths = ["tests"]', + ].join('\n'))).toEqual(['hatchling', 'pydantic', 'click', 'sphinx']) + }) + + it('does not truncate an array at a bracket inside extras', () => { + expect(parsePyprojectRequirements('[project]\ndependencies = ["httpx[http2]", "requests"]\n')) + .toEqual(['httpx', 'requests']) + }) + + it('reads a multi-line array', () => { + expect(parsePyprojectRequirements('[project]\ndependencies = [\n "pydantic>=2.12",\n "typing-extensions",\n]\n')) + .toEqual(['pydantic', 'typing-extensions']) + }) +}) + +describe('isPermissive', () => { + it('accepts the licenses this project ships and rejects copyleft or unknown ones', () => { + expect(['MIT', 'ISC', 'BSD-3-Clause', 'Apache-2.0', 'MIT / Apache-2.0', '(MIT OR CC0-1.0)'].every(isPermissive)).toBe(true) + expect(['LGPL-3.0-only', 'MPL-2.0', 'GPL-3.0-or-later', 'SEE LICENSE IN LICENSE'].some(isPermissive)).toBe(false) + }) +}) + +describe('manifestPatterns', () => { + it('derives globs from the declared members, so a new member area is read', () => { + expect(manifestPatterns(['packages/*/*', 'tools/*'], ['packages/*'])).toEqual([ + 'package.json', + 'packages/*/*/package.json', + 'tools/*/package.json', + 'examples/*/package.json', + 'native/landlock-run/package.json', + 'native/landlock-run/packages/*/package.json', + ]) }) }) diff --git a/scripts/gen-third-party-notices.ts b/scripts/gen-third-party-notices.ts index a33f0671fd..134a939662 100644 --- a/scripts/gen-third-party-notices.ts +++ b/scripts/gen-third-party-notices.ts @@ -110,11 +110,36 @@ function readManifest(rel: string): Manifest { return JSON.parse(readFileSync(resolve(root, rel), 'utf8')) as Manifest } +/** + * Manifest globs, derived from the workspace declarations rather than listed + * here, so a new member area (`tools/*`) is read the day it is declared. + * @returns one glob per manifest-bearing location, repository-relative. + */ +export function manifestPatterns(rootMembers: readonly string[], nativeMembers: readonly string[]): string[] { + return [ + 'package.json', + ...rootMembers.map(member => `${member}/package.json`), + // The demo leaves join the workspace through `examples/package.json`, so + // their own manifests are members of nothing and no glob above reaches them. + 'examples/*/package.json', + // `native/landlock-run` is a nested workspace with its own lock file. + 'native/landlock-run/package.json', + ...nativeMembers.map(member => `native/landlock-run/${member}/package.json`), + ] +} + +/** The `packages:` member globs declared by one pnpm workspace file. */ +function workspaceMembers(rel: string): string[] { + const declared = (yaml.load(readFileSync(resolve(root, rel), 'utf8')) as { packages?: unknown }).packages + if (!Array.isArray(declared) || declared.length === 0) { + throw new Error(`gen-third-party-notices: ${rel} declares no workspace members; the manifest set cannot be derived.`) + } + return declared.map(member => String(member)) +} + /** Every workspace manifest, keyed by path, plus the set of workspace package names. */ function loadWorkspaceManifests(): { manifests: Map; names: Set } { - // `native/landlock-run` is a nested workspace with its own lock file; its - // leaf manifests live one level deeper than this repository's own tiers. - const patterns = ['package.json', 'vendor/*/package.json', 'packages/*/*/package.json', 'apps/*/package.json', 'website/package.json', 'examples/package.json', 'python/sdk-runtime/package.json', 'native/landlock-run/package.json', 'native/landlock-run/packages/*/package.json'] + const patterns = manifestPatterns(workspaceMembers('pnpm-workspace.yaml'), workspaceMembers('native/landlock-run/pnpm-workspace.yaml')) const manifests = new Map() const names = new Set() for (const pattern of patterns) { @@ -132,15 +157,21 @@ function loadWorkspaceManifests(): { manifests: Map; names: Se function installedMetadata(name: string): { license: string; repo: string } { const override = OVERRIDES[name] let manifest: (Manifest & { license?: string; repository?: string | { url?: string }; homepage?: string }) | undefined - const direct = resolve(root, 'node_modules', name, 'package.json') - if (existsSync(direct)) { - manifest = JSON.parse(readFileSync(direct, 'utf8')) as typeof manifest - } else { - const prefix = `${name.replace('/', '+')}@` - const entry = readdirSync(resolve(root, 'node_modules/.pnpm')).find(dir => dir.startsWith(prefix)) - if (entry !== undefined) { - manifest = JSON.parse(readFileSync(resolve(root, 'node_modules/.pnpm', entry, 'node_modules', name, 'package.json'), 'utf8')) as typeof manifest + // The nested Landlock workspace installs into its own store, so a package + // only that workspace depends on is unreachable from the root one. + for (const store of ['node_modules', 'native/landlock-run/node_modules']) { + const direct = resolve(root, store, name, 'package.json') + if (existsSync(direct)) { + manifest = JSON.parse(readFileSync(direct, 'utf8')) as typeof manifest + break } + const virtual = resolve(root, store, '.pnpm') + if (!existsSync(virtual)) continue + const prefix = `${name.replace('/', '+')}@` + const entry = readdirSync(virtual).find(dir => dir.startsWith(prefix)) + if (entry === undefined) continue + manifest = JSON.parse(readFileSync(resolve(virtual, entry, 'node_modules', name, 'package.json'), 'utf8')) as typeof manifest + break } const license = override?.license ?? manifest?.license const rawRepo = typeof manifest?.repository === 'string' ? manifest.repository : manifest?.repository?.url ?? manifest?.homepage @@ -272,20 +303,72 @@ export function parsePythonRequirements(block: string): string[] { return names } +/** + * Every requirement name a `pyproject.toml` declares, located by TOML table + * rather than by key name: `requires` under `[build-system]`, `dependencies` + * under `[project]`, and every key under `[project.optional-dependencies]` and + * `[dependency-groups]`, whose keys are author-chosen group names. Array bodies + * are scanned with quote awareness, because a requirement may itself contain + * `]` inside extras (`"httpx[http2]"`). + * @param text - the complete `pyproject.toml` contents. + * @returns each declared requirement's distribution name, in file order. + */ +export function parsePyprojectRequirements(text: string): string[] { + const names: string[] = [] + let table = '' + const lines = text.split('\n') + for (let index = 0; index < lines.length; index += 1) { + const line = lines[index] ?? '' + const header = /^\s*\[([^\]]+)]\s*$/.exec(line) + if (header?.[1] !== undefined) { + table = header[1] + continue + } + const assignment = /^\s*([A-Za-z0-9._-]+)\s*=\s*\[/.exec(line) + if (assignment?.[1] === undefined) continue + const key = assignment[1] + const bearsRequirements = (table === 'build-system' && key === 'requires') + || (table === 'project' && key === 'dependencies') + || table === 'project.optional-dependencies' + || table === 'dependency-groups' + if (!bearsRequirements) continue + + // Consume the array body from the opening bracket to its match, ignoring + // brackets inside quoted requirements. + let body = '' + let depth = 0 + let quoted = false + let cursor = index + let column = line.indexOf('[') + scan: for (; cursor < lines.length; cursor += 1) { + const current = lines[cursor] ?? '' + for (; column < current.length; column += 1) { + const character = current[column] ?? '' + if (character === '"' || character === "'") quoted = !quoted + if (!quoted && character === '[') depth += 1 + if (!quoted && character === ']') { + depth -= 1 + if (depth === 0) break scan + } + if (depth > 0) body += character + } + body += '\n' + column = 0 + } + if (depth !== 0) throw new Error(`gen-third-party-notices: unterminated ${key} array in a pyproject.toml table [${table}].`) + names.push(...parsePythonRequirements(body)) + index = cursor + } + return names +} + /** Direct Python dependencies named by the `pyproject.toml` manifests under `python/`. */ function collectPython(): { name: string; license: string; repo: string; role: string }[] { const found = new Set() for (const path of ['python/sdk/pyproject.toml', 'python/sdk-runtime/pyproject.toml']) { - const text = readFileSync(resolve(root, path), 'utf8') - // Requirement arrays only: `[project] name`/`readme` and `[tool.*]` string - // values would otherwise read as dependencies. - for (const block of text.matchAll(/(?:^|\n)\s*(?:requires|dependencies|test|dev|lint)\s*=\s*\[([^\]]*)\]/g)) { - const body = block[1] - if (body === undefined) continue - for (const name of parsePythonRequirements(body)) { - if (name.startsWith('deepseek')) continue - found.add(name) - } + for (const name of parsePyprojectRequirements(readFileSync(resolve(root, path), 'utf8'))) { + if (name.startsWith('deepseek')) continue + found.add(name) } } return [...found].sort((a, b) => a.localeCompare(b)).map((name) => { @@ -311,6 +394,33 @@ function verifyBuildTimePins(): void { } } +/** + * Whether an SPDX expression is a permissive license this project may ship. + * Anything outside the list — copyleft or unrecognized — is reported rather + * than silently rendered, because the tier tables assert what may be linked. + * @param license - the SPDX expression from the package manifest. + * @returns true when every alternative in the expression is permissive. + */ +export function isPermissive(license: string): boolean { + const permissive = new Set(['MIT', 'ISC', 'BSD-2-Clause', 'BSD-3-Clause', 'Apache-2.0', '0BSD', 'Unlicense', 'CC0-1.0', 'BlueOak-1.0.0', 'Python-2.0']) + return license.split('/').map(part => part.trim().replace(/^\(|\)$/g, '')) + .flatMap(part => part.split(' OR ').map(alternative => alternative.trim())) + .some(alternative => permissive.has(alternative)) +} + +/** + * Render the sentence that isolates non-permissive development tooling, or + * nothing at all when every development dependency is permissive. + * @param deps - development dependencies whose license is not permissive. + * @returns the paragraph to place after the development table. + */ +function renderNonPermissiveNote(deps: ExternalDep[]): string { + if (deps.length === 0) return '' + const named = deps.map(dep => `\`${dep.name}\` (${dep.license})`) + const subject = named.length === 1 ? named[0] : `${named.slice(0, -1).join(', ')} and ${named.at(-1)}` + return `\n${subject} ${named.length === 1 ? 'runs' : 'run'} only as development tooling; their code is not linked into or distributed with any DeepSeek Harness artifact.\n` +} + /** Render one npm dependency table. */ function renderNpmTable(deps: ExternalDep[]): string { const lines = ['| Package | License |', '| --- | --- |'] @@ -331,7 +441,13 @@ export function render(): string { const python = collectPython() const patched = collectPatched() - const nonPermissiveDev = devDeps.filter(dep => dep.license.startsWith('LGPL') || dep.license.startsWith('MPL')) + const nonPermissiveDev = devDeps.filter(dep => !isPermissive(dep.license)) + // A copyleft license reaching a shipped surface is a distribution decision, + // not a rendering detail; the notices cannot quietly absorb it. + const nonPermissiveRuntime = runtimeDeps.filter(dep => !isPermissive(dep.license)) + if (nonPermissiveRuntime.length > 0) { + throw new Error(`gen-third-party-notices: runtime ${nonPermissiveRuntime.map(dep => `${dep.name} (${dep.license})`).join(', ')} is not a permissive license; review the distribution terms and record the decision before regenerating.`) + } const patchedLines = patched.map(({ spec, patch }) => `- \`${spec}\` — [\`${patch}\`](${patch})`) return `