jeo-code 0.1.0

package/src/agent/state.ts

@@ -0,0 +1,199 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { parseConfig } from "./config-schema";
+
+/** Persisted OAuth credential set (access + refresh + expiry) for a provider. */
+export interface StoredOAuth {
+  access: string;
+  refresh?: string;
+  /** Epoch ms after which the access token is considered expired (skew-adjusted at mint time). */
+  expires?: number;
+  accountId?: string;
+  email?: string;
+  projectId?: string;
+}
+
+export interface Config {
+  providers: {
+    anthropic?: string;
+    openai?: string;
+    gemini?: string;
+  };
+  /**
+   * OAuth credentials (take precedence over API keys for the same provider).
+   * A bare string is a legacy/manually-pasted bearer with no refresh metadata;
+   * a {@link StoredOAuth} object carries refresh token + expiry for auto-refresh.
+   */
+  oauth?: {
+    anthropic?: string | StoredOAuth;
+    openai?: string | StoredOAuth;
+    gemini?: string | StoredOAuth;
+  };
+  /** Base URL for the local Ollama server (keyless). */
+  ollamaBaseUrl?: string;
+  /** Base URL override for OpenAI-compatible providers (LM Studio, vLLM, llama-cpp-server, ...). */
+  openaiBaseUrl?: string;
+  defaultModel: string;
+  thinkingLevel?: "minimal" | "low" | "medium" | "high" | "xhigh";
+  /** Friendly model aliases, e.g. { fast: "ollama/qwen2.5:0.5b" }. Override built-ins. */
+  modelAliases?: { [alias: string]: string };
+  /**
+   * Provider retry budgets (gjc parity). `requestMaxRetries` is the number of
+   * retries (excluding the initial request) for a provider request; `maxDelayMs`
+   * caps exponential backoff. `maxRetries`/`streamMaxRetries` are accepted for
+   * gjc-config compatibility.
+   */
+  retry?: {
+    requestMaxRetries?: number;
+    streamMaxRetries?: number;
+    maxRetries?: number;
+    maxDelayMs?: number;
+  };
+  /**
+   * Per-subagent-role overrides (gjc role-agent parity). Keyed by role id
+   * (executor / planner / architect / critic); each may pin a model and/or a
+   * tool-loop step budget.
+   */
+  subagents?: { [roleId: string]: { model?: string; maxSteps?: number } };
+  /**
+   * Model role tiers (gjc `--smol`/`--slow`/`--plan` parity). Each falls back to
+   * `defaultModel`. Env `JOC_SMOL_MODEL`/`JOC_SLOW_MODEL`/`JOC_PLAN_MODEL` fill gaps.
+   */
+  roles?: { smol?: string; slow?: string; plan?: string };
+}
+
+export interface WorkflowState {
+  active: boolean;
+  current_phase: string;
+  skill: "deep-interview" | "ralplan" | "team" | "ultragoal";
+  interview_id?: string;
+  slug?: string;
+  initial_idea?: string;
+  current_ambiguity?: number;
+  threshold?: number;
+  seed_path?: string;
+  plan_path?: string;
+  completed_tasks?: string[];
+  pending_tasks?: string[];
+  approved?: boolean;
+}
+
+/**
+ * Resolve the global config directory at call time (not import time) so that a
+ * `JOC_CONFIG_DIR` override or a runtime `HOME` change is always honored.
+ * `JOC_CONFIG_DIR` takes precedence; otherwise `~/.joc`.
+ */
+function globalConfigDir(): string {
+  return process.env.JOC_CONFIG_DIR || path.join(os.homedir(), ".joc");
+}
+function globalConfigPath(): string {
+  return path.join(globalConfigDir(), "config.json");
+}
+
+function envOAuth(): NonNullable<Config["oauth"]> {
+  return {
+    anthropic: process.env.ANTHROPIC_OAUTH_TOKEN || process.env.CLAUDE_CODE_OAUTH_TOKEN,
+    openai: process.env.OPENAI_OAUTH_TOKEN,
+    gemini: process.env.GEMINI_OAUTH_TOKEN,
+  };
+}
+
+/** Merge env-provided OAuth tokens / Ollama base over a config (env fills gaps only). */
+function withEnvOverlay(cfg: Config): Config {
+  const envTok = envOAuth();
+  const oauth = { ...envTok, ...(cfg.oauth ?? {}) };
+  return {
+    ...cfg,
+    oauth,
+    defaultModel: process.env.JOC_DEFAULT_MODEL || cfg.defaultModel,
+    ollamaBaseUrl: cfg.ollamaBaseUrl || process.env.OLLAMA_HOST || "http://localhost:11434",
+    openaiBaseUrl: cfg.openaiBaseUrl || process.env.OPENAI_BASE_URL,
+    roles: {
+      smol: cfg.roles?.smol || process.env.JOC_SMOL_MODEL,
+      slow: cfg.roles?.slow || process.env.JOC_SLOW_MODEL,
+      plan: cfg.roles?.plan || process.env.JOC_PLAN_MODEL,
+    },
+  };
+}
+
+function envDefaultConfig(): Config {
+  return {
+    providers: {
+      anthropic: process.env.ANTHROPIC_API_KEY,
+      openai: process.env.OPENAI_API_KEY,
+      gemini: process.env.GEMINI_API_KEY,
+    },
+    defaultModel: process.env.JOC_DEFAULT_MODEL || "claude-3-5-sonnet",
+    thinkingLevel: "medium",
+  };
+}
+
+export async function readGlobalConfig(): Promise<Config> {
+  let data: string;
+  try {
+    data = await fs.readFile(globalConfigPath(), "utf-8");
+  } catch {
+    return withEnvOverlay(envDefaultConfig());
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(data);
+  } catch {
+    process.stderr.write(`[joc] ${globalConfigPath()} is not valid JSON; using environment defaults.\n`);
+    return withEnvOverlay(envDefaultConfig());
+  }
+
+  const parsed = parseConfig(raw);
+  if (!parsed.ok) {
+    process.stderr.write(`[joc] ${globalConfigPath()} is invalid (${parsed.message}); using environment defaults.\n`);
+    return withEnvOverlay(envDefaultConfig());
+  }
+  return withEnvOverlay(parsed.config as Config);
+}
+
+export async function saveGlobalConfig(config: Config): Promise<void> {
+  await fs.mkdir(globalConfigDir(), { recursive: true, mode: 0o700 });
+  await fs.writeFile(globalConfigPath(), JSON.stringify(config, null, 2), { encoding: "utf-8", mode: 0o600 });
+  await fs.chmod(globalConfigPath(), 0o600).catch(() => {}); // ensure mode even if file pre-existed
+}
+
+export function getLocalJocDir(cwd: string = process.cwd()): string {
+  return path.join(cwd, ".joc");
+}
+
+export async function readWorkflowState(
+  skill: "deep-interview" | "ralplan" | "team" | "ultragoal",
+  cwd: string = process.cwd()
+): Promise<WorkflowState | null> {
+  const statePath = path.join(getLocalJocDir(cwd), "state", `${skill}-state.json`);
+  try {
+    const data = await fs.readFile(statePath, "utf-8");
+    return JSON.parse(data) as WorkflowState;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeWorkflowState(
+  skill: "deep-interview" | "ralplan" | "team" | "ultragoal",
+  state: WorkflowState,
+  cwd: string = process.cwd()
+): Promise<string> {
+  const stateDir = path.join(getLocalJocDir(cwd), "state");
+  await fs.mkdir(stateDir, { recursive: true });
+  const statePath = path.join(stateDir, `${skill}-state.json`);
+  await fs.writeFile(statePath, JSON.stringify(state, null, 2), "utf-8");
+  return statePath;
+}
+
+export async function clearWorkflowState(
+  skill: "deep-interview" | "ralplan" | "team" | "ultragoal",
+  cwd: string = process.cwd()
+): Promise<void> {
+  const statePath = path.join(getLocalJocDir(cwd), "state", `${skill}-state.json`);
+  try {
+    await fs.unlink(statePath);
+  } catch {}
+}

package/src/agent/subagents.ts

@@ -0,0 +1,149 @@
+/**
+ * Subagent role registry (gjc role-agent parity: executor / planner / architect /
+ * critic). A "subagent" is the executor tool-loop driven with a role-specific
+ * system prompt, model, step budget, and toolset. The registry is pure data so
+ * it can be listed in the TUI (`/agents`) and consumed by `joc team` without
+ * importing any provider or I/O code.
+ *
+ * Read-only roles (planner/architect/critic) get a mutation-free toolset so a
+ * review/plan lane physically cannot edit the repo, mirroring gjc's read-only
+ * role agents.
+ */
+import { DEFAULT_TOOLS, executorSystemPrompt, type ToolHandler } from "./engine";
+import type { Config } from "./state";
+
+export interface SubagentRole {
+  /** Stable id used in config + `/agents <id>`. */
+  id: string;
+  /** Human title shown in listings. */
+  title: string;
+  /** One-line purpose. */
+  description: string;
+  /** Read-only roles must not mutate the repo (no write/edit tools). */
+  readOnly: boolean;
+  /** Default tool-loop step budget for this role. */
+  defaultMaxSteps: number;
+}
+
+/** The four bundled subagent roles. `executor` is the only mutating role. */
+export const SUBAGENT_ROLES: readonly SubagentRole[] = [
+  {
+    id: "executor",
+    title: "Executor",
+    description: "Bounded implementation, refactors, fixes, and verification-ready edits.",
+    readOnly: false,
+    defaultMaxSteps: 15,
+  },
+  {
+    id: "planner",
+    title: "Planner",
+    description: "Read-only sequencing, acceptance criteria, risks, and handoff shape.",
+    readOnly: true,
+    defaultMaxSteps: 10,
+  },
+  {
+    id: "architect",
+    title: "Architect",
+    description: "Read-only architecture and code review with severity-rated findings.",
+    readOnly: true,
+    defaultMaxSteps: 10,
+  },
+  {
+    id: "critic",
+    title: "Critic",
+    description: "Read-only plan critic; approves only actionable, verifiable plans.",
+    readOnly: true,
+    defaultMaxSteps: 8,
+  },
+];
+
+const DEFAULT_ROLE_ID = "executor";
+
+/** Normalize loosely-typed role input (case-insensitive, trimmed). */
+export function normalizeRoleId(input: string | undefined | null): string {
+  return (input ?? "").trim().toLowerCase();
+}
+
+/** Look up a role by id (case-insensitive). Returns undefined when unknown. */
+export function getSubagentRole(id: string | undefined | null): SubagentRole | undefined {
+  const want = normalizeRoleId(id);
+  return SUBAGENT_ROLES.find(r => r.id === want);
+}
+
+/** The default role (`executor`) used when none is specified. */
+export function defaultSubagentRole(): SubagentRole {
+  // Non-null: DEFAULT_ROLE_ID is guaranteed present in SUBAGENT_ROLES.
+  return getSubagentRole(DEFAULT_ROLE_ID)!;
+}
+
+export type SubagentConfig = NonNullable<Config["subagents"]>;
+
+/** Per-role model override → falls back to the global default model. */
+export function resolveSubagentModel(roleId: string, config: Pick<Config, "defaultModel" | "subagents">): string {
+  const entry = config.subagents?.[normalizeRoleId(roleId)];
+  return entry?.model ?? config.defaultModel;
+}
+
+/** Per-role step budget → config override, else the role default, else 15. */
+export function resolveSubagentMaxSteps(roleId: string, config: Pick<Config, "subagents">): number {
+  const entry = config.subagents?.[normalizeRoleId(roleId)];
+  if (typeof entry?.maxSteps === "number" && entry.maxSteps > 0) return entry.maxSteps;
+  return getSubagentRole(roleId)?.defaultMaxSteps ?? 15;
+}
+
+/** Build a role-specific executor system prompt; read-only roles get a no-mutation directive. */
+export function subagentSystemPrompt(role: SubagentRole): string {
+  const base = executorSystemPrompt(`${role.title} subagent — ${role.description}`);
+  if (!role.readOnly) return base;
+  return (
+    base +
+    `\n\nYou are a READ-ONLY ${role.title}. Do not create or modify files; ` +
+    `use read / find / search (and read-only bash) only, then report your findings via done.`
+  );
+}
+
+/** Toolset for a role: read-only roles drop the mutating tools (write/edit). */
+export function subagentToolset(role: SubagentRole): Record<string, ToolHandler> {
+  if (!role.readOnly) return DEFAULT_TOOLS;
+  const ro: Record<string, ToolHandler> = {};
+  for (const [name, handler] of Object.entries(DEFAULT_TOOLS)) {
+    if (name === "write" || name === "edit") continue;
+    ro[name] = handler;
+  }
+  return ro;
+}
+
+/** All role ids (for `/agents` autocomplete + validation). */
+export function subagentRoleIds(): string[] {
+  return SUBAGENT_ROLES.map(r => r.id);
+}
+
+/** Parse a `/agents <role> maxSteps <n>` value → positive int, else undefined. */
+export function parseMaxSteps(input: string | undefined): number | undefined {
+  const n = parseInt((input ?? "").trim(), 10);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+/**
+ * Return a new `subagents` map with a role's settings patched (model and/or
+ * maxSteps). Pure — does not mutate `config`. Unknown roles are rejected by the
+ * caller via `getSubagentRole`; this helper trusts the id it is given.
+ */
+export function withSubagentSetting(
+  config: Pick<Config, "subagents">,
+  roleId: string,
+  patch: { model?: string; maxSteps?: number },
+): SubagentConfig {
+  const id = normalizeRoleId(roleId);
+  const subs: SubagentConfig = { ...(config.subagents ?? {}) };
+  subs[id] = { ...subs[id], ...patch };
+  return subs;
+}
+
+/** Return a new `subagents` map with a role's override removed (reset to defaults). */
+export function clearSubagentSetting(config: Pick<Config, "subagents">, roleId: string): SubagentConfig {
+  const id = normalizeRoleId(roleId);
+  const subs: SubagentConfig = { ...(config.subagents ?? {}) };
+  delete subs[id];
+  return subs;
+}

package/src/agent/tools.ts

@@ -0,0 +1,355 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { readWorkflowState } from "./state";
+
+export interface ToolResult {
+  success: boolean;
+  output: string;
+  error?: string;
+}
+
+/**
+ * Directories that pollute `find`/`search` results and waste time: VCS, build
+ * artifacts, dependency trees, and joc's own runtime dir. gjc's native search
+ * respects ignore files; this is the pure-TS equivalent.
+ */
+export const IGNORED_DIRS = [
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".joc",
+  "vendor",
+  ".cache",
+];
+
+/**
+ * Validates if codebase mutation tools are blocked due to an active Socratic interview.
+ * Mutation is blocked only if deep-interview is active, not completed, and the file
+ * is NOT under the `.joc/` directory (planning/spec files are allowed).
+ */
+export async function assertMutationAllowed(
+  filePath: string,
+  cwd: string = process.cwd()
+): Promise<void> {
+  const deepInterviewState = await readWorkflowState("deep-interview", cwd);
+  if (deepInterviewState && deepInterviewState.active && deepInterviewState.current_phase !== "complete") {
+    // Check if the target is NOT inside the local .joc folder. Use a path-boundary
+    // check (not bare startsWith) so siblings like ".joc-backup" aren't mistaken for ".joc/".
+    const absPath = path.resolve(cwd, filePath);
+    const jocDir = path.resolve(cwd, ".joc");
+    const insideJoc = absPath === jocDir || absPath.startsWith(jocDir + path.sep);
+    if (!insideJoc) {
+      throw new Error(
+        `[MutationGuard Blocked] Code mutation is strictly blocked during an active Socratic interview.\n` +
+        `Current Ambiguity Score: ${((deepInterviewState.current_ambiguity ?? 1) * 100).toFixed(0)}% (must be <= 20% to unlock).\n` +
+        `Only spec/planning writes under '.joc/' are permitted. Finish requirements with 'joc deep-interview' first.`
+      );
+    }
+  }
+}
+
+export async function assertBashAllowed(
+  cwd: string = process.cwd()
+): Promise<void> {
+  const deepInterviewState = await readWorkflowState("deep-interview", cwd);
+  if (deepInterviewState && deepInterviewState.active && deepInterviewState.current_phase !== "complete") {
+    throw new Error(
+      "[MutationGuard] bash is disabled during an active Socratic interview (ambiguity must reach <=20% first). Finish 'joc deep-interview'."
+    );
+  }
+}
+
+export async function readTool(
+  filePath: string,
+  lineRange?: string,
+  cwd: string = process.cwd()
+): Promise<ToolResult> {
+  try {
+    const absPath = path.resolve(cwd, filePath);
+    const content = await fs.readFile(absPath, "utf-8");
+    const lines = content.split("\n");
+
+    if (lineRange) {
+      // Accept "start-end", open-ended "start-", or a single "start".
+      const match = lineRange.match(/^(\d+)(?:-(\d+)?)?$/);
+      if (match) {
+        const start = Math.max(1, parseInt(match[1]));
+        const hasRange = lineRange.includes("-");
+        const end = match[2]
+          ? Math.min(lines.length, parseInt(match[2]))
+          : hasRange
+            ? lines.length            // "start-" → to EOF
+            : Math.min(lines.length, start); // single line
+        if (end < start) {
+          return { success: false, output: "", error: `Invalid lineRange '${lineRange}': end < start (file has ${lines.length} lines)` };
+        }
+        const sliced = lines.slice(start - 1, end).map((l, i) => `${start + i}|${l}`).join("\n");
+        return { success: true, output: sliced };
+      }
+      return { success: false, output: "", error: `Invalid lineRange '${lineRange}'. Use "start-end", "start-", or "start".` };
+    }
+
+    const MAX_LINES = 500;
+    const annotated = lines.slice(0, MAX_LINES).map((l, i) => `${i + 1}|${l}`).join("\n");
+    if (lines.length > MAX_LINES) {
+      const notice = `\n…(showing lines 1-${MAX_LINES} of ${lines.length}; pass lineRange "${MAX_LINES + 1}-" to read the rest)`;
+      return { success: true, output: annotated + notice };
+    }
+    return { success: true, output: annotated };
+  } catch (err: any) {
+    return { success: false, output: "", error: err.message };
+  }
+}
+
+export async function writeTool(
+  filePath: string,
+  content: string,
+  cwd: string = process.cwd()
+): Promise<ToolResult> {
+  try {
+    await assertMutationAllowed(filePath, cwd);
+    const absPath = path.resolve(cwd, filePath);
+    await fs.mkdir(path.dirname(absPath), { recursive: true });
+    await fs.writeFile(absPath, content, "utf-8");
+    return { success: true, output: `Successfully wrote ${content.length} characters to ${filePath}` };
+  } catch (err: any) {
+    return { success: false, output: "", error: err.message };
+  }
+}
+
+export async function editTool(
+  filePath: string,
+  editBlock: string,
+  cwd: string = process.cwd()
+): Promise<ToolResult> {
+  try {
+    await assertMutationAllowed(filePath, cwd);
+    const absPath = path.resolve(cwd, filePath);
+    let content = await fs.readFile(absPath, "utf-8");
+
+    // Line-anchored edit parser. Modes (payload follows the directive's newline):
+    //   ≔A..B   replace lines A..B          ≔A    replace line A
+    //   ≔A+     insert AFTER line A (A=0 prepends)
+    //   ≔$      append to end of file
+    // Falls back to <<<<<<< SEARCH / ======= / >>>>>>> substring replacement.
+    const lines = content.split("\n");
+
+    let updated = false;
+    if (editBlock.startsWith("≔")) {
+      const appendMatch = editBlock.match(/^≔\$\n?([\s\S]*)$/);
+      const insertMatch = editBlock.match(/^≔(\d+)\+\n?([\s\S]*)$/);
+      const replaceMatch = editBlock.match(/^≔(\d+)(?:\.\.(\d+))?\n([\s\S]*)$/);
+      if (appendMatch) {
+        const payload = appendMatch[1];
+        content = content === "" || content.endsWith("\n") ? content + payload : content + "\n" + payload;
+        updated = true;
+      } else if (insertMatch) {
+        const at = parseInt(insertMatch[1]); // insert AFTER line `at`; 0 prepends
+        const payload = insertMatch[2];
+        if (at < 0 || at > lines.length) {
+          return { success: false, output: "", error: `Invalid insert position ${at}: out of bounds (file has ${lines.length} lines)` };
+        }
+        lines.splice(at, 0, payload);
+        content = lines.join("\n");
+        updated = true;
+      } else if (replaceMatch) {
+        const startLine = parseInt(replaceMatch[1]);
+        const endLine = replaceMatch[2] ? parseInt(replaceMatch[2]) : startLine;
+        const payload = replaceMatch[3];
+        if (startLine < 1 || endLine < startLine || endLine > lines.length) {
+          return {
+            success: false,
+            output: "",
+            error: `Invalid edit range ${startLine}..${endLine}: out of bounds or reversed (file has ${lines.length} lines)`,
+          };
+        }
+        lines.splice(startLine - 1, endLine - startLine + 1, payload);
+        content = lines.join("\n");
+        updated = true;
+      }
+    }
+
+    if (!updated) {
+      // Direct substring replacement fallback
+      const searchMatch = editBlock.split("<<<<<<< SEARCH");
+      if (searchMatch.length > 1) {
+        const parts = searchMatch[1].split("=======");
+        if (parts.length > 1) {
+          let searchVal = parts[0];
+          if (searchVal.startsWith("\r\n")) {
+            searchVal = searchVal.slice(2);
+          } else if (searchVal.startsWith("\n")) {
+            searchVal = searchVal.slice(1);
+          }
+          if (searchVal.endsWith("\r\n")) {
+            searchVal = searchVal.slice(0, -2);
+          } else if (searchVal.endsWith("\n")) {
+            searchVal = searchVal.slice(0, -1);
+          }
+
+          if (searchVal === "") {
+            return {
+              success: false,
+              output: "",
+              error: "Failed to apply edit: Search block is empty.",
+            };
+          }
+
+          const replaceParts = parts[1].split(">>>>>>>");
+          if (replaceParts.length > 0) {
+            let replaceVal = replaceParts[0];
+            if (replaceVal.startsWith("\r\n")) {
+              replaceVal = replaceVal.slice(2);
+            } else if (replaceVal.startsWith("\n")) {
+              replaceVal = replaceVal.slice(1);
+            }
+            if (replaceVal.endsWith("\r\n")) {
+              replaceVal = replaceVal.slice(0, -2);
+            } else if (replaceVal.endsWith("\n")) {
+              replaceVal = replaceVal.slice(0, -1);
+            }
+
+            if (content.includes(searchVal)) {
+              content = content.replace(searchVal, replaceVal);
+              updated = true;
+            } else {
+              return {
+                success: false,
+                output: "",
+                error: "Failed to apply edit: Search block not found in file.",
+              };
+            }
+          }
+        }
+      }
+    }
+
+    if (!updated) {
+      return {
+        success: false,
+        output: "",
+        error: "Failed to apply edit: Invalid edit block format. Use line range replacement: ≔[line]..[line] format.",
+      };
+    }
+
+    await fs.writeFile(absPath, content, "utf-8");
+    return { success: true, output: `Successfully updated ${filePath}` };
+  } catch (err: any) {
+    return { success: false, output: "", error: err.message };
+  }
+}
+
+export async function bashTool(
+  command: string,
+  cwd: string = process.cwd(),
+  timeoutMs: number = 120_000
+): Promise<ToolResult> {
+  try {
+    await assertBashAllowed(cwd);
+    // Run the command using Bun's native spawn
+    const proc = Bun.spawn(["bash", "-c", command], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    let timedOut = false;
+    const TIMEOUT_MS = timeoutMs;
+    let killTimer: ReturnType<typeof setTimeout> | undefined;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      // Graceful first (SIGTERM), then force-kill (SIGKILL) if it ignores it.
+      try { proc.kill(); } catch {}
+      killTimer = setTimeout(() => { try { proc.kill(9); } catch {} }, 3_000);
+    }, TIMEOUT_MS);
+
+    await proc.exited;
+    clearTimeout(timer);
+    if (killTimer) clearTimeout(killTimer);
+
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+
+    let output = [stdout, stderr].filter(Boolean).join("\n");
+    const MAX_OUTPUT = 100_000;
+    if (output.length > MAX_OUTPUT) {
+      output = output.slice(0, MAX_OUTPUT) + "\n…(output truncated at 100000 chars)";
+    }
+
+    if (timedOut) {
+      return {
+        success: false,
+        output,
+        error: `Command timed out after ${Math.round(TIMEOUT_MS / 1000)}s and was killed`,
+      };
+    }
+
+    return {
+      success: proc.exitCode === 0,
+      output: output || "(no output)",
+      error: proc.exitCode !== 0 ? `Exit code ${proc.exitCode}` : undefined,
+    };
+  } catch (err: any) {
+    return { success: false, output: "", error: err.message };
+  }
+}
+
+export async function findTool(
+  globPattern: string,
+  cwd: string = process.cwd()
+): Promise<ToolResult> {
+  try {
+    const pruneGroup: string[] = [];
+    for (let i = 0; i < IGNORED_DIRS.length; i++) {
+      if (i > 0) pruneGroup.push("-o");
+      pruneGroup.push("-name", IGNORED_DIRS[i]);
+    }
+    const proc = Bun.spawn(
+      ["find", ".", "-type", "d", "(", ...pruneGroup, ")", "-prune", "-o", "-name", globPattern, "-print"],
+      { cwd, stdout: "pipe", stderr: "pipe" },
+    );
+    await proc.exited;
+    const stdout = await new Response(proc.stdout).text();
+    const files = stdout.split("\n").filter(Boolean);
+    let output = files.length > 0 ? files.join("\n") : "No matching files found.";
+    const MAX_OUTPUT = 100_000;
+    if (output.length > MAX_OUTPUT) {
+      output = output.slice(0, MAX_OUTPUT) + "\n…(output truncated at 100000 chars)";
+    }
+    return { success: true, output };
+  } catch (err: any) {
+    return { success: false, output: "", error: err.message };
+  }
+}
+
+export async function searchTool(
+  pattern: string,
+  globPattern: string = "*",
+  cwd: string = process.cwd()
+): Promise<ToolResult> {
+  try {
+    const excludes = IGNORED_DIRS.map(d => `--exclude-dir=${d}`);
+    const proc = Bun.spawn(
+      ["grep", "-rnI", "--include", globPattern, ...excludes, "--", pattern, "."],
+      { cwd, stdout: "pipe", stderr: "pipe" },
+    );
+    await proc.exited;
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    // grep exit codes: 0 = match, 1 = no match (not an error), >=2 = a real error.
+    if (proc.exitCode !== null && proc.exitCode >= 2) {
+      return { success: false, output: stdout, error: stderr.trim() || `grep failed (exit ${proc.exitCode})` };
+    }
+    let output = stdout || "No matches found.";
+    const MAX_OUTPUT = 100_000;
+    if (output.length > MAX_OUTPUT) {
+      output = output.slice(0, MAX_OUTPUT) + "\n…(output truncated at 100000 chars)";
+    }
+    return { success: true, output };
+  } catch (err: any) {
+    return { success: false, output: "", error: err.message };
+  }
+}