@chloejs/core 0.2.0

package/core/turn.ts

@@ -0,0 +1,314 @@
+// Ask the model, run the tools it asked for, put the answers back, ask again.
+// Every step is written to the run as it happens, because a job that goes
+// wrong at four in the morning is only debuggable if that record exists.
+import { randomUUID } from "node:crypto";
+
+import { z } from "zod";
+
+import { db } from "#chloe/core/db.ts";
+import { oneLineSummary } from "#chloe/core/markdown.ts";
+import type { Agent, ChatHistory, Skill } from "#chloe/load/load.ts";
+import { ask, type Attachment, type Message, type ToolCall } from "#chloe/model/model.ts";
+import { recall, remember } from "#chloe/model/memory.ts";
+import { describe, type Approve, type Call, type Tool, type Tools } from "#chloe/model/tool.ts";
+
+export interface Ask {
+  agent: Agent;
+  prompt: string;
+  /** Photos and PDFs that came with the prompt. Seen this turn only: the thread keeps the words. */
+  attachments?: Attachment[];
+  /** When this job wants one the agent does not normally use. */
+  model?: string;
+  /** Without one, the turn starts fresh. */
+  thread?: string;
+  /**
+   * The channel it came in on: "telegram", "chat", "api", "terminal",
+   * "schedule", "eval", or the name of a channel an agent brings.
+   */
+  source: string;
+  /** The job this turn is, when it is one. */
+  job?: string;
+  /** How much of `thread` to show: the channel's `chatHistory`. The last 10 messages when unsaid. */
+  history?: ChatHistory;
+  /**
+   * Handed what the model writes before it asks for a tool, as soon as it is
+   * written. Never the final answer, which is what turn() returns.
+   */
+  said?: (text: string) => void;
+  /** Who this run is for, as an address. One column, and the team version reads it. */
+  owner?: string;
+  /** Answer tools from here instead of running them. For evals. */
+  instead?: (name: string, args: unknown) => Promise<unknown> | unknown;
+  signal?: AbortSignal;
+}
+
+/** What one turn came back with, including every tool call it made on the way. */
+export interface Result {
+  runId: string;
+  text: string;
+  steps: number;
+  cost: number;
+  calls: Call[];
+}
+
+function shown(history: ChatHistory = {}): { limit?: number; days?: number } {
+  return { limit: history.messages, days: history.days };
+}
+
+/** Dollars, at the size these numbers actually are: $0.0004 and $0.10, not $0.00 and $0.1. */
+export function money(amount: number): string {
+  return `$${amount.toFixed(4).replace(/(\.\d\d)0+$/, "$1")}`;
+}
+
+const MAX_STEPS = 40;
+
+/**
+ * Runs a prompt: ask a model, run the tools it asked for, put the answers
+ * back, ask again, until it stops asking.
+ */
+export async function turn({ agent, prompt, attachments, model, thread, source, job, history, said, owner, instead, signal }: Ask): Promise<Result> {
+  const runId = randomUUID();
+  const using = model ?? agent.model;
+  const tools = { ...(agent.tools ?? {}), skill: skillTool(agent.skills) };
+
+  const started = new Date().toISOString();
+  db.prepare(
+    "insert into runs (id, agent, started, source, job, model, prompt, kind, owner) values (?, ?, ?, ?, ?, ?, ?, 'turn', ?)",
+  ).run(runId, agent.name, started, source, job ?? null, using, prompt, owner ?? null);
+
+  const messages: Message[] = [
+    { role: "system", content: systemPrompt(agent) },
+    ...(thread ? recall(thread, { ...shown(history), tools: true }) : []),
+    { role: "user", content: prompt, attachments },
+  ];
+  if (thread) remember(thread, "user", prompt);
+
+  const trace: LoopStep[] = [];
+  const calls: Result["calls"] = [];
+  let cost = 0;
+  let steps = 0;
+
+  try {
+    const done = await loop({
+      model: using,
+      messages,
+      tools,
+      maxSteps: agent.maxSteps ?? MAX_STEPS,
+      signal,
+      instead,
+      onStep: (line) => {
+        trace.push(line);
+        if (said && line.say?.trim() && line.wants?.length) said(line.say);
+        if (line.tool) calls.push({ tool: line.tool, args: line.args, result: line.result });
+        save(runId, trace.filter((one) => (one as { say?: string }).say !== undefined).length, costOf(trace), trace);
+      },
+    });
+    cost = done.cost;
+    steps = done.steps;
+    if (done.stopped) {
+      fail(runId, done.text, steps, cost, trace);
+      return { runId, text: done.text, steps, cost, calls };
+    }
+    finish(runId, done.text, steps, cost, trace);
+    if (thread) remember(thread, "assistant", done.text, calls);
+    return { runId, text: done.text, steps, cost, calls };
+  } catch (error) {
+    fail(runId, String(error instanceof Error ? error.message : error), steps, cost, trace);
+    throw error;
+  }
+}
+
+/** What one turn of the loop did: what the model said, or one tool it ran. */
+export interface LoopStep {
+  step: number;
+  /** When it happened: when the model answered, or when the tool was called. */
+  at: string;
+  say?: string;
+  wants?: string[];
+  tool?: string;
+  args?: unknown;
+  result?: unknown;
+  failed?: boolean;
+  /** Set on a call the job would not allow. It never ran. */
+  refused?: boolean;
+  cost?: number;
+}
+
+/**
+ * Ask, run what it asked for, ask again, until it stops asking or hits a limit.
+ * Nothing here writes to the database: `turn` records a conversation and a
+ * job's agent step records one line, and they both run this.
+ *
+ * `stopped` says which limit ended it, "steps" or "budget", and is false when
+ * it finished. Hitting a limit is an answer and not a crash.
+ */
+export async function loop(options: {
+  model: string;
+  messages: Message[];
+  tools: Tools;
+  maxSteps: number;
+  /**
+   * The most this may spend, in dollars. Checked between turns, because what a
+   * turn costs is only known once it has been paid for, so the turn that goes
+   * over the line is paid for.
+   */
+  budget?: number;
+  signal?: AbortSignal;
+  instead?: Ask["instead"];
+  /** Asked before each tool runs. Without one, everything it was given may run. */
+  approve?: Approve;
+  onStep?: (line: LoopStep) => void;
+}): Promise<{ text: string; steps: number; cost: number; calls: Result["calls"]; stopped: false | "steps" | "budget" }> {
+  const specs = Object.entries(options.tools).map(([name, one]) => describe(name, one));
+  const calls: Result["calls"] = [];
+  let cost = 0;
+  let steps = 0;
+
+  for (; steps < options.maxSteps; steps++) {
+    const answer = await ask({ model: options.model, messages: options.messages, tools: specs, signal: options.signal });
+    cost += answer.cost;
+    options.onStep?.({ step: steps, at: new Date().toISOString(), say: answer.text, wants: answer.toolCalls.map((c) => c.function.name), cost: answer.cost });
+
+    if (answer.toolCalls.length === 0) {
+      return { text: answer.text, steps: steps + 1, cost, calls, stopped: false };
+    }
+
+    // Out of money before running what it asked for, because running the tools
+    // only leads to a turn there is nothing left to pay for.
+    if (options.budget !== undefined && cost >= options.budget) {
+      return { text: `Stopped after spending ${money(cost)} without finishing.`, steps: steps + 1, cost, calls, stopped: "budget" };
+    }
+
+    // Has to go back exactly as it came, or the provider rejects the tool
+    // answers that follow it.
+    options.messages.push({ role: "assistant", content: answer.text, tool_calls: answer.toolCalls });
+
+    for (const call of answer.toolCalls) {
+      const at = new Date().toISOString();
+      const { output, args, failed, refused } = await runTool(options.tools, call, options.instead, options.approve);
+      calls.push({ tool: call.function.name, args, result: output, ...(refused && { refused }) });
+      options.onStep?.({ step: steps, at, tool: call.function.name, args, result: clip(output), ...(failed && { failed }), ...(refused && { refused }) });
+      options.messages.push({
+        role: "tool",
+        tool_call_id: call.id,
+        content: typeof output === "string" ? output : JSON.stringify(output),
+      });
+    }
+  }
+
+  // Out of steps is an answer, not a crash: an empty string here would read as
+  // nothing being wrong.
+  return { text: `Stopped after ${steps} steps without finishing.`, steps, cost, calls, stopped: "steps" };
+}
+
+/** What the trace says has been spent so far, for the record written as it goes. */
+function costOf(trace: unknown[]): number {
+  return trace.reduce((sum: number, one) => sum + (((one as { cost?: number }).cost) ?? 0), 0);
+}
+
+// A missing tool, bad arguments and a tool that threw all go back to the model
+// as text it can act on. Dying here loses the work the turn had already done.
+async function runTool(
+  tools: Tools,
+  call: ToolCall,
+  instead?: Ask["instead"],
+  approve?: Approve,
+): Promise<{ output: unknown; args: unknown; failed?: boolean; refused?: boolean }> {
+  const name = call.function.name;
+  let args: unknown;
+  try {
+    args = call.function.arguments ? JSON.parse(call.function.arguments) : {};
+  } catch {
+    return { output: `${name} was called with arguments that are not valid JSON.`, args: call.function.arguments, failed: true };
+  }
+
+  const one = tools[name];
+  if (!one) return { output: `There is no tool called ${name}. You have: ${Object.keys(tools).join(", ")}`, args, failed: true };
+
+  const checked = one.inputSchema.safeParse(args);
+  if (!checked.success) {
+    return { output: `${name} was called wrongly: ${checked.error.issues.map((i) => `${i.path.join(".") || "input"} ${i.message}`).join("; ")}`, args, failed: true };
+  }
+
+  // Asked once the arguments are known and before anything runs, because what
+  // makes a call worth stopping is usually the arguments rather than the tool.
+  if (approve) {
+    let allowed: boolean | string;
+    try {
+      allowed = await approve({ tool: name, args: checked.data });
+    } catch (error) {
+      throw new Error(`Deciding whether ${name} could run failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (allowed !== true) {
+      const why = typeof allowed === "string" && allowed.trim() !== "" ? allowed : "the job did not allow it";
+      return {
+        output: `${name} was not allowed: ${why}. Try another way, or finish with what you have.`,
+        args: checked.data,
+        refused: true,
+      };
+    }
+  }
+
+  try {
+    const output = instead ? await instead(name, checked.data) : await one.execute(checked.data);
+    return { output: output ?? { ok: true }, args: checked.data };
+  } catch (error) {
+    return { output: `${name} failed: ${error instanceof Error ? error.message : String(error)}`, args: checked.data, failed: true };
+  }
+}
+
+// The model sees each skill's name and one sentence, and opens the body only
+// when it applies. In the system prompt instead, every skill would cost its
+// full text on every step of every turn.
+function skillTool(skills: Skill[]): Tool {
+  const byName = new Map(skills.map((s) => [s.name, s]));
+  return {
+    id: "skill",
+    description:
+      "Open one of your skills and read what it says. A skill tells you when to do something and " +
+      "how. Open the skill before doing the thing it covers.",
+    inputSchema: z.object({ name: z.string().describe("The skill's name, from the list in your instructions.") }),
+    execute: ({ name }: { name: string }) => {
+      const found = byName.get(name);
+      if (!found) throw new Error(`No skill called ${JSON.stringify(name)}. You have: ${[...byName.keys()].join(", ")}`);
+      return found.body;
+    },
+  };
+}
+
+function systemPrompt(agent: Agent): string {
+  const parts = [agent.instructions];
+  if (agent.skills.length > 0) {
+    parts.push(
+      "## Your skills\n\n" +
+        "Open one with the `skill` tool before doing the thing it covers.\n\n" +
+        agent.skills.map((s) => `- **${s.name}**: ${s.description}`).join("\n"),
+    );
+  }
+  parts.push(`Today is ${new Date().toISOString().slice(0, 10)}.`);
+  return parts.join("\n\n");
+}
+
+function save(runId: string, steps: number, cost: number, trace: unknown[]): void {
+  db.prepare("update runs set steps = ?, cost = ?, trace = ? where id = ?").run(
+    steps, cost, JSON.stringify(trace), runId,
+  );
+}
+
+function finish(runId: string, reply: string, steps: number, cost: number, trace: unknown[]): void {
+  db.prepare("update runs set finished = ?, reply = ?, summary = ?, steps = ?, cost = ?, trace = ? where id = ?").run(
+    new Date().toISOString(), reply, oneLineSummary(reply), steps, cost, JSON.stringify(trace), runId,
+  );
+}
+
+function fail(runId: string, error: string, steps: number, cost: number, trace: unknown[]): void {
+  db.prepare("update runs set finished = ?, error = ?, steps = ?, cost = ?, trace = ? where id = ?").run(
+    new Date().toISOString(), error, steps, cost, JSON.stringify(trace), runId,
+  );
+}
+
+/** So one tool answer in the record is not a megabyte of HTML. */
+function clip(output: unknown): unknown {
+  const text = typeof output === "string" ? output : JSON.stringify(output) ?? "";
+  return text.length > 4000 ? `${text.slice(0, 4000)}...[${text.length} bytes]` : output;
+}

package/do/email.ts

@@ -0,0 +1,45 @@
+// Sending one email.
+//
+// The caller supplies who it is from and who it is to; this file only knows
+// how to send. The key is resend.api_key in settings.local.json.
+//
+// The tool a model reaches is model/tools/send_email.ts, which calls
+// this. A job calls this directly, from a step.
+
+import { setting, settings } from "#chloe/core/settings.ts";
+
+/**
+ * Who an agent's mail comes from, who it goes to, and the tag in front of
+ * every subject.
+ */
+export interface Address {
+  /** The From line, e.g. "Backups <info@example.com>". */
+  from: string;
+  /** Who it goes to. */
+  to: string[];
+  /** Prefix put in front of every subject, so an inbox can be filtered. */
+  tag?: string;
+}
+
+/** Sends one email and returns its id. The tag is put in front of the subject. */
+export async function send(
+  { from, to, tag }: Address,
+  subject: string,
+  body: string,
+): Promise<{ sent: true; id?: string; subject: string }> {
+  const key = setting(settings.resend.api_key, "RESEND_API_KEY");
+  if (!key) throw new Error("No Resend key. Put it in settings.local.json as resend.api_key.");
+  // Refuse rather than send nowhere.
+  if (to.length === 0) throw new Error("Nobody to send to. The address belongs in settings.local.json.");
+  const response = await fetch("https://api.resend.com/emails", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ from, to, subject: tag ? `[${tag}] ${subject}` : subject, text: body }),
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!response.ok) {
+    throw new Error(`Resend refused the message (${response.status}): ${await response.text()}`);
+  }
+  const sent = (await response.json()) as { id?: string };
+  return { sent: true, id: sent.id, subject };
+}

package/do/files.ts

@@ -0,0 +1,96 @@
+// Reading and writing files inside one folder.
+//
+// `list`, `read`, `search` and `write` are what a job calls from a step. A job
+// that knows which file it wants should call one of these: going through a
+// model to read a path you already know is two seconds and a price for
+// nothing. The tools over them are model/tools/files.ts.
+//
+// They know nothing about what is in the folder: no list of subfolders, no
+// file format, no house rules. All of that is an agent's instructions or a
+// skill, which is text you can edit, not code that needs a restart.
+//
+// What they do enforce is the edge of the folder, through confine().
+import { execFile } from "node:child_process";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import { confine } from "#chloe/core/confine.ts";
+import { run } from "./run.ts";
+
+/** List a folder. `path` is relative to `root`, and omitting it means the top. */
+export async function list(root: string, path?: string) {
+  const resolved = path ? confine(root, path) : root;
+  const entries = await readdir(resolved, { withFileTypes: true });
+  return {
+    path: resolved,
+    entries: entries
+      .filter((e) => !e.name.startsWith("."))
+      .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
+      .sort(),
+  };
+}
+
+/** Read one file. `path` is relative to `root` and cannot leave it. */
+export async function read(root: string, path: string) {
+  const resolved = confine(root, path);
+  const content = await readFile(resolved, "utf8");
+  return { path: resolved, bytes: content.length, content };
+}
+
+/** Search a folder for text, case-insensitive. `folder` narrows it. */
+export async function search(root: string, query: string, folder?: string) {
+  const target = folder ? confine(root, folder) : root;
+  // ripgrep if the box has it, grep otherwise. An earlier version assumed
+  // ripgrep, and when it was not installed every search quietly answered
+  // "nothing matched", which reads exactly like a subject he never wrote
+  // about. A search that cannot run has to say so.
+  const attempts: Array<[string, string[]]> = [
+    ["rg", ["-i", "--no-heading", "--line-number", "--max-count", "5", "--glob", "!.git", "--", query, target]],
+    ["grep", ["-rIin", "--exclude-dir=.git", "--max-count=5", "-e", query, target]],
+  ];
+  for (const [file, args] of attempts) {
+    const r = await run(file, args, { timeoutMs: 60_000 });
+    // grep and rg both exit 1 for "no matches", which is an answer. Only a
+    // missing binary (127) means try the next one.
+    if (r.exitCode === 127) continue;
+    const lines = r.stdout.split("\n").filter(Boolean).slice(0, 80);
+    return {
+      searchedWith: file,
+      matches: lines.length,
+      results: lines,
+      note: lines.length === 0 ? "Nothing matched. Try the words he would have written." : undefined,
+    };
+  }
+  throw new Error("Neither rg nor grep is on this box, so nothing can be searched.");
+}
+
+/**
+ * Write one file, replacing it. `commit` makes the write a git commit, for a
+ * folder that is a repo, and then `message` is required.
+ */
+export async function write(
+  root: string,
+  path: string,
+  content: string,
+  { commit = false, message }: { commit?: boolean; message?: string } = {},
+) {
+  if (commit && (message ?? "").length < 10) {
+    throw new Error("This folder is a repo, so every write needs a commit message.");
+  }
+  const resolved = confine(root, path);
+  await mkdir(dirname(resolved), { recursive: true });
+  await writeFile(resolved, content, "utf8");
+  if (!commit) return { path: resolved, bytes: content.length };
+  const committed = await new Promise<string>((done) => {
+    execFile("git", ["-C", root, "add", "--", resolved], { timeout: 30_000 }, () =>
+      execFile(
+        "git",
+        ["-C", root, "commit", "-m", message!, "--", resolved],
+        { timeout: 30_000, encoding: "utf8" },
+        (error: unknown, out: string, err: string) =>
+          done(error ? `not committed: ${err || out}` : out.trim()),
+      ),
+    );
+  });
+  return { path: resolved, bytes: content.length, commit: committed };
+}

package/do/mail.ts

@@ -0,0 +1,155 @@
+// Reading mail, bound to a fixed search.
+//
+// The point of this file is the thing it does NOT let a caller do lightly. The
+// token `gog` holds can read the whole mailbox, so a query written at the call
+// site is a filter, not a boundary: one prompt injection or one sloppy turn
+// and the filter widens. The search comes from the binding in the agent's own
+// config, the caller may only choose how far back and how many, and fetching a
+// single message re-runs the same search first and refuses an id that is not
+// in it.
+//
+// The tool a model reaches is model/tools/gmail.ts, which calls this
+// with the same binding, so a job does not get a wider search for skipping
+// the model.
+import { run } from "./run.ts";
+import { setting, settings } from "#chloe/core/settings.ts";
+
+const GOG = "gog";
+
+/** gog reads its account and the password to its saved login from these two. */
+function gog(): Record<string, string> {
+  return {
+    GOG_ACCOUNT: setting(settings.google.account, "GOG_ACCOUNT"),
+    GOG_KEYRING_PASSWORD: setting(settings.google.password, "GOG_KEYRING_PASSWORD"),
+  };
+}
+
+/** One message from a mailbox, as a search hands it back. */
+export interface Message {
+  id: string;
+  threadId?: string;
+  subject?: string;
+  from?: string;
+  date?: string;
+  snippet?: string;
+}
+
+/** What the bound search matches. Nothing here widens it. */
+export async function messages({
+  search,
+  days = 7,
+  limit = 10,
+}: {
+  search: string;
+  days?: number;
+  limit?: number;
+}): Promise<{ query: string; count: number; messages: Message[] }> {
+  const query = `${search} newer_than:${days}d`;
+  const messages = await search_(query, limit);
+  return { query, count: messages.length, messages };
+}
+
+/**
+ * One message in full. The search runs again first and an id it does not
+ * return is refused, which is what makes the binding a boundary rather than a
+ * filter. Same check as the tool, because a job is not more trusted than a
+ * model here: it is only more predictable.
+ */
+export async function oneMessage({
+  search,
+  what,
+  days = 7,
+  limit = 10,
+  messageId,
+}: {
+  search: string;
+  what: string;
+  days?: number;
+  limit?: number;
+  messageId: string;
+}): Promise<{ query: string; message: unknown }> {
+  const { query, messages: found } = await messages({ search, days, limit });
+  if (!found.some((m) => m.id === messageId || m.threadId === messageId)) {
+    throw new Error(
+      `That message is not in ${what}. You can only read what this search listed. ` +
+        `If it is older than ${days} days, ask for more days.`,
+    );
+  }
+  const result = await run(GOG, ["gmail", "get", messageId, "--format", "full", "--json"], {
+    timeoutMs: 60_000,
+    env: gog(),
+  });
+  if (result.exitCode !== 0) throw new Error(explain(result.stderr || result.stdout));
+  return { query, message: JSON.parse(result.stdout) };
+}
+
+async function search_(query: string, max: number): Promise<Message[]> {
+  const result = await run(GOG, ["gmail", "search", query, "--max", String(max), "--json"], {
+    timeoutMs: 60_000,
+    env: gog(),
+  });
+  if (result.exitCode !== 0) throw new Error(explain(result.stderr || result.stdout));
+
+  // gog wraps results in an envelope on some commands and not others, so take
+  // whichever shape came back rather than assuming one.
+  const parsed: unknown = JSON.parse(result.stdout || "[]");
+  const rows = Array.isArray(parsed)
+    ? parsed
+    : ((parsed as Record<string, unknown>)?.messages ??
+       (parsed as Record<string, unknown>)?.threads ??
+       (parsed as Record<string, unknown>)?.results ??
+       []);
+  return (Array.isArray(rows) ? rows : []) as Message[];
+}
+
+/**
+ * The command a person runs to sign in again, built from the account that is
+ * actually configured rather than written down: no file in this repo may name
+ * a person. Signing in is the one fix an agent cannot do for itself, so the
+ * message carries the command ready to paste.
+ */
+function signIn(): string {
+  const account = gog().GOG_ACCOUNT;
+  return account ? `${GOG} auth login --account ${account}` : `${GOG} auth login`;
+}
+
+/**
+ * Turn the CLI's own failures into something an agent can act on, rather than
+ * letting "integrity check failed" reach a model that will retry it forever.
+ *
+ * Where a person has to do something, say exactly what, as a command they can
+ * paste. An agent that answers "you need to re-authenticate" has made someone
+ * go and look up how.
+ */
+export function explain(text: string): string {
+  if (/integrity check failed|KeyUnwrap/i.test(text)) {
+    return (
+      "Mail is not reachable: the saved Google login could not be opened, " +
+      "usually because google.password in settings.local.json does not match the one it was saved with. " +
+      `A person has to sign in again on the box, with this command exactly as written: ${signIn()} ` +
+      "Give them that command. Do not retry."
+    );
+  }
+  // The keyring opened but Google refused the saved refresh token: it expired,
+  // was revoked, or the account's password changed. Nothing an agent can do.
+  if (/invalid_grant|token has been expired or revoked/i.test(text)) {
+    return (
+      "Mail is not reachable: the saved Google sign-in has expired or was revoked. " +
+      `A person has to sign in again on the box, with this command exactly as written: ${signIn()} ` +
+      "Give them that command. Do not retry."
+    );
+  }
+  if (/no TTY|GOG_KEYRING_PASSWORD/i.test(text)) {
+    return (
+      "Mail is not reachable: google.password is not set, so the saved login cannot be opened. " +
+      "A person has to set it in settings.local.json and restart the service. Do not retry."
+    );
+  }
+  if (/missing --account|GOG_ACCOUNT/i.test(text)) {
+    return (
+      "Mail is not reachable: google.account is not set, so there is no account to read. " +
+      "A person has to set it in settings.local.json and restart the service. Do not retry."
+    );
+  }
+  return `Mail could not be read: ${text.trim().slice(0, 300)}`;
+}

package/do/run.ts

@@ -0,0 +1,56 @@
+// Running one command on this machine.
+//
+// Nothing here ever takes a shell string. The caller builds its own argument
+// list, so nothing a model says can be spliced into a command.
+import { execFile } from "node:child_process";
+
+/** What a command came back with. */
+export interface Result {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+const MAX_OUTPUT = 80_000;
+
+function clip(s: string): string {
+  return s.length > MAX_OUTPUT
+    ? `${s.slice(0, MAX_OUTPUT)}\n...[cut here, ${s.length} bytes in total]`
+    : s;
+}
+
+/**
+ * Runs one command with its arguments, never through a shell, and cuts output
+ * that is very long.
+ */
+export function run(
+  file: string,
+  args: string[],
+  options: { timeoutMs?: number; cwd?: string; env?: Record<string, string> } = {},
+): Promise<Result> {
+  return new Promise((done) => {
+    execFile(
+      file,
+      args,
+      {
+        cwd: options.cwd,
+        env: options.env ? { ...process.env, ...options.env } : undefined,
+        timeout: options.timeoutMs ?? 60_000,
+        maxBuffer: 1024 * 1024 * 16,
+        encoding: "utf8",
+      },
+      (error, stdout, stderr) => {
+        // execFile reports a missing binary as ENOENT, not as an exit code.
+        // Turn it into 127, the shell's "command not found", so a caller can
+        // tell "this program is not here" from "it ran and failed".
+        const code = (error as NodeJS.ErrnoException | null)?.code;
+        done({
+          exitCode:
+            typeof code === "number" ? code : code === "ENOENT" ? 127 : error ? 1 : 0,
+          stdout: clip(stdout ?? ""),
+          stderr: clip(stderr ?? "") || (code === "ENOENT" ? `${file}: not found` : ""),
+        });
+      },
+    );
+  });
+}