Merge remote-tracking branch 'origin/master' into worktree/archive-agent-notes-20260726
# Conflicts: # .agents/notes/archived/process/2026-07-23-browser-demo-gif-recording.i18n.yaml
This commit is contained in:
Tianyi Cui
@@ -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
|
||||
2026-07-26-code-dispatch-log-spill.md: eee8fb73b3f1ddba0a2da3ad5a9d2d4417d5951c
|
||||
2026-07-26-code-dispatch-log-spill.zh.md: 664a2aefcfef198d56809c289e10827a8084a06a
|
||||
@@ -0,0 +1,31 @@
|
||||
# Agent Note: Spilling the durable copy of Code Mode sub-dispatch results
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-26-code-dispatch-log-spill.zh.md)
|
||||
|
||||
> Scope: the fourth PR of the Code Mode UI stack — bounding the `tool/code-dispatch` event's content with the existing spill machinery. The [host foundation note](2026-07-26-code-dispatch-ui-foundation.md) accepted the unbounded log deliberately and named this PR as the payoff point; the [live-parallel note](2026-07-26-code-mode-live-parallel-dispatch.md) settled the event pair this shaping hooks into.
|
||||
|
||||
## Problem
|
||||
|
||||
Since the full-content dispatch logging landed, a `run_code` program that reads a large file wrote the complete rendered text into the session log — uncapped and outside spill policy, while native results were bounded to `maxInlineBytes` before logging. The asymmetry was backwards: sub-calls (built for bulk data work) were precisely the calls most likely to carry huge results, and the JSONL grew by megabytes per such turn.
|
||||
|
||||
## Decision
|
||||
|
||||
**A log-shaping waterfall on the registry, and the spill policy as its first listener.**
|
||||
|
||||
- **Seam**: `tools/code-dispatch-log` — a scope-filtered waterfall the bridge runs (via the registry's PRIVATE `shapeDispatchLog` invoker, handed to the bridge as a capability closure in `RunCodeBridgeOptions` — the waterfall is the public seam, the invoker never widens the service surface; contained: a throwing listener falls back to the unshaped content, with total error formatting so a hostile thrown value cannot escape the containment) over each settled sub-dispatch before appending `tool/code-dispatch`. The payload (`CodeDispatchLog`) carries the outer execution, the hoisted `agent` routing key, the sub-call identity, and the default content — the RENDERED result projection a native `tool/result` would carry (the program itself received the structured `value`). Only the durable copy is shapeable; the model sees neither. Shaping runs OFF the program path as tracked side work, but bounded: past `maxParallelSubCalls` pending log tasks the ordered commit lane holds, so a slow spill backend backpressures the run instead of accumulating unbounded pending I/O; run settlement still drains every task inside the open turn.
|
||||
- **Policy**: `dsh-spill-policy` registers a second arm on the new seam sharing the exact replacement pipeline of its model-facing arm (same `maxInlineBytes` cap, same preview + locator + within-cap invariant, same best-effort fallbacks), with the artifact labeled `dispatch` under the sub-call id. UIs and replay read the full text through the spill artifact exactly as they do for spilled native results, so the native-parity rendering story survives bounding.
|
||||
- **One deliberate asymmetry**: the model-facing arm skips `read` (the `read → spill → read again` loop); the dispatch-log arm bounds `read` sub-calls too — a log copy is not model context, so the loop cannot happen, and `read` is precisely the tool that produces huge logs.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Bound inside the bridge with a plain cap (no spill).** Rejected: truncation without a locator loses data replay/UIs may need, and re-introduces the "truncated summary" degraded render path the stack removed.
|
||||
|
||||
**Spill inside the bridge directly (call `ctx.spillStore` from code-mode.ts).** Rejected: the registry would grow a hard dependency on the spill capability; the waterfall keeps the policy where every other spill decision lives, composable and disable-able (omitted `maxInlineBytes` still means a true no-op).
|
||||
|
||||
**Reuse `tools/post-execute` for nested calls instead of a new event.** Rejected: post-execute shapes the PROGRAM-facing result (nested calls deliberately skip it so programs get complete data); the durable copy needs its own decision point after the program has its value.
|
||||
|
||||
## Consequences
|
||||
|
||||
The session log is bounded again for Code Mode turns — the README's Known Limitations entry about uncapped dispatch logging is resolved and now points here. Old logs with oversized dispatch content still replay (the event shape is unchanged; only future appends shrink). The web UI renders spilled sub-call output as the preview + locator text through the identical native path, no special casing.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Agent Note：将 Code Mode 子分发结果的持久副本纳入 spill 机制
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-26-code-dispatch-log-spill.md) | 中文
|
||||
|
||||
> 范围：Code Mode UI 堆叠 PR（Pull Request）链的第四个 PR，即用既有的 spill 机制为 `tool/code-dispatch` 事件的内容施加边界。[宿主侧基础 Agent Note](2026-07-26-code-dispatch-ui-foundation.md)当初有意接受了不设上限的日志，并指明本 PR 就是兑现点；[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md)敲定了本次整形所挂接的事件对。
|
||||
|
||||
## 问题
|
||||
|
||||
自携带完整内容的分发日志落地以来，读取大文件的 `run_code` 程序过去会把完整的渲染文本写进会话日志，不设上限、位于 spill 策略之外；而原生结果在记录之前就已被限制在 `maxInlineBytes` 以内。这种不对称的方向完全反了：子调用（本就为批量数据工作而设计）恰恰是最可能携带巨大结果的调用，而每个这样的轮次都会让 JSONL 增长数 MB。
|
||||
|
||||
## 决策
|
||||
|
||||
**在注册表上增设一个日志整形 waterfall（瀑布式事件），spill 策略作为其第一个监听器。**
|
||||
|
||||
- **Seam**：`tools/code-dispatch-log`，一个按作用域过滤的 waterfall，由桥接层在追加 `tool/code-dispatch` 之前对每个已结算的子分发运行（经由注册表的私有 `shapeDispatchLog` 调用器——作为能力闭包经 `RunCodeBridgeOptions` 交给桥接层；waterfall 才是公开 seam，调用器绝不加宽服务表面。故障被兜住：监听器抛出异常时回退到未整形的内容，并用全防御的错误格式化确保恶意抛出值无法逃出兜底）。载荷（`CodeDispatchLog`）携带外层执行、提升出来的 `agent` 路由键、子调用标识与默认内容——即原生 `tool/result` 所载的渲染后结果投影（程序本身收到的是结构化 `value`）。可整形的只有持久副本；模型两者都看不到。整形作为被跟踪的旁路工作在程序路径之外运行，但有界：待处理日志任务超过 `maxParallelSubCalls` 时有序提交车道会暂停，因此慢速 spill 后端会对整个 run 施加背压，而不是无限累积待完成 I/O；run 结算仍会在开放轮次内排空全部任务。
|
||||
- **策略**：`dsh-spill-policy` 在新 seam 上注册第二个分支，与其面向模型的分支共用一模一样的替换流水线（同样的 `maxInlineBytes` 上限、同样的预览 + 定位符 + 不超上限不变式、同样的尽力而为回退），产物以 `dispatch` 为标签，记在子调用 id 名下。UI 与回放通过 spill 产物读取全文，方式与读取被 spill 的原生结果完全相同，因此与原生同等保真的渲染在施加边界之后依然成立。
|
||||
- **一处有意的不对称**：面向模型的分支跳过 `read`（避免 `read → spill → read again` 循环）；分发日志分支则连 `read` 子调用也施加边界：日志副本不是模型上下文，该循环因此不可能发生，而 `read` 恰恰是会产生巨大日志的那个工具。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**在桥接层内部用普通上限施加边界（不做 spill）。** 否决：没有定位符的截断会丢失回放与 UI 可能需要的数据，还会重新引入本堆叠 PR 链已经移除的「截断摘要」降级渲染路径。
|
||||
|
||||
**直接在桥接层内做 spill（从 code-mode.ts 调用 `ctx.spillStore`）。** 否决：注册表会因此对 spill 能力产生硬依赖；waterfall 则把策略留在所有其他 spill 决策所在的地方，既可组合也可禁用（省略 `maxInlineBytes` 依然意味着真正的 no-op）。
|
||||
|
||||
**让嵌套调用复用 `tools/post-execute`，而不是新增一个事件。** 否决：post-execute 整形的是面向程序的那份结果（嵌套调用有意跳过它，好让程序拿到完整数据）；持久副本需要一个属于自己的决策点，位于程序取得其值之后。
|
||||
|
||||
## 后果
|
||||
|
||||
对 Code Mode 轮次而言，会话日志重新有了边界：README 中关于分发日志不设上限的 Known Limitations 条目已经解决，现在指向本篇。携带超大分发内容的旧日志仍可回放（事件形状未变；只有今后的追加才会变小）。web UI 经由与原生完全相同的路径，把被 spill 的子调用输出渲染为预览 + 定位符文本，没有任何特殊处理。
|
||||
+6
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-26-code-mode-trajectory-waterfall-spans.md: fe4dcc25dbf211cf69e0d33937cf87a7482852e2
|
||||
2026-07-26-code-mode-trajectory-waterfall-spans.zh.md: aaae06b1fca1b5587d06aa7704adec421d2b2c27
|
||||
@@ -0,0 +1,31 @@
|
||||
# Agent Note: Code Mode sub-calls in the trajectory and waterfall views
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-26-code-mode-trajectory-waterfall-spans.zh.md)
|
||||
|
||||
> Scope: the final PR of the Code Mode UI stack — sub-dispatch rendering in the two non-chat views. Chat nesting is owned by the [sub-call rows note](2026-07-26-code-mode-chat-subcall-rows.md); the timing this consumes is the [live-parallel note](2026-07-26-code-mode-live-parallel-dispatch.md)'s start/settle pair.
|
||||
|
||||
## Problem
|
||||
|
||||
Trajectory and waterfall still rendered a `run_code` turn as one opaque Tool cell / one node-count bar. The chat view got nested sub-rows in the earlier PRs, but the two analytical views — whose whole purpose is structure and timing — showed none of the sub-call structure and none of the per-sub-call wall time the dispatch pair now records. Waterfall sub-spans were deliberately deferred until that pair existed: a span without real timing would have been a lie.
|
||||
|
||||
## Decision
|
||||
|
||||
**Trajectory: `subtool` cells interleaved after their parent Tool cell. Waterfall: real-time sub-lanes under the owning turn row.**
|
||||
|
||||
- **Trajectory**: the layout fold takes the snapshot's `codeDispatches` index; after each Tool cell whose `callId` has dispatches (assistant-block calls, orphan results, and running calls alike), it interleaves one `subtool` cell per sub-dispatch in start order — indexes stay sequential across the interleave. A settled sub-call's duration is its start/settle pair (`durationSeconds(sub.time, sub.callTime)`); a running one shows the em dash, exactly the native in-flight convention. The new cell kind wears a `Sub` tag (business tint) and a 28px indent so nesting reads at a glance.
|
||||
- **Waterfall**: `deriveSubSpans` folds the dispatch index into per-turn lanes with REAL timing — each parent's dispatch window is first start → last settle, and every lane's offset/width is its fraction of that window, so parallel sub-calls (PR3) visibly overlap. Each lane carries a `timing` provenance tag: `measured` (pair observed), `running` (settle pending — extends to the window end at reduced opacity), or `unknown` (settle-only replay window, `callTime: null` — drawn hollow and titled "duration unknown", never a fabricated 0 ms). Lanes draw under the owning turn's bar row, scaled into a fixed lane budget.
|
||||
- Both views read `codeDispatches` through the standard snapshot hook — no new wire data, no new stores; replay renders identically to live by construction.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Fold sub-calls into the turn-span node counts (weight the existing bars).** Rejected: it hides exactly the structure this stack exists to show, and node-count weighting is already flagged as a stand-in (deviation ledger #3).
|
||||
|
||||
**A dedicated sub-call panel instead of in-view nesting.** Rejected: the stack's settled UX is nesting under the parent everywhere; a separate panel would diverge from chat and double the selection plumbing.
|
||||
|
||||
**Defer waterfall lanes until the P-III duration-lane redesign.** Rejected: the sub-lane timing is real today (the pair), and the fraction-of-window rendering is independent of whatever the turn-level lanes become; deferring would strand the stack's timing payoff.
|
||||
|
||||
## Consequences
|
||||
|
||||
The waterfall carries the first REAL wall-time rendering in the client (turn bars remain node-count stand-ins — the contrast is deliberate and labeled by hover titles). Trajectory cell indexes now count sub-calls, so `#N` totals grow on Code Mode turns. Specs pin the interleave order and durations, the running em-dash arm, window fractions (offsets/widths), the running-lane extension, the unknown-timing (settle-only) lane, and the rendered lane under the turn row; the built-client Code Mode fixture snapshot additionally pins both tabs' assembled rendering (sub-cells with real +0.8s durations, measured lanes).
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
# Agent Note：trajectory 与 waterfall 视图中的 Code Mode 子调用
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-26-code-mode-trajectory-waterfall-spans.md) | 中文
|
||||
|
||||
> 范围：Code Mode UI 堆叠 PR（Pull Request）链的最后一个 PR，涵盖两个非 chat 视图中的子分发渲染。chat 的嵌套归[子调用行 Agent Note](2026-07-26-code-mode-chat-subcall-rows.md)所有；本篇所消费的计时即[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md)的 start/settle 事件对。
|
||||
|
||||
## 问题
|
||||
|
||||
trajectory 过去仍把一个 `run_code` 轮次渲染为单个不透明的 Tool 单元格，waterfall 则渲染为一根节点计数条。chat 视图在此前的几个 PR 中已获得嵌套子行，但这两个分析视图（其全部意义恰恰是结构与计时）过去既不显示任何子调用结构，也不显示分发事件对如今已记录的逐子调用墙钟时间。waterfall 的子调用 span 曾被刻意推迟到该事件对存在之后：没有真实计时的 span 就是在撒谎。
|
||||
|
||||
## 决策
|
||||
|
||||
**trajectory：`subtool` 单元格穿插在其父 Tool 单元格之后。waterfall：所属轮次行之下、带真实计时的子泳道（sub-lane）。**
|
||||
|
||||
- **trajectory**：布局 fold 接收快照的 `codeDispatches` 索引；凡某个 Tool 单元格的 `callId` 名下存在分发（assistant 块内的调用、孤儿结果与运行中的调用一视同仁），fold 就在该单元格之后按启动顺序为每个子分发穿插一个 `subtool` 单元格，索引在整个穿插序列中保持连续编号。已结算子调用的耗时来自其 start/settle 事件对（`durationSeconds(sub.time, sub.callTime)`）；运行中的子调用则显示破折号，与原生的进行中约定完全一致。新增的单元格类型带有 `Sub` 标签（business 色调）与 28px 缩进，嵌套关系一眼可辨。
|
||||
- **waterfall**：`deriveSubSpans` 把分发索引折叠成带真实计时的逐轮次泳道：每个父调用的分发窗口为首个 start → 最后一个 settle，每条泳道的偏移/宽度即其在该窗口中的占比，因此并行的子调用（PR3）会肉眼可见地重叠。每条泳道带有 `timing` 来源标记：`measured`（观察到了成对事件）、`running`（settle 未到 — 以较低不透明度延伸至窗口末端）或 `unknown`（回放窗口只含 settle、`callTime: null` — 画成空心并以「duration unknown」为悬停标题，绝不伪造 0 ms）。泳道绘制在所属轮次的条形行之下，并缩放进固定的泳道预算。
|
||||
- 两个视图都经由标准的快照 hook 读取 `codeDispatches`：没有新的 wire 数据，也没有新的 store；回放的渲染由构造保证与实时完全一致。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**把子调用折入轮次 span 的节点计数（给既有的条加权）。** 否决：它隐藏的恰恰是本堆叠 PR 链存在就是为了展示的结构，而且节点计数加权本就已被标记为占位（偏差账本 #3）。
|
||||
|
||||
**用专用的子调用面板取代视图内嵌套。** 否决：本堆叠 PR 链已敲定的 UX 是处处嵌套在父级之下；独立面板会与 chat 发生偏差，还会让选中接线翻倍。
|
||||
|
||||
**把 waterfall 泳道推迟到 P-III 的时长泳道重新设计。** 否决：子泳道的计时如今已是真实的（即那对事件），而按窗口占比的渲染与轮次级泳道将来的形态无关；推迟只会让本堆叠 PR 链的计时收益搁浅。
|
||||
|
||||
## 后果
|
||||
|
||||
waterfall 承载了 client 中第一处真实的墙钟时间渲染（轮次条仍是节点计数的占位；这一反差是有意为之，并由悬停标题标注）。trajectory 的单元格索引现在会把子调用计入，因此 Code Mode 轮次上的 `#N` 总数会随之增大。spec 锁定穿插顺序与耗时、运行中的破折号分支、窗口占比（偏移/宽度）、运行中泳道的延伸、unknown 计时（仅 settle）泳道，以及轮次行之下实际渲染出的泳道；构建产物级的 Code Mode fixture 快照另行锁定两个标签页的组装后渲染（带真实 +0.8s 耗时的子单元格、measured 泳道）。
|
||||
Reference in New Issue
Block a user