interference-agent 0.1.0

package/src/tools/bash.ts

@@ -0,0 +1,104 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { decide, requestConfirmation } from "../permissions.ts";
+
+const OUTPUT_CAP = 30_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export const bash = tool({
+  description:
+    "Execute a shell command in the workspace. " +
+    "Use this for git operations, running tests, installing packages, building, etc. " +
+    "Never use interactive commands (no -i, no editors). " +
+    "Explain what the command does before running it.",
+  inputSchema: z.object({
+    command: z.string().describe("The shell command to execute"),
+    timeout: z
+      .number()
+      .int()
+      .min(1_000)
+      .max(300_000)
+      .optional()
+      .describe("Timeout in milliseconds (default: 120000)"),
+  }),
+  execute: async ({ command, timeout }) => {
+    const decision = decide("bash", command);
+    if (decision === "deny") {
+      return `Command denied by policy: '${command}'`;
+    }
+    if (decision === "ask") {
+      const preview = `[bash] ${command}`;
+      const allowed = await requestConfirmation("bash", preview);
+      if (!allowed) {
+        return `Command refused by user: '${command}'`;
+      }
+    }
+
+    const ms = timeout ?? DEFAULT_TIMEOUT_MS;
+    const proc = Bun.spawn(["sh", "-c", command], {
+      cwd: process.cwd(),
+      stdout: "pipe",
+      stderr: "pipe",
+      timeout: ms,
+      killSignal: "SIGTERM",
+    });
+
+    const [stdout, stderr] = await Promise.all([
+      readStream(proc.stdout, OUTPUT_CAP),
+      readStream(proc.stderr, OUTPUT_CAP),
+    ]);
+
+    const exitCode = await proc.exited;
+
+    let output = "";
+    if (stdout.length > 0) output += stdout;
+    if (stderr.length > 0) {
+      if (output.length > 0) output += "\n";
+      output += "[stderr]\n" + stderr;
+    }
+
+    const truncated =
+      stdout.length >= OUTPUT_CAP || stderr.length >= OUTPUT_CAP ? " [output truncated]" : "";
+    const exitInfo = exitCode === 0 ? "" : ` (exit code: ${exitCode})`;
+
+    if (output.length === 0 && exitCode !== 0) {
+      return `Command failed (exit code: ${exitCode}) with no output.`;
+    }
+    if (output.length === 0) {
+      return `Command succeeded (no output).`;
+    }
+
+    return `${output}${truncated}${exitInfo}`;
+  },
+});
+
+async function readStream(
+  stream: ReadableStream | null,
+  cap: number,
+): Promise<string> {
+  if (!stream) return "";
+  const reader = (stream as ReadableStream<Uint8Array>).getReader();
+  const decoder = new TextDecoder();
+  let text = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      text += decoder.decode(value, { stream: true });
+      if (text.length > cap) {
+        text = text.slice(0, cap);
+        reader.cancel();
+        break;
+      }
+    }
+  } catch {
+    // reader cancelled
+  }
+
+  let final: string;
+  try { final = decoder.decode(); } catch { final = ""; }
+  if (final.length > 0 && text.length < cap) text += final;
+
+  return text.slice(0, cap);
+}

package/src/tools/edit.ts

@@ -0,0 +1,98 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { resolveInWorkspace } from "./_fs.ts";
+import { decide, requestConfirmation } from "../permissions.ts";
+import { snapshotFile } from "../session/snapshot.ts";
+import * as path from "node:path";
+
+export const edit = tool({
+  description:
+    "Replace a string in a file with another string. " +
+    "The oldString must match EXACTLY ONCE in the file. " +
+    "If it matches zero or multiple times, the edit fails. " +
+    "Use `replaceAll: true` to replace all occurrences. " +
+    "Prefer this over `write` for targeted changes to existing files.",
+  inputSchema: z.object({
+    path: z.string().describe("Path to the file, relative to workspace root"),
+    oldString: z.string().describe("The exact string to replace"),
+    newString: z.string().describe("The string to replace it with"),
+    replaceAll: z
+      .boolean()
+      .optional()
+      .describe("If true, replace all occurrences instead of just one (default: false)"),
+  }),
+  execute: async ({ path: filePath, oldString, newString, replaceAll }) => {
+    const abs = resolveInWorkspace(filePath);
+    const rel = path.relative(process.cwd(), abs) || abs;
+
+    const decision = decide("edit", filePath);
+    if (decision === "deny") {
+      return `Error: edit denied by policy for '${rel}'`;
+    }
+
+    const f = Bun.file(abs);
+    if (!(await f.exists())) {
+      return `Error: file not found: ${rel}`;
+    }
+
+    const content = await f.text();
+    const count = countOccurrences(content, oldString);
+
+    if (oldString === newString) {
+      return `Error: oldString and newString are identical`;
+    }
+
+    if (count === 0) {
+      return `Error: oldString not found in ${rel}. Ensure the string matches exactly (including whitespace).`;
+    }
+
+    if (!replaceAll && count > 1) {
+      return (
+        `Error: oldString matches ${count} times in ${rel}. Use 'replaceAll: true' to replace all, ` +
+        `or provide more surrounding context to narrow to a single match.`
+      );
+    }
+
+    if (decision === "ask") {
+      const preview = generateEditPreview(rel, oldString, newString, replaceAll ?? false, count);
+      const allowed = await requestConfirmation("edit", preview);
+      if (!allowed) {
+        return `Edit refused by user for '${rel}'`;
+      }
+    }
+
+    const replaced = replaceAll
+      ? content.replaceAll(oldString, newString)
+      : content.replace(oldString, newString);
+
+    await snapshotFile(filePath);
+    await Bun.write(abs, replaced);
+
+    const label = replaceAll ? ` (${count} occurrences)` : "";
+    return `Edited ${rel}${label}`;
+  },
+});
+
+function countOccurrences(haystack: string, needle: string): number {
+  if (needle.length === 0) return 0;
+  let count = 0;
+  let pos = 0;
+  while ((pos = haystack.indexOf(needle, pos)) !== -1) {
+    count++;
+    pos += needle.length;
+  }
+  return count;
+}
+
+function generateEditPreview(
+  file: string,
+  oldS: string,
+  newS: string,
+  replaceAll: boolean,
+  count: number,
+): string {
+  const label = replaceAll ? `replace all (${count} occurrences)` : "replace once";
+  const truncatedOld = oldS.length > 300 ? oldS.slice(0, 300) + "…" : oldS;
+  const truncatedNew = newS.length > 300 ? newS.slice(0, 300) + "…" : newS;
+  return `[edit] ${label}: ${file}\n- ${truncatedOld}\n+ ${truncatedNew}`;
+}

package/src/tools/glob.ts

@@ -0,0 +1,40 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { resolveInWorkspace } from "./_fs.ts";
+import * as path from "node:path";
+
+const MAX_RESULTS = 200;
+
+export const glob = tool({
+  description:
+    "Find files matching a glob pattern (e.g. 'src/**/*.ts'). " +
+    "Use this to locate files by name or extension.",
+  inputSchema: z.object({
+    pattern: z.string().describe("Glob pattern relative to workspace root"),
+    cwd: z
+      .string()
+      .optional()
+      .describe("Directory to search in, relative to workspace root (default: workspace root)"),
+  }),
+  execute: async ({ pattern: globPattern, cwd }) => {
+    const base = cwd ? resolveInWorkspace(cwd) : process.cwd();
+    const baseName = path.relative(process.cwd(), base) || ".";
+
+    const g = new Bun.Glob(globPattern);
+    const results: string[] = [];
+
+    for await (const match of g.scan({ cwd: base, absolute: false, onlyFiles: true })) {
+      const segs = match.split("/");
+      if (segs.includes("node_modules") || segs.includes(".git")) continue;
+      if (results.length >= MAX_RESULTS) break;
+      results.push(match);
+    }
+
+    if (results.length === 0) {
+      return `No files matched '${globPattern}' in ${baseName}`;
+    }
+
+    const truncated = results.length >= MAX_RESULTS ? `\n… [truncated to ${MAX_RESULTS} results]` : "";
+    return `${results.length} files matching '${globPattern}' in ${baseName}:${truncated}\n${results.join("\n")}`;
+  },
+});

package/src/tools/grep.ts

@@ -0,0 +1,187 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { resolveInWorkspace } from "./_fs.ts";
+import * as path from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+
+const OUTPUT_CAP = 30_000;
+const MAX_MATCHES = 500;
+
+export const grep = tool({
+  description:
+    "Search for a regex pattern in file contents. " +
+    "Returns matching lines with file path and line number. " +
+    "Use this to find where functions, types, or strings are defined.",
+  inputSchema: z.object({
+    pattern: z.string().describe("Regex pattern to search for"),
+    path: z
+      .string()
+      .optional()
+      .describe("File or directory to search in, relative to workspace root (default: workspace root)"),
+    include: z
+      .string()
+      .optional()
+      .describe("Glob pattern to filter files (e.g. '*.ts', 'src/**')"),
+    ignoreCase: z
+      .boolean()
+      .optional()
+      .describe("Case-insensitive search (default: false)"),
+  }),
+  execute: async ({ pattern, path: searchPath, include, ignoreCase }) => {
+    const cwd = searchPath ? resolveInWorkspace(searchPath) : process.cwd();
+    const cwdName = path.relative(process.cwd(), cwd) || ".";
+
+    const rgResult = await tryRg(pattern, cwd, include, ignoreCase);
+    if (rgResult !== null) return rgResult;
+
+    try {
+      return await jsGrep(pattern, cwd, cwdName, include, ignoreCase);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return `grep error: ${msg}`;
+    }
+  },
+});
+
+async function tryRg(
+  pattern: string,
+  cwd: string,
+  include?: string,
+  ignoreCase?: boolean,
+): Promise<string | null> {
+  const args = ["--line-number", "--no-heading", "--color=never", "--no-messages"];
+
+  if (ignoreCase) args.push("--ignore-case");
+
+  if (include) args.push("--glob", include);
+
+  args.push("--", pattern);
+  args.push(cwd);
+
+  const proc = Bun.spawn(["rg", ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const out = await proc.stdout.text();
+  const err = await proc.stderr.text();
+  await proc.exited;
+
+  if (proc.exitCode === 0) {
+    const cwdName = path.relative(process.cwd(), cwd) || ".";
+    return formatMatches(out, pattern, cwdName);
+  }
+
+  if (proc.exitCode === 1) {
+    const cwdName = path.relative(process.cwd(), cwd) || ".";
+    return `No matches for '${pattern}' in ${cwdName}`;
+  }
+
+  if (err.includes("command not found") || err.includes("No such file")) {
+    return null; // rg not available, fallback to JS
+  }
+
+  return `grep error (exit ${proc.exitCode}): ${err || "unknown error"}`;
+}
+
+async function jsGrep(
+  pattern: string,
+  absPath: string,
+  name: string,
+  include?: string,
+  ignoreCase?: boolean,
+): Promise<string> {
+  const flags = ignoreCase ? "i" : "";
+  let regex: RegExp;
+  try {
+    regex = new RegExp(pattern, flags);
+  } catch {
+    return `Invalid regex pattern: ${pattern}`;
+  }
+
+  const matches: string[] = [];
+  const fileEntries = include
+    ? await collectMatching(absPath, include)
+    : await collectAll(absPath);
+
+  for (const filePath of fileEntries) {
+    if (matches.length >= MAX_MATCHES) break;
+
+    try {
+      const content = await readFile(filePath, "utf-8");
+      const lines = content.split("\n");
+      const rel = path.relative(process.cwd(), filePath) || filePath;
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (regex.test(line)) {
+          const stripped = line.trimEnd();
+          const display =
+            stripped.length > 200 ? stripped.slice(0, 200) + "…" : stripped;
+          matches.push(`${rel}:${i + 1}: ${display}`);
+          if (matches.length >= MAX_MATCHES) break;
+        }
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  if (matches.length === 0) {
+    return `No matches for '${pattern}' in ${name}`;
+  }
+
+  let output = matches.join("\n");
+  if (output.length > OUTPUT_CAP) {
+    output = output.slice(0, OUTPUT_CAP) + "\n… [truncated]";
+  }
+
+  return `${matches.length} matches for '${pattern}' in ${name}:\n${output}`;
+}
+
+async function collectAll(dir: string): Promise<string[]> {
+  const results: string[] = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const nested = await collectAll(full);
+        results.push(...nested);
+      } else if (entry.isFile()) {
+        results.push(full);
+      }
+    }
+  } catch {
+    // Permission denied or similar
+  }
+  return results;
+}
+
+async function collectMatching(dir: string, globPattern: string): Promise<string[]> {
+  const g = new Bun.Glob(globPattern);
+  const results: string[] = [];
+  for await (const match of g.scan({ cwd: dir, absolute: false, onlyFiles: true })) {
+    results.push(path.join(dir, match));
+  }
+  return results;
+}
+
+function formatMatches(raw: string, pattern: string, cwdName: string): string {
+  const lines = raw.split("\n").filter((l) => l.length > 0);
+  if (lines.length === 0) {
+    return `No matches for '${pattern}' in ${cwdName}`;
+  }
+
+  const truncated = lines.length > MAX_MATCHES;
+  const shown = truncated ? lines.slice(0, MAX_MATCHES) : lines;
+  let output = shown.join("\n");
+
+  if (output.length > OUTPUT_CAP) {
+    output = output.slice(0, OUTPUT_CAP) + "\n… [truncated]";
+  }
+
+  const note = truncated
+    ? `\n… [${lines.length} matches, showing ${MAX_MATCHES}]`
+    : "";
+  return `${lines.length} matches for '${pattern}' in ${cwdName}:${note}\n${output}`;
+}

package/src/tools/index.ts

@@ -0,0 +1,21 @@
+import { read, ls, glob, grep, write, edit, bash, todowrite, question, readonlyTools, allToolsWithoutTask } from "./registry.ts";
+import { task } from "./task.ts";
+import type { ToolSet } from "ai";
+
+export { read, ls, glob, grep, write, edit, bash, todowrite, question, task };
+export { readonlyTools };
+
+export const allTools: ToolSet = {
+  ...allToolsWithoutTask,
+  task,
+};
+
+export type AgentMode = "plan" | "build";
+
+export function toolsForMode(mode: AgentMode): ToolSet {
+  return mode === "plan" ? readonlyTools : allTools;
+}
+
+export function isReadonlyTool(name: string): boolean {
+  return name in readonlyTools;
+}

package/src/tools/ls.ts

@@ -0,0 +1,70 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { resolveInWorkspace } from "./_fs.ts";
+import { readdir, stat } from "node:fs/promises";
+import * as path from "node:path";
+
+const MAX_ENTRIES = 200;
+const SKIP_DIRS = new Set(["node_modules", ".git", "__pycache__", ".venv", "vendor"]);
+
+export const ls = tool({
+  description:
+    "List files and directories in a given directory. " +
+    "Use this to explore the project structure.",
+  inputSchema: z.object({
+    path: z
+      .string()
+      .optional()
+      .describe("Directory path relative to workspace root (default: workspace root)"),
+  }),
+  execute: async ({ path: dirPath = "." }) => {
+    const abs = resolveInWorkspace(dirPath);
+    const name = path.relative(process.cwd(), abs) || abs;
+
+    let entries: string[];
+    try {
+      entries = await readdir(abs);
+    } catch {
+      return `Error: directory not found: ${name}`;
+    }
+
+    if (entries.length === 0) {
+      return `${name}/ (empty)`;
+    }
+
+    const rows: string[] = [];
+    const sorted = entries.sort();
+    let skipped = 0;
+
+    for (const entry of sorted) {
+      if (SKIP_DIRS.has(entry)) {
+        skipped++;
+        continue;
+      }
+      if (rows.length >= MAX_ENTRIES) break;
+
+      try {
+        const s = await stat(path.join(abs, entry));
+        const suffix = s.isDirectory() ? "/" : "";
+        const size = s.isFile() ? formatSize(s.size) : "-";
+        rows.push(`${size.padStart(6, " ")}  ${entry}${suffix}`);
+      } catch {
+        rows.push(`     ?  ${entry}`);
+      }
+    }
+
+    const more =
+      rows.length < entries.length - skipped
+        ? `\n… and ${entries.length - skipped - rows.length} more entries`
+        : "";
+    const skipNote = skipped > 0 ? ` (${skipped} hidden dirs skipped)` : "";
+
+    return `${name}/${skipNote} (${entries.length - skipped} entries):\n${rows.join("\n")}${more}`;
+  },
+});
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}K`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+}

package/src/tools/question.ts

@@ -0,0 +1,81 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+export interface QuestionOption {
+  label: string;
+  description?: string;
+}
+
+export interface QuestionSpec {
+  question: string;
+  header?: string;
+  options: QuestionOption[];
+  multiple?: boolean;
+}
+
+// Risposta: per ogni domanda, le label selezionate (più di una se multiple).
+export type Answers = string[][];
+
+// Meccanismo EVENT-DRIVEN (come requestConfirmation in permissions.ts):
+// la UI registra un handler con setAnswerHandler; il tool, dentro execute, chiama
+// requestAnswer e ne attende l'esito. Senza handler (test/headless) si usa il fallback.
+export type AnswerHandler = (questions: QuestionSpec[]) => Promise<Answers>;
+
+let answerHandler: AnswerHandler | null = null;
+
+export function setAnswerHandler(handler: AnswerHandler | null): void {
+  answerHandler = handler;
+}
+
+export async function requestAnswer(questions: QuestionSpec[]): Promise<Answers> {
+  if (answerHandler) return answerHandler(questions);
+  // Fallback senza UI: nessuna risposta (l'agente prosegue con cautela).
+  return questions.map(() => []);
+}
+
+export const question = tool({
+  description:
+    "Ask the user one or more questions during execution instead of guessing on ambiguous choices. " +
+    "Each question offers a list of options the user picks from (single or multiple choice). " +
+    "Use sparingly, only for decisions that genuinely change the outcome and that you cannot resolve " +
+    "from the request, the code, or sensible defaults. Execution pauses until the user answers.",
+  inputSchema: z.object({
+    questions: z
+      .array(
+        z.object({
+          question: z.string().min(1).describe("The full question to ask the user"),
+          header: z
+            .string()
+            .optional()
+            .describe("Very short label/chip for the question (e.g. 'Auth method')"),
+          options: z
+            .array(
+              z.object({
+                label: z.string().min(1).describe("Short choice text shown to the user"),
+                description: z
+                  .string()
+                  .optional()
+                  .describe("Optional explanation of what this option means"),
+              }),
+            )
+            .min(2)
+            .describe("The available choices (at least 2, mutually exclusive unless multiple)"),
+          multiple: z
+            .boolean()
+            .optional()
+            .describe("Allow selecting more than one option (default false)"),
+        }),
+      )
+      .min(1)
+      .describe("The questions to ask (1 or more)"),
+  }),
+  execute: async ({ questions }) => {
+    const answers = await requestAnswer(questions);
+    const lines = questions.map((q, i) => {
+      const sel = answers[i] ?? [];
+      const a = sel.length > 0 ? sel.join(", ") : "(no answer — proceed with best judgment)";
+      return `Q: ${q.question}\nA: ${a}`;
+    });
+    return lines.join("\n\n");
+  },
+});

package/src/tools/read.ts

@@ -0,0 +1,61 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { resolveInWorkspace } from "./_fs.ts";
+import * as path from "node:path";
+
+const OUTPUT_CAP = 30_000;
+
+export const read = tool({
+  description:
+    "Read a file from the workspace. Use offset and limit for large files. " +
+    "Returns content with line numbers. Prefer this over bash for reading files.",
+  inputSchema: z.object({
+    path: z.string().describe("Path to the file, relative to workspace root"),
+    offset: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe("Line number to start reading from (0-indexed)"),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(2000)
+      .optional()
+      .describe("Maximum number of lines to read"),
+  }),
+  execute: async ({ path: filePath, offset, limit }) => {
+    const abs = resolveInWorkspace(filePath);
+    const name = path.relative(process.cwd(), abs) || abs;
+    const f = Bun.file(abs);
+
+    if (!(await f.exists())) {
+      return `Error: file not found: ${name}`;
+    }
+
+    const raw = await f.text();
+    const lines = raw.split("\n");
+    const start = offset ?? 0;
+    const end = limit ? start + limit : lines.length;
+    const sliced = lines.slice(start, end);
+
+    const numbered = sliced
+      .map((line, i) => {
+        const n = String(start + i + 1).padStart(4, " ");
+        return `${n}: ${line}`;
+      })
+      .join("\n");
+
+    const truncated = numbered.length > OUTPUT_CAP;
+    const output = truncated
+      ? numbered.slice(0, OUTPUT_CAP) + "\n… [truncated]"
+      : numbered;
+
+    const linesLabel =
+      end >= lines.length ? `${lines.length} lines` : `${start + 1}-${end} of ${lines.length} lines`;
+    const header = `${name} (${linesLabel})${truncated ? " [truncated]" : ""}`;
+
+    return `${header}\n${output}`;
+  },
+});

package/src/tools/registry.ts

@@ -0,0 +1,36 @@
+import type { ToolSet } from "ai";
+import { read } from "./read.ts";
+import { ls } from "./ls.ts";
+import { glob } from "./glob.ts";
+import { grep } from "./grep.ts";
+import { write } from "./write.ts";
+import { edit } from "./edit.ts";
+import { bash } from "./bash.ts";
+import { webfetch } from "./webfetch.ts";
+import { todowrite } from "./todowrite.ts";
+import { question } from "./question.ts";
+
+export { read, ls, glob, grep, write, edit, bash, webfetch, todowrite, question };
+
+export const readonlyTools: ToolSet = {
+  read,
+  ls,
+  glob,
+  grep,
+  webfetch,
+  todowrite,
+  question,
+};
+
+export const allToolsWithoutTask: ToolSet = {
+  read,
+  ls,
+  glob,
+  grep,
+  write,
+  edit,
+  bash,
+  webfetch,
+  todowrite,
+  question,
+};