Merge remote-tracking branch 'origin/master' into codex/fs-directory-listing

# Conflicts:
#	docs/rfc/README.md
#	packages/fs/fs-local/src/index.ts

packages/fs/tool-fs/src/diff.ts

@@ -0,0 +1,92 @@
+/**
+ * Result-time contextual-diff computation for the `write`/`edit` tools. Turns a
+ * before/after pair of file texts into one {@link FileDiff} per applied hunk —
+ * each hunk's `oldText`/`newText` reconstructed from the unified-diff lines with
+ * ±{@link DIFF_CONTEXT} surrounding context lines, matching how claude-agent-acp
+ * renders an editor inline diff.
+ *
+ * This is display-only presentation vocabulary (a UI concern), so it lives in
+ * the model-facing tool, NOT the `dsh-fs` storage seam — the backend returns
+ * only the raw before/after text (storage facts) and the tool computes the diff.
+ *
+ * @module @deepseek-ai/dsh-tool-fs/src/diff
+ */
+
+import { structuredPatch } from 'diff'
+import type { FileDiff } from '@deepseek-ai/dsh-tools'
+
+/** Context lines shown on each side of an applied hunk (matches claude-agent-acp). */
+export const DIFF_CONTEXT = 3
+
+/**
+ * The `write`/`edit` tools' private `tool/result` `meta` payload: the applied
+ * contextual-diff hunks. Attached opaquely (as `unknown`) on the tool result and
+ * persisted with the session log — it must be JSON-serializable (the session
+ * validates this at `append`), so `presentResult` reproduces the diff card on
+ * replay. The producing tool owns this shape; the bridge only sees the opaque
+ * `meta` and the tool narrows it back via {@link diffsFromMeta}.
+ */
+export type FsDiffMeta = { diffs: FileDiff[] }
+
+/**
+ * Compute one {@link FileDiff} per hunk between `before` and `after`, each
+ * carrying the applied change plus {@link DIFF_CONTEXT} context lines. Returns an
+ * empty array when the texts are identical (no hunks). For a scattered
+ * `replace_all` edit the patch yields multiple hunks, so multiple `FileDiff`s
+ * come back — matching the editor rendering one diff block per site.
+ *
+ * Each hunk's `oldText` is its `-` (removed) and context lines joined by `\n`;
+ * `newText` is its `+` (added) and context lines. A hunk with no old lines
+ * (a pure insertion) reports `oldText: null` (nothing to diff against), mirroring
+ * the call-time card's new-file convention. The unified-diff "\ No newline at end
+ * of file" markers are dropped — they annotate the patch, not file content.
+ */
+export function computeHunkDiffs(path: string, before: string, after: string): FileDiff[] {
+  const patch = structuredPatch('', '', before, after, undefined, undefined, { context: DIFF_CONTEXT })
+  const diffs: FileDiff[] = []
+  for (const hunk of patch.hunks) {
+    const oldLines: string[] = []
+    const newLines: string[] = []
+    for (const line of hunk.lines) {
+      // The unified-diff marker for a missing trailing newline annotates the
+      // patch, not the content — skip it so it never leaks into a diff block.
+      if (line.startsWith('\\')) continue
+      const text = line.slice(1)
+      if (line.startsWith('-')) {
+        oldLines.push(text)
+      } else if (line.startsWith('+')) {
+        newLines.push(text)
+      } else {
+        // A context (unchanged) line appears on both sides.
+        oldLines.push(text)
+        newLines.push(text)
+      }
+    }
+    diffs.push({ path, oldText: oldLines.length > 0 ? oldLines.join('\n') : null, newText: newLines.join('\n') })
+  }
+  return diffs
+}
+
+/** Whether `value` is a valid {@link FileDiff} (defensive narrowing from opaque `meta`). */
+function isFileDiff(value: unknown): value is FileDiff {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const { path, oldText, newText } = value as Record<string, unknown>
+  return typeof path === 'string'
+    && (oldText === null || typeof oldText === 'string')
+    && typeof newText === 'string'
+}
+
+/**
+ * Narrow an opaque `tool/result` `meta` back to this tool's {@link FileDiff}
+ * hunks, or `undefined` when it is absent/malformed. `presentResult` runs on
+ * arbitrary logged `meta` (possibly from an older shape or a hand-edited log), so
+ * it validates defensively rather than trusting the payload — a bad `meta` yields
+ * `undefined`, and the caller decides the fallback (edit → the generic result
+ * rendering; write → an args-derived whole-file diff), never a thrown presenter.
+ */
+export function diffsFromMeta(meta: unknown): FileDiff[] | undefined {
+  if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) return undefined
+  const diffs = (meta as Record<string, unknown>).diffs
+  if (!Array.isArray(diffs) || diffs.length === 0 || !diffs.every(isFileDiff)) return undefined
+  return diffs
+}

packages/fs/tool-fs/src/edit.ts

@@ -14,10 +14,12 @@
 
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { DiffCallView, DiffResultView, ToolResult } from '@deepseek-ai/dsh-tools'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { FsEditOutcome } from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
+import { computeHunkDiffs, diffsFromMeta, type FsDiffMeta } from './diff.ts'
 import { sessionCwd } from './session-cwd.ts'
 
 /** Validated `edit` arguments after defaulting. */
@@ -65,7 +67,7 @@ export function applyEditTool(ctx: Context): void {
       new_string: { type: 'string', required: true, description: 'Literal replacement text. Use an empty string to delete the match.' },
       replace_all: { type: 'boolean', description: 'Replace all matches. Defaults to false; when false, old_string must appear exactly once.' },
     },
-    async execute(args, exec): Promise<ContentBlock[]> {
+    async execute(args, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
       const input = parseEditArgs(args)
       const cwd = sessionCwd(exec)
       const target = await ctx.fs.resolve(input.filePath, cwd !== undefined ? { cwd } : undefined)
@@ -81,20 +83,39 @@ export function applyEditTool(ctx: Context): void {
       )
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
-      return [{ type: 'text', text: formatEditOutput(target.displayPath, outcome) }]
-    },
-    // Pure display: `edit` kind, a location for editor follow-along, and a short
-    // old→new summary as rawInput (truncated so a large replacement stays a
-    // readable card). The replacement COUNT is not available here — presentResult
-    // only sees `{ content, isError }`, not the outcome — so the title is static.
-    presentCall(args) {
-      const clip = (s: string): string => (s.length > 40 ? `${s.slice(0, 40)}…` : s)
+      // The result-time applied-hunk diff (before→after with context lines). An
+      // edit always changes content (parseEditArgs requires old_string to differ
+      // and editText matches at least once), so there is always at least one hunk.
+      // The bridge renders these as an inline diff that supersedes the call-time
+      // snippet; the display path is the model-facing `file_path` (the bridge
+      // relativizes it).
+      const diffs = computeHunkDiffs(input.filePath, outcome.before, outcome.after)
       return {
+        content: [{ type: 'text', text: formatEditOutput(target.displayPath, outcome) }],
+        meta: { diffs },
+      }
+    },
+    // Pure display: a diff card of the literal replacement (old_string →
+    // new_string), derived from the call args. `oldText: old_string || null`
+    // matches claude-agent-acp's Edit arm; new_string is a required arg here, so
+    // it maps straight to newText. A follow-along location points at the file.
+    presentCall(args): DiffCallView {
+      return {
+        card: 'diff',
         title: `Edit ${args.file_path}`,
-        kind: 'edit',
-        rawInput: `${JSON.stringify(clip(args.old_string))} → ${JSON.stringify(clip(args.new_string))}`,
+        diffs: [{ path: args.file_path, oldText: args.old_string || null, newText: args.new_string }],
         locations: [{ path: args.file_path }],
       }
     },
+    // Result-time display: the applied contextual-diff hunks carried on `meta`.
+    // On success with diffs, a `diff` result card supersedes the call-time
+    // snippet; on error (nothing applied) or malformed meta, fall through to the
+    // generic "updated successfully" rendering.
+    presentResult(args, result: ToolResult): DiffResultView | undefined {
+      if (result.isError) return undefined
+      const diffs = diffsFromMeta(result.meta)
+      if (diffs === undefined) return undefined
+      return { card: 'diff', title: `Edit ${args.file_path}`, diffs }
+    },
   }))
 }

packages/fs/tool-fs/src/index.ts

@@ -32,6 +32,8 @@ export { applyWriteTool, formatWriteOutput, parseWriteArgs } from './write.ts'
 export { applyEditTool, formatEditOutput, parseEditArgs } from './edit.ts'
 export { READ_MAX_BYTES, READ_MAX_LINE_LENGTH, buildWindow, formatReadOutput } from './read-render.ts'
 export type { FileReadOutcome, FileTextLine, ReadWindow, WindowResult } from './read-render.ts'
+export { DIFF_CONTEXT, computeHunkDiffs, diffsFromMeta } from './diff.ts'
+export type { FsDiffMeta } from './diff.ts'
 
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'tool-fs'

packages/fs/tool-fs/src/read.ts

@@ -14,6 +14,7 @@
 
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { GenericCallView } from '@deepseek-ai/dsh-tools'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { FsError } from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-fs'
@@ -101,19 +102,21 @@ export function applyReadTool(ctx: Context): void {
       ctx.emit('fs/observed', target, info.version, exec)
       return [{ type: 'text', text: formatReadOutput(target.displayPath, outcome) }]
     },
-    // Pure display: a UI card titled by the file, `read` kind (icon), and a
-    // location so an editor can follow along to the file (and the read's offset
-    // line). `rawInput` surfaces offset/limit when the model narrowed the read.
-    presentCall(args) {
-      const detail = [
-        ...args.offset !== undefined ? [`offset ${args.offset}`] : [],
-        ...args.limit !== undefined ? [`limit ${args.limit}`] : [],
-      ].join(', ')
+    // Pure display: a generic card titled by the file with the read window
+    // appended (`Read foo.txt (5 - 8)`), `read` kind (icon), and a follow-along
+    // location whose line is the read's offset (defaulting to 1). The window is
+    // derived from the RAW args (offset/limit as the model passed them), NOT the
+    // tool's defaulted 1/READ_LIMIT, so an unbounded read shows a bare title.
+    presentCall(args): GenericCallView {
+      const { offset, limit } = args
+      const window = limit !== undefined && limit > 0
+        ? ` (${offset ?? 1} - ${(offset ?? 1) + limit - 1})`
+        : offset !== undefined ? ` (from line ${offset})` : ''
       return {
-        title: `Read ${args.file_path}`,
+        card: 'generic',
+        title: `Read ${args.file_path}${window}`,
         kind: 'read',
-        locations: [{ path: args.file_path, ...args.offset !== undefined ? { line: args.offset } : {} }],
-        ...detail.length > 0 ? { rawInput: detail } : {},
+        locations: [{ path: args.file_path, line: offset ?? 1 }],
       }
     },
   }))

packages/fs/tool-fs/src/write.ts

@@ -13,10 +13,12 @@
 
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { DiffCallView, DiffResultView, ToolResult } from '@deepseek-ai/dsh-tools'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { FsWriteOutcome } from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
+import { computeHunkDiffs, diffsFromMeta, type FsDiffMeta } from './diff.ts'
 import { sessionCwd } from './session-cwd.ts'
 
 /** Validate value constraints the schema DSL can't express. */
@@ -50,7 +52,7 @@ export function applyWriteTool(ctx: Context): void {
       file_path: { type: 'string', required: true, description: 'Path to write, resolved by the filesystem backend.' },
       content: { type: 'string', required: true, description: 'Full UTF-8 text content to write.' },
     },
-    async execute(args, exec): Promise<ContentBlock[]> {
+    async execute(args, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
       const input = parseWriteArgs(args)
       const cwd = sessionCwd(exec)
       const target = await ctx.fs.resolve(input.filePath, cwd !== undefined ? { cwd } : undefined)
@@ -60,14 +62,41 @@ export function applyWriteTool(ctx: Context): void {
       const outcome = await ctx.fs.writeText(target, input.content, intent, exec.signal)
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
-      return [{ type: 'text', text: formatWriteOutput(target.displayPath, outcome) }]
+      // Attach a contextual hunk as `meta` ONLY for an overwrite (a before-version
+      // exists). A create has no "before" — `outcome.before` is null — so it
+      // carries no `meta`; `presentResult` then renders a whole-file diff from the
+      // args, so the completed card is still a diff (never the result text).
+      const diffs = outcome.before !== null ? computeHunkDiffs(input.filePath, outcome.before, outcome.after) : []
+      return {
+        content: [{ type: 'text', text: formatWriteOutput(target.displayPath, outcome) }],
+        ...diffs.length > 0 ? { meta: { diffs } } : {},
+      }
     },
-    // Pure display: `edit` kind (an editor treats create/replace as an edit) and
-    // a location so the UI can follow along to the written file. The create-vs-
-    // overwrite fact lives in the model-facing result text; `presentResult` only
-    // sees `{ content, isError }` (not the outcome), so the title stays static.
-    presentCall(args) {
-      return { title: `Write ${args.file_path}`, kind: 'edit', locations: [{ path: args.file_path }] }
+    // Pure display: a diff card (an editor renders write as a new-file / full-
+    // replace diff). `oldText: null` — a call-time presenter has no access to the
+    // file's prior content, so even an overwrite renders new-file style, matching
+    // claude-agent-acp. A follow-along location points at the written file.
+    presentCall(args): DiffCallView {
+      return {
+        card: 'diff',
+        title: `Write ${args.file_path}`,
+        diffs: [{ path: args.file_path, oldText: null, newText: args.content }],
+        locations: [{ path: args.file_path }],
+      }
+    },
+    // Result-time display: a `diff` card so the completed `tool_call_update`
+    // re-installs the diff rather than the model-facing result text (an ACP
+    // `tool_call_update.content` REPLACES the call's content, so a text result
+    // would clobber the pending diff card). An OVERWRITE uses the applied
+    // contextual hunks on `meta`; a CREATE has no `meta` (no prior content), so
+    // its whole-file new-file diff is derived from `args.content` (replay-safe,
+    // matching the call-time card). An error falls through to generic rendering
+    // so its message shows.
+    presentResult(args, result: ToolResult): DiffResultView | undefined {
+      if (result.isError) return undefined
+      const diffs = diffsFromMeta(result.meta)
+        ?? [{ path: args.file_path, oldText: null, newText: args.content }]
+      return { card: 'diff', title: `Write ${args.file_path}`, diffs }
     },
   }))
 }