mini-coder 0.5.10 → 0.5.12

package/src/tools.ts

@@ -1,6 +1,9 @@
 /**
- * Built-in tool implementations: `edit`, `shell`, `todoWrite`, `todoRead`,
- * and `readImage`.
+ * Built-in tool implementations: `shell`, `read`, `grep`, `edit`, `todoWrite`,
+ * `todoRead`, and `readImage`.
+ *
+ * Shell, read, and grep live in dedicated modules and are re-exported here so
+ * the rest of the codebase can keep a single built-in-tools import surface.
  *
  * Each tool is exposed as a pure-ish execute function that takes typed
  * arguments and a working directory, returning a result object. The pi-ai
@@ -13,36 +16,55 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, extname, isAbsolute, join } from "node:path";
 import type {
-  ImageContent,
   Message,
+  Static,
   TextContent,
   Tool,
   ToolResultMessage,
 } from "@mariozechner/pi-ai";
 import { Type } from "@mariozechner/pi-ai";
-import type { ToolUpdateCallback } from "./agent.ts";
-
-// ---------------------------------------------------------------------------
-// Result type
-// ---------------------------------------------------------------------------
-
-/**
- * Result from executing a tool.
- *
- * Content blocks carry either text or image data. The agent loop
- * maps these directly into {@link ToolResultMessage.content}.
- */
-export interface ToolExecResult {
-  /** Content blocks for the tool result (text and/or images). */
-  content: (TextContent | ImageContent)[];
-  /** Whether the execution encountered an error. */
-  isError: boolean;
-}
-
-/** Convenience: build a text-only {@link ToolExecResult}. */
-function textResult(text: string, isError: boolean): ToolExecResult {
-  return { content: [{ type: "text", text }], isError };
-}
+import type { ToolHandler } from "./agent.ts";
+import {
+  detectLineEnding,
+  normalizeLineEndings,
+  type ToolExecResult,
+  textResult,
+  validateBuiltinToolArgs,
+} from "./tool-common.ts";
+
+export type { ToolExecResult } from "./tool-common.ts";
+export {
+  DEFAULT_GREP_LIMIT,
+  executeGrep,
+  type GrepArgs,
+  type GrepOpts,
+  type GrepResult,
+  type GrepResultFile,
+  type GrepResultLine,
+  grepTool,
+  grepToolHandler,
+  parseGrepResult,
+} from "./tool-grep.ts";
+export {
+  DEFAULT_READ_LIMIT,
+  executeRead,
+  formatReadContinuationHint,
+  parseReadContinuationHint,
+  parseReadResult,
+  type ReadArgs,
+  type ReadContinuationHint,
+  type ReadOpts,
+  readTool,
+  readToolHandler,
+} from "./tool-read.ts";
+export {
+  executeShell,
+  type ShellArgs,
+  type ShellOpts,
+  shellTool,
+  shellToolHandler,
+  truncateOutput,
+} from "./tool-shell.ts";
 
 /** Persisted todo status values shown to the user and stored in snapshots. */
 export type TodoStatus = "pending" | "in_progress" | "completed";
@@ -58,18 +80,36 @@ export interface TodoItem {
   status: TodoStatus;
 }
 
-interface TodoWriteInputItem {
-  /** Task description used as the matching key. */
-  content: string;
-  /** Requested next status for the task. */
-  status: TodoWriteStatus;
-}
+const todoWriteToolParameters = Type.Object({
+  todos: Type.Array(
+    Type.Object({
+      content: Type.String({
+        description: "Task description used as the matching key",
+      }),
+      status: Type.Union(
+        [
+          Type.Literal("pending"),
+          Type.Literal("in_progress"),
+          Type.Literal("completed"),
+          Type.Literal("cancelled"),
+        ],
+        {
+          description:
+            "Task status. Use `cancelled` to remove the item entirely.",
+        },
+      ),
+    }),
+    {
+      description:
+        "List of todo items to create, update, or remove. Only send the items that changed.",
+    },
+  ),
+});
 
 /** Arguments for the `todoWrite` tool. */
-export interface TodoWriteArgs {
-  /** Todo items to create, update, or remove. */
-  todos: TodoWriteInputItem[];
-}
+export type TodoWriteArgs = Static<typeof todoWriteToolParameters>;
+
+const todoReadToolParameters = Type.Object({});
 
 const MAX_TODO_CONTENT_LENGTH = 1_000;
 
@@ -229,26 +269,6 @@ export function executeTodoRead(
   return textResult(formatTodoSnapshot(getTodoItems(messages)), false);
 }
 
-function detectLineEnding(content: string): "\n" | "\r\n" | null {
-  if (content.includes("\r\n")) {
-    return "\r\n";
-  }
-  if (content.includes("\n")) {
-    return "\n";
-  }
-  return null;
-}
-
-function normalizeLineEndings(
-  content: string,
-  lineEnding: "\n" | "\r\n",
-): string {
-  if (lineEnding === "\r\n") {
-    return content.replace(/\r?\n/g, "\r\n");
-  }
-  return content.replace(/\r\n/g, "\n");
-}
-
 const MAX_EDIT_ERROR_MATCHES = 3;
 const MAX_EDIT_ERROR_SNIPPET_LINES = 8;
 const MAX_EDIT_ERROR_SNIPPET_LINE_CHARS = 160;
@@ -567,15 +587,21 @@ function formatEditMultipleMatchesError(
 // edit
 // ---------------------------------------------------------------------------
 
+const editToolParameters = Type.Object({
+  path: Type.String({
+    description: "File path (absolute or relative to cwd)",
+  }),
+  oldText: Type.String({
+    description:
+      'Exact text to find and replace. Empty string means "create new file".',
+  }),
+  newText: Type.String({
+    description: "Replacement text (or full content for new files)",
+  }),
+});
+
 /** Arguments for the `edit` tool. */
-interface EditArgs {
-  /** File path (absolute or relative to cwd). */
-  path: string;
-  /** Exact text to find. Empty string means "create new file". */
-  oldText: string;
-  /** Replacement text (or full content for new files). */
-  newText: string;
-}
+export type EditArgs = Static<typeof editToolParameters>;
 
 /**
  * Execute an exact-text replacement in a single file.
@@ -660,927 +686,6 @@ export function executeEdit(args: EditArgs, cwd: string): ToolExecResult {
   return textResult(`Edited ${args.path}`, false);
 }
 
-// ---------------------------------------------------------------------------
-// shell
-// ---------------------------------------------------------------------------
-
-/** Arguments for the `shell` tool. */
-interface ShellArgs {
-  /** The command to run. */
-  command: string;
-}
-
-/** Options for shell execution. */
-interface ShellOpts {
-  /** Maximum output lines before truncation. Default: 1000. */
-  maxLines?: number;
-  /** Maximum UTF-8 bytes before truncation. Default: 50_000. */
-  maxBytes?: number;
-  /** Abort signal to cancel the command. */
-  signal?: AbortSignal;
-  /** Callback for progressive output updates while the command is running. */
-  onUpdate?: ToolUpdateCallback;
-}
-
-type ShellProcess = ReturnType<typeof Bun.spawn>;
-
-const DEFAULT_MAX_LINES = 1000;
-const DEFAULT_MAX_BYTES = 50_000;
-const SHELL_UPDATE_INTERVAL_MS = 75;
-const SHELL_STREAM_DRAIN_TIMEOUT_MS = 25;
-
-/** Format combined stdout/stderr for display in tool results. */
-function formatShellOutput(stdout: string, stderr: string): string {
-  if (stdout && stderr) {
-    return `${stdout}\n\n[stderr]\n${stderr}`;
-  }
-  if (stdout) {
-    return stdout;
-  }
-  if (stderr) {
-    return `[stderr]\n${stderr}`;
-  }
-  return "";
-}
-
-interface ShellCommandLines {
-  lines: string[];
-  lineEnding: "\n" | "\r\n";
-  hasTrailingLineEnding: boolean;
-}
-
-interface PendingHeredoc {
-  startLineIndex: number;
-  delimiter: string;
-  stripLeadingTabs: boolean;
-}
-
-interface ShellQuoteState {
-  quote: "'" | '"' | null;
-  escaped: boolean;
-}
-
-function splitShellCommandLines(command: string): ShellCommandLines {
-  const lineEnding = detectLineEnding(command) ?? "\n";
-  const normalized = normalizeLineEndings(command, "\n");
-  const hasTrailingLineEnding = normalized.endsWith("\n");
-  const lines = normalized.split("\n");
-  if (hasTrailingLineEnding) {
-    lines.pop();
-  }
-  return { lines, lineEnding, hasTrailingLineEnding };
-}
-
-function joinShellCommandLines(parts: ShellCommandLines): string {
-  const joined = parts.lines.join(parts.lineEnding);
-  if (parts.hasTrailingLineEnding) {
-    return joined + parts.lineEnding;
-  }
-  return joined;
-}
-
-function advanceShellQuoteState(char: string, state: ShellQuoteState): boolean {
-  if (state.quote === "'") {
-    if (char === "'") {
-      state.quote = null;
-    }
-    return true;
-  }
-
-  if (state.quote === '"') {
-    if (state.escaped) {
-      state.escaped = false;
-      return true;
-    }
-    if (char === "\\") {
-      state.escaped = true;
-      return true;
-    }
-    if (char === '"') {
-      state.quote = null;
-    }
-    return true;
-  }
-
-  if (char === "'") {
-    state.quote = "'";
-    return true;
-  }
-  if (char === '"') {
-    state.quote = '"';
-    return true;
-  }
-
-  return false;
-}
-
-function isHeredocPrefixCharacter(char: string): boolean {
-  return (
-    char === "" ||
-    char === " " ||
-    char === "\t" ||
-    char === ";" ||
-    char === "(" ||
-    char === "&" ||
-    char === "|"
-  );
-}
-
-function getHeredocStartAt(
-  line: string,
-  index: number,
-): { index: number; stripLeadingTabs: boolean } | null {
-  if (line[index] !== "<" || line[index + 1] !== "<") {
-    return null;
-  }
-
-  const previousChar = index === 0 ? "" : (line[index - 1] ?? "");
-  if (!isHeredocPrefixCharacter(previousChar)) {
-    return null;
-  }
-
-  return {
-    index,
-    stripLeadingTabs: line[index + 2] === "-",
-  };
-}
-
-function findUnquotedHeredocStart(
-  line: string,
-): { index: number; stripLeadingTabs: boolean } | null {
-  const quoteState: ShellQuoteState = { quote: null, escaped: false };
-  let heredocStart: { index: number; stripLeadingTabs: boolean } | null = null;
-
-  for (let index = 0; index < line.length - 1; index++) {
-    const char = line[index];
-    if (char === undefined || advanceShellQuoteState(char, quoteState)) {
-      continue;
-    }
-
-    const nextHeredocStart = getHeredocStartAt(line, index);
-    if (!nextHeredocStart) {
-      continue;
-    }
-    if (heredocStart) {
-      return null;
-    }
-
-    heredocStart = nextHeredocStart;
-    index += heredocStart.stripLeadingTabs ? 2 : 1;
-  }
-
-  return heredocStart;
-}
-
-function skipHeredocDelimiterWhitespace(line: string, cursor: number): number {
-  let nextCursor = cursor;
-  while (line[nextCursor] === " " || line[nextCursor] === "\t") {
-    nextCursor++;
-  }
-  return nextCursor;
-}
-
-function readQuotedHeredocDelimiter(
-  line: string,
-  cursor: number,
-): string | null {
-  const quote = line[cursor];
-  if (quote !== "'" && quote !== '"') {
-    return null;
-  }
-
-  const endQuoteIndex = line.indexOf(quote, cursor + 1);
-  if (endQuoteIndex === -1) {
-    return null;
-  }
-  return line.slice(cursor + 1, endQuoteIndex);
-}
-
-function isHeredocDelimiterStopCharacter(char: string): boolean {
-  return (
-    char === " " ||
-    char === "\t" ||
-    char === "<" ||
-    char === ">" ||
-    char === "&" ||
-    char === "|" ||
-    char === ";" ||
-    char === "(" ||
-    char === ")"
-  );
-}
-
-function readBareHeredocDelimiter(line: string, cursor: number): string | null {
-  const startChar = line[cursor];
-  if (startChar === undefined || !/[A-Za-z_]/.test(startChar)) {
-    return null;
-  }
-
-  let endIndex = cursor;
-  while (endIndex < line.length) {
-    const currentChar = line[endIndex];
-    if (
-      currentChar === undefined ||
-      isHeredocDelimiterStopCharacter(currentChar)
-    ) {
-      break;
-    }
-    endIndex++;
-  }
-  return line.slice(cursor, endIndex);
-}
-
-function findUnquotedHeredoc(
-  line: string,
-  startLineIndex: number,
-): PendingHeredoc | null {
-  const heredocStart = findUnquotedHeredocStart(line);
-  if (!heredocStart) {
-    return null;
-  }
-
-  const cursor = skipHeredocDelimiterWhitespace(
-    line,
-    heredocStart.index + 2 + (heredocStart.stripLeadingTabs ? 1 : 0),
-  );
-  const delimiter =
-    readQuotedHeredocDelimiter(line, cursor) ??
-    readBareHeredocDelimiter(line, cursor);
-  if (!delimiter) {
-    return null;
-  }
-
-  return {
-    startLineIndex,
-    delimiter,
-    stripLeadingTabs: heredocStart.stripLeadingTabs,
-  };
-}
-
-function getHeredocLineBody(line: string, stripLeadingTabs: boolean): string {
-  if (!stripLeadingTabs) {
-    return line;
-  }
-  return line.replace(/^\t+/, "");
-}
-
-function getSupportedHeredocTrailer(rest: string): string | null {
-  const trimmedRest = rest.trimStart();
-  if (!trimmedRest) {
-    return null;
-  }
-  if (trimmedRest.startsWith("&&")) {
-    return trimmedRest.slice(2).trim() ? rest : null;
-  }
-  if (trimmedRest.startsWith("||")) {
-    return null;
-  }
-  if (trimmedRest.startsWith("|")) {
-    return trimmedRest.slice(1).trim() ? rest : null;
-  }
-  if (trimmedRest.startsWith(">")) {
-    return trimmedRest.slice(1).trim() ? rest : null;
-  }
-  return null;
-}
-
-function rewritePendingHeredocTrailer(
-  parts: ShellCommandLines,
-  line: string,
-  lineIndex: number,
-  pendingHeredoc: PendingHeredoc,
-): PendingHeredoc | null {
-  const body = getHeredocLineBody(line, pendingHeredoc.stripLeadingTabs);
-  if (body === pendingHeredoc.delimiter) {
-    return null;
-  }
-  if (!body.startsWith(pendingHeredoc.delimiter)) {
-    return pendingHeredoc;
-  }
-
-  const trailer = getSupportedHeredocTrailer(
-    body.slice(pendingHeredoc.delimiter.length),
-  );
-  if (!trailer) {
-    return pendingHeredoc;
-  }
-
-  const startLine = parts.lines[pendingHeredoc.startLineIndex];
-  if (startLine === undefined) {
-    return pendingHeredoc;
-  }
-
-  parts.lines[pendingHeredoc.startLineIndex] = startLine + trailer;
-  const leadingTabs = pendingHeredoc.stripLeadingTabs
-    ? (line.match(/^\t*/) ?? [""])[0]
-    : "";
-  parts.lines[lineIndex] = `${leadingTabs}${pendingHeredoc.delimiter}`;
-  return null;
-}
-
-function normalizeHeredocTrailingContinuations(command: string): string {
-  const parts = splitShellCommandLines(command);
-  let pendingHeredoc: PendingHeredoc | null = null;
-
-  for (const [index, line] of parts.lines.entries()) {
-    if (pendingHeredoc) {
-      pendingHeredoc = rewritePendingHeredocTrailer(
-        parts,
-        line,
-        index,
-        pendingHeredoc,
-      );
-      continue;
-    }
-
-    pendingHeredoc = findUnquotedHeredoc(line, index);
-  }
-
-  return joinShellCommandLines(parts);
-}
-
-function normalizeLeadingDashPrintf(command: string): string {
-  const parts = splitShellCommandLines(command);
-  let pendingHeredoc: PendingHeredoc | null = null;
-
-  for (const [index, line] of parts.lines.entries()) {
-    if (pendingHeredoc) {
-      const body = getHeredocLineBody(line, pendingHeredoc.stripLeadingTabs);
-      if (body === pendingHeredoc.delimiter) {
-        pendingHeredoc = null;
-      }
-      continue;
-    }
-
-    parts.lines[index] = line.replace(
-      /^(\s*)printf(\s+)(['"])-/,
-      "$1printf$2-- $3-",
-    );
-    pendingHeredoc = findUnquotedHeredoc(parts.lines[index] || "", index);
-  }
-
-  return joinShellCommandLines(parts);
-}
-
-function normalizeShellCommand(command: string): string {
-  try {
-    return normalizeLeadingDashPrintf(
-      normalizeHeredocTrailingContinuations(command),
-    );
-  } catch {
-    return command;
-  }
-}
-
-interface ShellStreamCapture {
-  done: Promise<void>;
-  getOutput: () => string;
-  isFinished: () => boolean;
-  close: () => Promise<void>;
-}
-
-function startShellStreamCapture(
-  stream: ReadableStream<Uint8Array>,
-  onChunk: (chunk: string) => void,
-): ShellStreamCapture {
-  const reader = stream.getReader();
-  const decoder = new TextDecoder();
-  let output = "";
-  let closed = false;
-  let finished = false;
-
-  const done = (async (): Promise<void> => {
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) {
-          break;
-        }
-
-        const chunk = decoder.decode(value, { stream: true });
-        output += chunk;
-        onChunk(chunk);
-      }
-    } catch (error) {
-      if (!closed) {
-        throw error;
-      }
-    } finally {
-      const trailing = decoder.decode();
-      output += trailing;
-      onChunk(trailing);
-      finished = true;
-    }
-  })();
-
-  return {
-    done,
-    getOutput: () => output,
-    isFinished: () => finished,
-    close: async (): Promise<void> => {
-      if (!finished) {
-        closed = true;
-        try {
-          await reader.cancel();
-        } catch {
-          // Ignore cancellation errors while closing the pipe after exit/abort.
-        }
-      }
-      await done;
-    },
-  };
-}
-
-async function finalizeShellStreamCaptures(
-  captures: readonly ShellStreamCapture[],
-): Promise<void> {
-  const pending = captures
-    .filter((capture) => !capture.isFinished())
-    .map((capture) => capture.done);
-
-  if (pending.length > 0) {
-    await new Promise<void>((resolve) => {
-      const timer = setTimeout(resolve, SHELL_STREAM_DRAIN_TIMEOUT_MS);
-      void Promise.allSettled(pending).then(() => {
-        clearTimeout(timer);
-        resolve();
-      });
-    });
-  }
-
-  await Promise.all(captures.map((capture) => capture.close()));
-}
-
-function buildShellSpawnOptions(cwd: string): Parameters<typeof Bun.spawn>[1] {
-  return {
-    cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-    ...(process.platform === "win32" ? {} : { detached: true }),
-  };
-}
-
-function abortShellProcess(proc: ShellProcess): void {
-  if (proc.killed || proc.exitCode !== null) {
-    return;
-  }
-
-  if (process.platform !== "win32") {
-    try {
-      process.kill(-proc.pid, "SIGTERM");
-      return;
-    } catch {
-      // Fall through to a direct kill when the process group is unavailable.
-    }
-  }
-
-  proc.kill("SIGTERM");
-}
-
-function registerShellAbort(
-  signal: AbortSignal | undefined,
-  proc: ShellProcess,
-): (() => void) | null {
-  if (!signal) {
-    return null;
-  }
-
-  const abortListener = (): void => {
-    abortShellProcess(proc);
-  };
-
-  if (signal.aborted) {
-    abortShellProcess(proc);
-    return null;
-  }
-
-  signal.addEventListener("abort", abortListener, { once: true });
-  return () => {
-    signal.removeEventListener("abort", abortListener);
-  };
-}
-
-/**
- * Run a command in the user's shell.
- *
- * Executes via `$SHELL -c` (falling back to `/bin/sh`). Returns combined
- * stdout/stderr and the exit code. Large output is truncated to keep
- * head + tail lines with a middle marker.
- *
- * @param args - Shell arguments (command).
- * @param cwd - Working directory to run the command in.
- * @param opts - Optional execution options (maxLines, signal, onUpdate).
- * @returns A {@link ToolExecResult} with the command output.
- */
-export async function executeShell(
-  args: ShellArgs,
-  cwd: string,
-  opts?: ShellOpts,
-): Promise<ToolExecResult> {
-  const shell = process.env.SHELL || "/bin/sh";
-  const maxLines = opts?.maxLines ?? DEFAULT_MAX_LINES;
-  const maxBytes = opts?.maxBytes ?? DEFAULT_MAX_BYTES;
-  let updateTimer: ReturnType<typeof setTimeout> | null = null;
-  let cleanupAbort: (() => void) | null = null;
-  let lastReportedOutput = "";
-  let lastReportAt = 0;
-  let stdoutCapture: ShellStreamCapture | null = null;
-  let stderrCapture: ShellStreamCapture | null = null;
-
-  try {
-    const clearPendingUpdate = (): void => {
-      if (updateTimer) {
-        clearTimeout(updateTimer);
-        updateTimer = null;
-      }
-    };
-
-    const buildOutput = (trimEnd: boolean): string => {
-      const stdout = stdoutCapture?.getOutput() ?? "";
-      const stderr = stderrCapture?.getOutput() ?? "";
-      return truncateOutput(
-        formatShellOutput(
-          trimEnd ? stdout.trimEnd() : stdout,
-          trimEnd ? stderr.trimEnd() : stderr,
-        ),
-        maxLines,
-        maxBytes,
-      );
-    };
-
-    const emitUpdate = (): void => {
-      clearPendingUpdate();
-      if (!opts?.onUpdate) {
-        return;
-      }
-
-      const output = buildOutput(false);
-      if (!output || output === lastReportedOutput) {
-        return;
-      }
-
-      lastReportedOutput = output;
-      lastReportAt = Date.now();
-      opts.onUpdate(textResult(output, false));
-    };
-
-    const scheduleUpdate = (): void => {
-      if (!opts?.onUpdate) {
-        return;
-      }
-
-      const elapsed = Date.now() - lastReportAt;
-      if (elapsed >= SHELL_UPDATE_INTERVAL_MS) {
-        emitUpdate();
-        return;
-      }
-      if (updateTimer) {
-        return;
-      }
-
-      updateTimer = setTimeout(() => {
-        emitUpdate();
-      }, SHELL_UPDATE_INTERVAL_MS - elapsed);
-    };
-
-    const command = normalizeShellCommand(args.command);
-    const proc = Bun.spawn([shell, "-c", command], buildShellSpawnOptions(cwd));
-    cleanupAbort = registerShellAbort(opts?.signal, proc);
-    stdoutCapture = startShellStreamCapture(
-      proc.stdout as ReadableStream<Uint8Array>,
-      () => {
-        scheduleUpdate();
-      },
-    );
-    stderrCapture = startShellStreamCapture(
-      proc.stderr as ReadableStream<Uint8Array>,
-      () => {
-        scheduleUpdate();
-      },
-    );
-
-    const exitCode = await proc.exited;
-    cleanupAbort?.();
-    cleanupAbort = null;
-
-    await finalizeShellStreamCaptures([stdoutCapture, stderrCapture]);
-    clearPendingUpdate();
-    const output = buildOutput(true);
-    if (opts?.onUpdate && output && output !== lastReportedOutput) {
-      lastReportedOutput = output;
-      opts.onUpdate(textResult(output, false));
-    }
-
-    const isError = exitCode !== 0;
-    const body = output || "(no output)";
-    return textResult(`Exit code: ${exitCode}\n${body}`, isError);
-  } catch (err) {
-    cleanupAbort?.();
-    cleanupAbort = null;
-    const captures = [stdoutCapture, stderrCapture].filter(
-      (capture): capture is ShellStreamCapture => capture !== null,
-    );
-    if (captures.length > 0) {
-      await Promise.allSettled(captures.map((capture) => capture.close()));
-    }
-    if (updateTimer) {
-      clearTimeout(updateTimer);
-      updateTimer = null;
-    }
-    const message = err instanceof Error ? err.message : String(err);
-    return textResult(`Shell error: ${message}`, true);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Output truncation
-// ---------------------------------------------------------------------------
-
-/** Build line-limited head/tail segments and their truncation marker. */
-function buildLineTruncation(
-  output: string,
-  maxLines: number,
-): {
-  head: string;
-  tail: string;
-  marker: string;
-} | null {
-  const lines = output.split("\n");
-  if (lines.length <= maxLines) {
-    return null;
-  }
-
-  const headCount = Math.ceil(maxLines / 2);
-  const tailCount = Math.floor(maxLines / 2);
-  const omitted = lines.length - headCount - tailCount;
-
-  return {
-    head: lines.slice(0, headCount).join("\n"),
-    tail: lines.slice(lines.length - tailCount).join("\n"),
-    marker: `\n… truncated ${omitted} lines …\n`,
-  };
-}
-
-function isHighSurrogate(codeUnit: number): boolean {
-  return codeUnit >= 0xd800 && codeUnit <= 0xdbff;
-}
-
-function isLowSurrogate(codeUnit: number): boolean {
-  return codeUnit >= 0xdc00 && codeUnit <= 0xdfff;
-}
-
-function findUtf8SliceLength(
-  input: string,
-  maxBytes: number,
-  getCandidate: (length: number) => string,
-): number {
-  if (maxBytes <= 0 || input === "") {
-    return 0;
-  }
-
-  let low = 0;
-  let high = input.length;
-  while (low < high) {
-    const mid = Math.ceil((low + high) / 2);
-    const candidate = getCandidate(mid);
-    if (Buffer.byteLength(candidate, "utf8") <= maxBytes) {
-      low = mid;
-    } else {
-      high = mid - 1;
-    }
-  }
-
-  return low;
-}
-
-function normalizeUtf8PrefixEnd(input: string, end: number): number {
-  if (end <= 0 || end >= input.length) {
-    return end;
-  }
-
-  const previousCodeUnit = input.charCodeAt(end - 1);
-  const nextCodeUnit = input.charCodeAt(end);
-  if (isHighSurrogate(previousCodeUnit) && isLowSurrogate(nextCodeUnit)) {
-    return end - 1;
-  }
-
-  return end;
-}
-
-function normalizeUtf8SuffixStart(input: string, start: number): number {
-  if (start <= 0 || start >= input.length) {
-    return start;
-  }
-
-  const previousCodeUnit = input.charCodeAt(start - 1);
-  const nextCodeUnit = input.charCodeAt(start);
-  if (isHighSurrogate(previousCodeUnit) && isLowSurrogate(nextCodeUnit)) {
-    return start + 1;
-  }
-
-  return start;
-}
-
-/** Slice the largest UTF-8 prefix that fits within `maxBytes`. */
-function sliceUtf8Prefix(input: string, maxBytes: number): string {
-  const end = normalizeUtf8PrefixEnd(
-    input,
-    findUtf8SliceLength(input, maxBytes, (length) => input.slice(0, length)),
-  );
-  return input.slice(0, end);
-}
-
-/** Slice the largest UTF-8 suffix that fits within `maxBytes`. */
-function sliceUtf8Suffix(input: string, maxBytes: number): string {
-  const start = normalizeUtf8SuffixStart(
-    input,
-    input.length -
-      findUtf8SliceLength(input, maxBytes, (length) =>
-        input.slice(input.length - length),
-      ),
-  );
-  return input.slice(start);
-}
-
-/** Fit disjoint head/tail segments plus a marker within a UTF-8 byte budget. */
-function fitSegmentsWithinBytes(
-  headSource: string,
-  tailSource: string,
-  marker: string,
-  maxBytes: number,
-): string {
-  const markerBytes = Buffer.byteLength(marker, "utf8");
-  if (markerBytes >= maxBytes) {
-    return sliceUtf8Prefix(headSource, maxBytes);
-  }
-
-  const availableBytes = maxBytes - markerBytes;
-  const headBudget = Math.ceil(availableBytes / 2);
-  const tailBudget = Math.floor(availableBytes / 2);
-
-  let head = sliceUtf8Prefix(headSource, headBudget);
-  let tail = sliceUtf8Suffix(tailSource, tailBudget);
-
-  const usedBytes =
-    Buffer.byteLength(head, "utf8") + Buffer.byteLength(tail, "utf8");
-  let remainingBytes = availableBytes - usedBytes;
-
-  if (remainingBytes > 0) {
-    const headBytes = Buffer.byteLength(head, "utf8");
-    const expandedHead = sliceUtf8Prefix(
-      headSource,
-      headBytes + remainingBytes,
-    );
-    remainingBytes -= Buffer.byteLength(expandedHead, "utf8") - headBytes;
-    head = expandedHead;
-  }
-
-  if (remainingBytes > 0) {
-    const tailBytes = Buffer.byteLength(tail, "utf8");
-    tail = sliceUtf8Suffix(tailSource, tailBytes + remainingBytes);
-  }
-
-  return head + marker + tail;
-}
-
-/** Truncate output by UTF-8 byte size, preserving head and tail text. */
-function truncateOutputByBytes(output: string, maxBytes: number): string {
-  if (Buffer.byteLength(output, "utf8") <= maxBytes) {
-    return output;
-  }
-
-  return fitSegmentsWithinBytes(
-    output,
-    output,
-    "\n… truncated for size …\n",
-    maxBytes,
-  );
-}
-
-/**
- * Truncate output to keep useful head and tail content within line and byte budgets.
- *
- * The line budget avoids flooding the model with very tall outputs, while the
- * byte budget prevents context explosions caused by a small number of very long
- * lines.
- *
- * @param output - The full output string.
- * @param maxLines - Maximum number of content lines to keep.
- * @param maxBytes - Maximum UTF-8 bytes to keep.
- * @returns The (possibly truncated) output string.
- */
-export function truncateOutput(
-  output: string,
-  maxLines: number,
-  maxBytes: number,
-): string {
-  if (!output) return output;
-
-  const lineTruncation = buildLineTruncation(output, maxLines);
-  if (!lineTruncation) {
-    return truncateOutputByBytes(output, maxBytes);
-  }
-
-  const lineLimited =
-    lineTruncation.head + lineTruncation.marker + lineTruncation.tail;
-  if (Buffer.byteLength(lineLimited, "utf8") <= maxBytes) {
-    return lineLimited;
-  }
-
-  return fitSegmentsWithinBytes(
-    lineTruncation.head,
-    lineTruncation.tail,
-    lineTruncation.marker,
-    maxBytes,
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Tool definitions (pi-ai Tool schemas)
-// ---------------------------------------------------------------------------
-
-/** pi-ai tool definition for `edit`. */
-export const editTool: Tool = {
-  name: "edit",
-  description:
-    "Make an exact-text replacement in a single file. " +
-    "Provide the file path, the exact text to find, and the replacement text. " +
-    "The old text must match exactly one location in the file. " +
-    "To create a new file, use an empty old text and the full file content as new text. " +
-    "Use this to write the exact final file content the task requires.",
-  parameters: Type.Object({
-    path: Type.String({
-      description: "File path (absolute or relative to cwd)",
-    }),
-    oldText: Type.String({
-      description:
-        'Exact text to find and replace. Empty string means "create new file".',
-    }),
-    newText: Type.String({
-      description: "Replacement text (or full content for new files)",
-    }),
-  }),
-};
-
-/** pi-ai tool definition for `todoWrite`. */
-export const todoWriteTool: Tool = {
-  name: "todoWrite",
-  description:
-    "Use this tool to create and manage a structured task list for your current coding session. " +
-    "This helps you track progress, organize complex tasks, and keep the user informed. " +
-    "Only send the items that changed; unchanged items stay as they are. " +
-    "Each item must include `content` and `status`, where `status` is one of `pending`, `in_progress`, `completed`, or `cancelled`. " +
-    "Use `cancelled` to remove an item from the list. " +
-    "Mark tasks `in_progress` before starting them and `completed` immediately after verification succeeds.",
-  parameters: Type.Object({
-    todos: Type.Array(
-      Type.Object({
-        content: Type.String({
-          description: "Task description used as the matching key",
-        }),
-        status: Type.Union(
-          [
-            Type.Literal("pending"),
-            Type.Literal("in_progress"),
-            Type.Literal("completed"),
-            Type.Literal("cancelled"),
-          ],
-          {
-            description:
-              "Task status. Use `cancelled` to remove the item entirely.",
-          },
-        ),
-      }),
-      {
-        description:
-          "List of todo items to create, update, or remove. Only send the items that changed.",
-      },
-    ),
-  }),
-};
-
-/** pi-ai tool definition for `todoRead`. */
-export const todoReadTool: Tool = {
-  name: "todoRead",
-  description:
-    "Retrieves the current todo list for this coding session. " +
-    "Use this tool before updating todos when you need to inspect the current list, or when the user asks for the current plan or progress. " +
-    "If no todos exist yet, it returns an empty list.",
-  parameters: Type.Object({}),
-};
-
-/** pi-ai tool definition for `shell`. */
-export const shellTool: Tool = {
-  name: "shell",
-  description:
-    "Run a command in the user's shell. Returns stdout, stderr, and exit code. " +
-    "Use this to explore the codebase, read tests/verifiers/examples, inspect required outputs, and run targeted checks, builds, or git commands. " +
-    "Commands mutate the real working directory, so direct verification outputs to temporary paths or clean them up before finishing.",
-  parameters: Type.Object({
-    command: Type.String({ description: "The shell command to execute" }),
-  }),
-};
-
 // ---------------------------------------------------------------------------
 // readImage
 // ---------------------------------------------------------------------------
@@ -1594,11 +699,14 @@ const IMAGE_MIME_TYPES: Record<string, string> = {
   ".webp": "image/webp",
 };
 
+const readImageToolParameters = Type.Object({
+  path: Type.String({
+    description: "File path (absolute or relative to cwd)",
+  }),
+});
+
 /** Arguments for the `readImage` tool. */
-interface ReadImageArgs {
-  /** File path (absolute or relative to cwd). */
-  path: string;
-}
+export type ReadImageArgs = Static<typeof readImageToolParameters>;
 
 /**
  * Read an image file and return it as base64-encoded content.
@@ -1644,16 +752,99 @@ export function executeReadImage(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Tool definitions (pi-ai Tool schemas)
+// ---------------------------------------------------------------------------
+
+/** pi-ai tool definition for `edit`. */
+export const editTool: Tool<typeof editToolParameters> = {
+  name: "edit",
+  description:
+    "Make an exact-text replacement in a single file. " +
+    "Provide the file path, the exact text to find, and the replacement text. " +
+    "The old text must match exactly one location in the file. " +
+    "To create a new file, use an empty old text and the full file content as new text. " +
+    "Use this to write the exact final file content the task requires.",
+  parameters: editToolParameters,
+};
+
+/**
+ * Tool handler that validates edit arguments before execution.
+ *
+ * @param args - Raw parsed tool-call arguments.
+ * @param cwd - Working directory for path resolution.
+ * @returns The edit tool result.
+ */
+export const editToolHandler: ToolHandler = (args, cwd) =>
+  executeEdit(validateBuiltinToolArgs(editTool, args), cwd);
+
+/** pi-ai tool definition for `todoWrite`. */
+export const todoWriteTool: Tool<typeof todoWriteToolParameters> = {
+  name: "todoWrite",
+  description:
+    "Use this tool to create and manage a structured task list for your current coding session. " +
+    "This helps you track progress, organize complex tasks, and keep the user informed. " +
+    "Only send the items that changed; unchanged items stay as they are. " +
+    "Each item must include `content` and `status`, where `status` is one of `pending`, `in_progress`, `completed`, or `cancelled`. " +
+    "Use `cancelled` to remove an item from the list. " +
+    "Mark tasks `in_progress` before starting them and `completed` immediately after verification succeeds.",
+  parameters: todoWriteToolParameters,
+};
+
+/**
+ * Create a `todoWrite` handler bound to the current persisted message history.
+ *
+ * @param messages - Current persisted message history.
+ * @returns Tool handler for todo writes.
+ */
+export function createTodoWriteToolHandler(
+  messages: readonly TodoHistoryMessage[],
+): ToolHandler {
+  return (args) =>
+    executeTodoWrite(validateBuiltinToolArgs(todoWriteTool, args), messages);
+}
+
+/** pi-ai tool definition for `todoRead`. */
+export const todoReadTool: Tool<typeof todoReadToolParameters> = {
+  name: "todoRead",
+  description:
+    "Retrieves the current todo list for this coding session. " +
+    "Use this tool before updating todos when you need to inspect the current list, or when the user asks for the current plan or progress. " +
+    "If no todos exist yet, it returns an empty list.",
+  parameters: todoReadToolParameters,
+};
+
+/**
+ * Create a `todoRead` handler bound to the current persisted message history.
+ *
+ * @param messages - Current persisted message history.
+ * @returns Tool handler for todo reads.
+ */
+export function createTodoReadToolHandler(
+  messages: readonly TodoHistoryMessage[],
+): ToolHandler {
+  return (args) => {
+    validateBuiltinToolArgs(todoReadTool, args);
+    return executeTodoRead(messages);
+  };
+}
+
 /** pi-ai tool definition for `readImage`. */
-export const readImageTool: Tool = {
+export const readImageTool: Tool<typeof readImageToolParameters> = {
   name: "readImage",
   description:
     "Read an image file and return its contents. " +
     "Supports PNG, JPEG, GIF, and WebP formats. " +
     "Use this to inspect screenshots, diagrams, or any image in the repo.",
-  parameters: Type.Object({
-    path: Type.String({
-      description: "File path (absolute or relative to cwd)",
-    }),
-  }),
+  parameters: readImageToolParameters,
 };
+
+/**
+ * Tool handler that validates image-read arguments before execution.
+ *
+ * @param args - Raw parsed tool-call arguments.
+ * @param cwd - Working directory for path resolution.
+ * @returns The readImage tool result.
+ */
+export const readImageToolHandler: ToolHandler = (args, cwd) =>
+  executeReadImage(validateBuiltinToolArgs(readImageTool, args), cwd);