feat(tools): batch edits, process-tree kill, abort propagation, image read

- edit_file: optional `edits[]` for atomic multi-edit (resolve on original,
  reject overlaps, apply right-to-left). Reuses fuzzy match + nearMiss.
- run_bash: own timeout with process-tree kill (POSIX detached group /
  Windows taskkill /T) so forked grandchildren can't outlive the call;
  `all:true` restores stdout/stderr interleave order.
- ToolContext threads the turn AbortSignal into handlers; Ctrl-C now kills
  the running command tree mid-flight.
- read_file: returns image files (png/jpg/gif/webp/bmp) as base64 attachments
  for vision models instead of refusing as binary; 8MB cap. Adapter injects a
  user message carrying the pixels after the tool message (Ollama only honors
  images on user messages).
- JsonSchema gains `items` for array-of-object params.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: maruakshay

src/agent/adapter.ts

@@ -43,6 +43,12 @@ export function toOllamaMessages(history: MiiMessage[], system: string): OllamaM
       const texts = msg.content.filter((b): b is { type: 'text'; text: string } => b.type === 'text')
       for (const tr of tool_results) {
         out.push({ role: 'tool', content: tr.content, tool_call_id: tr.tool_use_id })
+        // Ollama only honours `images` on user messages, not tool messages — so a
+        // tool that returned pixels (read_file on an image) gets a follow-up user
+        // message carrying the base64 for the vision model to actually see.
+        if (tr.images && tr.images.length > 0) {
+          out.push({ role: 'user', content: 'Image content from the previous tool result:', images: tr.images })
+        }
       }
       if (texts.length > 0) {
         out.push({ role: 'user', content: texts.map((t) => t.text).join('') })

src/agent/loop.ts

@@ -405,12 +405,13 @@ export async function* runAgent(opts: RunAgentOpts): AsyncGenerator<AgentEvent,
       try { await hooks?.firePre(use) } catch { /* hook error ignored */ }
       let r: ToolResultBlock
       try {
-        const out = await tool.handler(use.input)
+        const out = await tool.handler(use.input, { signal })
         r = {
           type: 'tool_result',
           tool_use_id: use.id,
           content: out.content,
           is_error: out.is_error,
+          ...(out.images && out.images.length > 0 ? { images: out.images } : {}),
         }
       } catch (err) {
         r = {

src/agent/types.ts

@@ -15,6 +15,8 @@ export interface ToolResultBlock {
   tool_use_id: string
   content: string
   is_error?: boolean
+  /** Base64 images produced by the tool; surfaced to the model as a user message. */
+  images?: string[]
 }
 
 export type ContentBlock = TextBlock | ToolUse | ToolResultBlock

src/tools/edit_file.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { mkdtempSync, rmSync, writeFileSync, readFileSync } from 'fs'
 import { join, relative } from 'path'
-import { edit_file, fuzzyRange, similarity } from './edit_file.js'
+import { edit_file, fuzzyRange, similarity, applyBatch } from './edit_file.js'
 
 describe('similarity', () => {
   it('is 1 for identical (ws-trimmed) strings', () => {
@@ -34,6 +34,47 @@ describe('fuzzyRange', () => {
   })
 })
 
+describe('applyBatch', () => {
+  it('applies multiple non-overlapping edits atomically', () => {
+    const src = 'const a = 1\nconst b = 2\nconst c = 3\n'
+    const r = applyBatch(src, [
+      { old_str: 'a = 1', new_str: 'a = 10' },
+      { old_str: 'c = 3', new_str: 'c = 30' },
+    ])
+    expect('out' in r).toBe(true)
+    if ('out' in r) {
+      expect(r.count).toBe(2)
+      expect(r.out).toBe('const a = 10\nconst b = 2\nconst c = 30\n')
+    }
+  })
+
+  it('errors and applies nothing when one edit does not match', () => {
+    const src = 'x = 1\ny = 2\n'
+    const r = applyBatch(src, [
+      { old_str: 'x = 1', new_str: 'x = 9' },
+      { old_str: 'z = 3', new_str: 'z = 9' },
+    ])
+    expect('error' in r).toBe(true)
+    if ('error' in r) expect(r.error).toMatch(/edits\[1\].*not found/)
+  })
+
+  it('rejects a non-unique old_str', () => {
+    const r = applyBatch('dup\ndup\n', [{ old_str: 'dup', new_str: 'x' }])
+    expect('error' in r).toBe(true)
+    if ('error' in r) expect(r.error).toMatch(/not unique/)
+  })
+
+  it('rejects overlapping edits', () => {
+    const src = 'abcdef'
+    const r = applyBatch(src, [
+      { old_str: 'abcd', new_str: 'X' },
+      { old_str: 'cdef', new_str: 'Y' },
+    ])
+    expect('error' in r).toBe(true)
+    if ('error' in r) expect(r.error).toMatch(/overlap/)
+  })
+})
+
 describe('edit_file handler', () => {
   let dir: string
   const rel = (abs: string) => relative(process.cwd(), abs)
@@ -90,6 +131,33 @@ describe('edit_file handler', () => {
     expect(readFileSync(join(dir, 'a.py'), 'utf-8')).toBe('def f():\n\tfoo = 2\n')
   })
 
+  it('applies a batch of edits via the edits[] param', async () => {
+    const p = seed('a.txt', 'one\ntwo\nthree\n')
+    const out = await edit_file.handler({
+      path: p,
+      edits: [
+        { old_str: 'one', new_str: '1' },
+        { old_str: 'three', new_str: '3' },
+      ],
+    })
+    expect(out.is_error).toBeFalsy()
+    expect(out.content).toMatch(/2 edits/)
+    expect(readFileSync(join(dir, 'a.txt'), 'utf-8')).toBe('1\ntwo\n3\n')
+  })
+
+  it('writes nothing when a batch edit fails to match', async () => {
+    const p = seed('a.txt', 'alpha\nbeta\n')
+    const out = await edit_file.handler({
+      path: p,
+      edits: [
+        { old_str: 'alpha', new_str: 'A' },
+        { old_str: 'gamma', new_str: 'G' },
+      ],
+    })
+    expect(out.is_error).toBe(true)
+    expect(readFileSync(join(dir, 'a.txt'), 'utf-8')).toBe('alpha\nbeta\n')
+  })
+
   it('on no match, returns the closest text in the file', async () => {
     const p = seed('a.txt', 'const alpha = 1\nconst beta = 2\n')
     const out = await edit_file.handler({ path: p, old_str: 'const alph = 1', new_str: 'x' })

src/tools/edit_file.ts

@@ -3,11 +3,18 @@ import { confinePath } from './paths.js'
 import { verifyHint } from './verifyHint.js'
 import type { Tool } from './types.js'
 
-interface Input {
-  path: string
+interface EditSpec {
   old_str: string
   new_str: string
+}
+
+interface Input {
+  path: string
+  old_str?: string
+  new_str?: string
   replace_all?: boolean
+  /** Batch mode: apply several exact-string edits atomically in one call. */
+  edits?: EditSpec[]
 }
 
 /** Cheap line-similarity: fraction of matching chars by position, ignoring leading/trailing ws. */
@@ -90,22 +97,96 @@ function nearMiss(src: string, old_str: string): string {
   return `\nClosest text in file (lines ${from + 1}-${to}):\n${ctx}`
 }
 
+/**
+ * Find the unique char range of `old_str` in `src`: exact match first, then a
+ * whitespace-tolerant fuzzy match. Used by batch mode, which has no replace_all
+ * — every edit must resolve to exactly one location. Returns the range or a
+ * reason string explaining why it couldn't (with the closest text on no match).
+ */
+function locate(src: string, old_str: string): [number, number] | { error: string } {
+  const first = src.indexOf(old_str)
+  if (first !== -1) {
+    if (src.indexOf(old_str, first + 1) !== -1) {
+      return { error: `old_str not unique — add surrounding context to disambiguate.` }
+    }
+    return [first, first + old_str.length]
+  }
+  const fuzzy = fuzzyRange(src, old_str)
+  if (fuzzy) return fuzzy
+  return { error: `old_str not found.${nearMiss(src, old_str)}` }
+}
+
+/**
+ * Batch edit: resolve every edit against the ORIGINAL buffer, reject overlaps,
+ * then apply right-to-left so earlier offsets stay valid. All-or-nothing — if
+ * any edit fails to resolve or two edits overlap, nothing is written.
+ */
+export function applyBatch(src: string, edits: EditSpec[]): { out: string; count: number } | { error: string } {
+  const ranges: Array<{ start: number; end: number; new_str: string }> = []
+  for (let i = 0; i < edits.length; i++) {
+    const { old_str, new_str } = edits[i]
+    if (typeof old_str !== 'string' || typeof new_str !== 'string') {
+      return { error: `edits[${i}] must have string old_str and new_str.` }
+    }
+    if (old_str === '') return { error: `edits[${i}].old_str is empty.` }
+    if (old_str === new_str) return { error: `edits[${i}] old_str and new_str are identical — nothing to change.` }
+    const r = locate(src, old_str)
+    if (!Array.isArray(r)) return { error: `edits[${i}]: ${r.error}` }
+    ranges.push({ start: r[0], end: r[1], new_str })
+  }
+  const sorted = [...ranges].sort((a, b) => a.start - b.start)
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i].start < sorted[i - 1].end) {
+      return { error: `edits overlap in the file — split them into separate calls or widen the context.` }
+    }
+  }
+  let out = src
+  for (const r of [...ranges].sort((a, b) => b.start - a.start)) {
+    out = out.slice(0, r.start) + r.new_str + out.slice(r.end)
+  }
+  return { out, count: ranges.length }
+}
+
 export const edit_file: Tool<Input> = {
   name: 'edit_file',
   description:
-    'Replace an exact string in a file. old_str must be unique unless replace_all is set. On no match, returns the closest text in the file.',
+    'Replace an exact string in a file. old_str must be unique unless replace_all is set. On no match, returns the closest text in the file. To make several edits to one file at once, pass an `edits` array of {old_str,new_str} — they apply atomically (all or nothing).',
   input_schema: {
     type: 'object',
     properties: {
       path:        { type: 'string', description: 'File path' },
-      old_str:     { type: 'string', description: 'Exact text to replace (whitespace-sensitive)' },
-      new_str:     { type: 'string', description: 'Replacement text' },
+      old_str:     { type: 'string', description: 'Exact text to replace (whitespace-sensitive). Omit when using edits[].' },
+      new_str:     { type: 'string', description: 'Replacement text. Omit when using edits[].' },
       replace_all: { type: 'boolean', description: 'Replace every occurrence instead of requiring uniqueness' },
+      edits: {
+        type: 'array',
+        description: 'Batch mode: several edits applied atomically. Each old_str must be unique in the file. Alternative to old_str/new_str.',
+        items: {
+          type: 'object',
+          properties: {
+            old_str: { type: 'string', description: 'Exact text to replace (whitespace-sensitive)' },
+            new_str: { type: 'string', description: 'Replacement text' },
+          },
+          required: ['old_str', 'new_str'],
+        },
+      },
     },
-    required: ['path', 'old_str', 'new_str'],
+    required: ['path'],
   },
-  handler: ({ path, old_str, new_str, replace_all }) => {
+  handler: ({ path, old_str, new_str, replace_all, edits }) => {
     try {
+      // Batch mode: resolve + apply all edits atomically against the original.
+      if (Array.isArray(edits) && edits.length > 0) {
+        const abs = confinePath(path)
+        const src = readFileSync(abs, 'utf-8')
+        const res = applyBatch(src, edits)
+        if ('error' in res) return { content: `${res.error} (in ${path})`, is_error: true }
+        writeFileSync(abs, res.out, 'utf-8')
+        return { content: `Edited ${path} (${res.count} edits).${verifyHint(path)}` }
+      }
+      if (typeof old_str !== 'string' || typeof new_str !== 'string') {
+        return { content: `edit_file needs old_str and new_str (or an edits[] array) for ${path}.`, is_error: true }
+      }
       if (old_str === new_str) {
         return {
           content: `old_str and new_str are identical — nothing to change in ${path}. If the file is already correct, do NOT edit again: finish with the respond action and tell the user it is done.`,

src/tools/read_file.ts

@@ -16,6 +16,26 @@ function numbered(lines: string[], start: number): string {
     .join('\n')
 }
 
+// Raster formats a vision model can consume. SVG is intentionally excluded — it
+// is text, so it falls through to the normal text path (and is more useful read
+// as source anyway).
+const IMAGE_EXT = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp'])
+// Base64 roughly quadruples size and rides in the prompt; refuse oversized images
+// rather than blow the context window.
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024
+
+/** Sniff the leading magic bytes so an image with a wrong/missing extension is still caught. */
+function looksImage(buf: Buffer): boolean {
+  if (buf.length < 4) return false
+  if (buf[0] === 0x89 && buf[1] === 0x50) return true // PNG
+  if (buf[0] === 0xff && buf[1] === 0xd8) return true // JPEG
+  if (buf[0] === 0x47 && buf[1] === 0x49) return true // GIF
+  if (buf[0] === 0x42 && buf[1] === 0x4d) return true // BMP
+  // WEBP: "RIFF"...."WEBP"
+  if (buf.length >= 12 && buf.toString('ascii', 0, 4) === 'RIFF' && buf.toString('ascii', 8, 12) === 'WEBP') return true
+  return false
+}
+
 export const read_file: Tool<Input> = {
   name: 'read_file',
   description:
@@ -33,6 +53,23 @@ export const read_file: Tool<Input> = {
     try {
       const MAX_CHARS = 200_000
       const buf = readFileSync(confinePath(path))
+
+      // Image: hand the raw pixels back as a base64 attachment for a vision model
+      // rather than refusing it as binary. Extension OR magic bytes qualifies.
+      const ext = path.slice(path.lastIndexOf('.') + 1).toLowerCase()
+      if (IMAGE_EXT.has(ext) || looksImage(buf)) {
+        if (buf.length > MAX_IMAGE_BYTES) {
+          return {
+            content: `${path} is an image but too large to attach (${buf.length} bytes > ${MAX_IMAGE_BYTES}). Resize it first.`,
+            is_error: true,
+          }
+        }
+        return {
+          content: `[image ${path} — ${buf.length} bytes, attached for viewing]`,
+          images: [buf.toString('base64')],
+        }
+      }
+
       // Refuse binary — NUL byte in the head is the cheap, reliable signal.
       if (buf.subarray(0, 8000).includes(0)) {
         return { content: `${path} looks binary (${buf.length} bytes); not reading as text.`, is_error: true }

src/tools/run_bash.ts

@@ -7,6 +7,26 @@ interface Input {
   timeout_ms?: number
 }
 
+/**
+ * Kill the whole process tree rooted at `pid`, not just the direct child.
+ * execa's built-in timeout only SIGTERMs the shell we spawned — a `bash -c`
+ * that forked a build/test process leaves that grandchild running. On POSIX we
+ * spawn detached (child is its own process-group leader) so a negative-pid kill
+ * takes out the group; on Windows we shell out to taskkill /T.
+ */
+function killTree(pid: number | undefined, isWin: boolean): void {
+  if (!pid) return
+  try {
+    if (isWin) {
+      execa('taskkill', ['/pid', String(pid), '/T', '/F'], { reject: false })
+    } else {
+      process.kill(-pid, 'SIGKILL')
+    }
+  } catch {
+    /* process already gone — nothing to kill */
+  }
+}
+
 export const run_bash: Tool<Input> = {
   name: 'run_bash',
   description: 'Execute a shell command (bash on Unix, cmd on Windows). Returns stdout+stderr. Non-interactive only.',
@@ -18,26 +38,50 @@ export const run_bash: Tool<Input> = {
     },
     required: ['command'],
   },
-  handler: async ({ command, timeout_ms }) => {
+  handler: async ({ command, timeout_ms }, ctx) => {
+    const isWin = process.platform === 'win32'
+    const shell = isWin ? 'cmd' : 'bash'
+    const shellArgs = isWin ? ['/c', command] : ['-c', command]
+    const timeout = timeout_ms ?? 120000
+
+    // Own timeout + tree-kill instead of execa's `timeout` so a forked grandchild
+    // process can't outlive the call. `all:true` interleaves stdout/stderr in the
+    // real order they were written (the old filter+join lost that ordering).
+    const child = execa(shell, shellArgs, {
+      reject: false,
+      all: true,
+      detached: !isWin, // POSIX: new process group so killTree(-pid) hits the whole tree
+    })
+
+    let timedOut = false
+    let aborted = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      killTree(child.pid, isWin)
+    }, timeout)
+    const onAbort = () => {
+      aborted = true
+      killTree(child.pid, isWin)
+    }
+    ctx?.signal?.addEventListener('abort', onAbort, { once: true })
+
     try {
-      const isWin = process.platform === 'win32'
-      const shell = isWin ? 'cmd' : 'bash'
-      const shellArgs = isWin ? ['/c', command] : ['-c', command]
-      const { stdout, stderr, exitCode } = await execa(shell, shellArgs, {
-        timeout: timeout_ms ?? 120000,
-        reject: false,
-        all: false,
-      })
-      const out = [stdout, stderr].filter(Boolean).join('\n')
-      const is_error = exitCode !== 0
+      const { all, exitCode } = await child
+      const out = all ?? ''
+      const is_error = aborted || timedOut || exitCode !== 0
+      const note = timedOut
+        ? `\n[timed out after ${timeout}ms — process tree killed]`
+        : aborted
+          ? `\n[aborted — process tree killed]`
+          : ''
       const body = out || (is_error ? `(no output)` : '')
-      const content = `${spillIfLarge(body, 'command output')}\n[exit ${exitCode}]`
-      return {
-        content,
-        is_error,
-      }
+      const content = `${spillIfLarge(body, 'command output')}\n[exit ${exitCode ?? 'killed'}]${note}`
+      return { content, is_error }
     } catch (err) {
       return { content: err instanceof Error ? err.message : String(err), is_error: true }
+    } finally {
+      clearTimeout(timer)
+      ctx?.signal?.removeEventListener('abort', onAbort)
     }
   },
 }