Files

Tianyi Cui d8fd3225af feat(tool-fs): result-time applied-hunk diffs for write/edit

fs write/edit now emit a result-time contextual-diff tool_call_update
(the applied hunk with ±3 context lines, one hunk per replace_all site),
matching what claude-agent-acp sends and what makes an editor render the
change in place. The call-time snippet diff stays; the result hunk
supersedes it (ACP content-replace).

Mechanism:
- A persisted tool-private `meta` channel: execute may return
  `{ content, meta }`; `meta` (JsonValue) rides on the tool/result event
  and is handed back to presentResult, so the diff reproduces on replay
  (event-sourced). JsonValue is now exported from dsh-session.
- The backend returns raw before/after text (storage facts) on
  FsWriteOutcome/FsEditOutcome; the tool computes the hunk via the npm
  `diff` package's structuredPatch. A create has no before → no result
  diff; a failed/aborted mutation carries no meta.
- ToolResultView gains a DiffResultView; the bridge's result-side switch
  renders it as {type:'diff'} content blocks.

RFC: docs/rfc/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md
(justifies the npm `diff` runtime dep over vendoring and the meta channel);
the render-intent-union RFC's Non-goal is updated to record this shipped.
All fs snapshot goldens re-recorded; edit/overwrite gain the contextual
result diff, create/read/policy-reject unchanged in structure.

2026-07-03 17:12:00 +08:00

6.5 KiB

Raw Blame History

RFC: Result-time applied-hunk diffs for file mutations

Status: implemented

Problem

The tagged render-intent union gave dsh-tool-fs write/edit a card:'diff' at CALL time, derived purely from the tool's args: write ⇒ {oldText:null, newText:content} (the whole new file), edit ⇒ {oldText:old_string, newText:new_string} (the bare replaced snippet). An editor renders that as an inline diff, but it is a context-free diff — the bare old_string→new_string with no surrounding lines, and a replace_all that touched five scattered sites still renders as one snippet pair.

Driving claude-agent-acp's own ACP bridge shows what a full editor diff looks like: after the mutation applies, it emits a SECOND tool_call_update whose diff is the applied hunk with ±3 context lines (and one hunk per changed site for replace_all), reconstructed from the tool's structuredPatch. That result-time hunk is what makes Zed show the change in place in the file rather than as a floating snippet. Our tools stopped at the call-time snippet; the completed result carried only the plain "updated successfully" text, no diff.

The obstacle is a seam boundary: presentResult(args, result) is a pure function of args + the model-facing result ({content, isError}) — it runs on live streaming AND on session-log replay, so it must be replay-deterministic and cannot do I/O. It never sees the file's before/after content, and FsEditOutcome/FsWriteOutcome carried only a replacement count + version, not the text. So there was no way to compute — or even carry — an applied hunk to the presenter.

Decision

Add a persisted, tool-private presentation channel so a tool's execute can attach a result-time render payload that survives replay, and use it to carry the applied-hunk diff.

1. A `meta` channel on the tool result (core)

ToolDefinition.execute may now return either its model-facing ContentBlock[] (unchanged, the common case) OR { content: ContentBlock[]; meta?: JsonValue }:

type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta?: JsonValue }

meta is an opaque, JSON-serializable payload the core never interprets. The registry threads it onto the tool/result session event ({ …, meta?: JsonValue }), so it is persisted with the log; on replay the same meta is read back and handed to presentResult via a widened ToolResult ({ content, isError, meta? }). Because the payload lives in the event log, the diff reproduces on session reload / snapshot replay for free — the event-sourcing guarantee, not a re-computation. JsonValue is exported from dsh-session (paired with the existing isJsonValue predicate that already gates every event's serializability at append).

This is the general shape ("a tool attaches durable result presentation"), not an fs-specific one — any tool can use it.

2. The tool computes the hunk; the backend returns before/after (fs)

Per the capability-seam split, the storage backend returns only storage facts and the model-facing tool owns presentation:

dsh-fs widens FsEditOutcome with { before: string; after: string } and FsWriteOutcome with { before: string | null; after: string } (before: null ⇒ a create, or an existing-but-undiffable binary/non-UTF-8 file). The local backend already holds both texts at write time; it returns them as raw LF-normalized text, with no diff/UI concept entering the seam.
dsh-tool-fs computes the contextual hunk from before/after and attaches it as meta: { diffs: FileDiff[] }. A result diff is emitted only when a before-version exists — edit always; write on overwrite; a create emits none (there is no before), matching claude-agent-acp's empty structuredPatch on create. A failed/aborted/policy-rejected mutation applied nothing, so it carries no meta and renders no result diff.

3. The bridge renders a `diff` result card

ToolResultView gains a DiffResultView { card:'diff'; title?; diffs: FileDiff[] }; the bridge's result-side switch (view.card) gets a diff arm emitting the {type:'diff'} ToolCallContent blocks (mirroring the call-side arm). An ACP tool_call_update.content REPLACES the call's content in an editor, so the result-time contextual hunk supersedes the call-time snippet — the two-update sequence (call snippet, then result hunk) matches claude-agent-acp exactly.

The diff algorithm — a third-party runtime dependency over vendoring

Computing hunks-with-context is a solved problem with sharp edge cases (grouping, context coalescing, the trailing-newline marker). Rather than hand-roll it, dsh-tool-fs takes a runtime dependency on the npm diff package (v9, ships its own types) and uses its structuredPatch. The repo's default is to vendor Cordis-framework source, but that policy is about the framework; a leaf tool package taking a small, well-known, self-typed utility dependency is the same shape as dsh-acp depending on @agentclientprotocol/sdk. Vendoring a diff algorithm would be re-implementing a battle-tested one for no benefit — the pre-release "foundation over blast radius" reasoning does not argue for re-deriving standard algorithms. The dependency is pinned and its output is normalized in one small module (packages/fs/tool-fs/src/diff.ts).

Non-goals

Live incremental diff streaming. The hunk is computed once, after the mutation completes; there is no per-keystroke diff.
Diffing a binary/non-UTF-8 overwrite. before is null for such a file (it has no text diff basis); the write still succeeds and renders the call-time card only.
Rename/move diffs. Only content diffs of a single resolved path.

Completes the one remaining representation difference named as a non-goal in Tagged render-intent union — that RFC's Non-goals section is updated to record that applied-hunk diffs shipped here.
Builds on the filesystem capability seam (the before/after are storage facts the backend returns) and event-sourced sessions (the meta payload persists on the tool/result event, so replay reproduces the card).
The meta channel is deliberately generic: a future tool (a structured search, a data-table result) can attach its own durable result presentation without another core change.

6.5 KiB Raw Blame History