Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
20.7 KB
Raw Blame
// The tool calls of a turn (from the engine's messages) and what a shell
// command does to the file system, by a light parse of the command text:
// the folders it changes into or creates (cd, mkdir, git clone, npm create,
// cargo new, …), the files it writes (redirections, tee, cp/mv targets,
// curl -o, …), the scripts it runs (bash x.sh, python x.py, ./x, source x),
// the paths it names, and the on-the-fly tools it runs (npx, uvx, …).
// Nothing is executed; the parse errs on the side of naming too much (each
// path is checked on disk later).

import { basename, isAbsolute, join, resolve } from "node:path";

import { packageOfCommand } from "./setup.js";

export type ToolCall = {
  callId: string | null;
  tool: string;
  input: Record<string, unknown>;
  status: string | null;
  start: number | null;
  end: number | null;
  /** The shell command of a shell tool. */
  command: string | null;
  /** The directory the tool ran in (its workdir input), absolute. */
  cwd: string;
};

const SHELL_TOOLS = new Set(["bash", "shell", "sh", "zsh", "run_command", "run_shell_command", "exec", "terminal", "local_shell", "powershell", "cmd"]);
const READ_TOOLS = new Set(["read", "view", "cat", "file_read", "read_file", "open", "read_many_files", "readfile", "grep", "glob", "list", "ls"]);
const WRITE_TOOLS = new Set(["write", "edit", "multiedit", "multi_edit", "create", "file_write", "write_file", "patch", "apply_patch", "str_replace", "str_replace_editor", "notebook_edit", "notebookedit", "replace"]);
const PATH_KEYS = ["filePath", "file_path", "filepath", "path", "filename", "notebook_path", "absolute_path"];
const MAX_COMMAND_CHARS = 64 * 1024;

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

export function toolKind(tool: string): "shell" | "read" | "write" | "other" {
  const name = tool.trim().toLowerCase().split(/[.:/]/).at(-1) ?? "";
  if (SHELL_TOOLS.has(name)) return "shell";
  if (READ_TOOLS.has(name)) return "read";
  if (WRITE_TOOLS.has(name)) return "write";
  return "other";
}

export function expandHome(path: string, home: string | null): string | null {
  if (path === "~" || path === "$HOME" || path === "${HOME}") return home;
  if (path.startsWith("~/") || path.startsWith("~\\")) return home ? join(home, path.slice(2)) : null;
  // The shell's own spelling of the home folder.
  for (const prefix of ["$HOME/", "${HOME}/"]) if (path.startsWith(prefix)) return home ? join(home, path.slice(prefix.length)) : null;
  if (path.startsWith("~")) return null;
  return path;
}

/** The tool calls of a turn's messages, in the order they started. */
export function toolCallsOf(messages: unknown, root: string, home: string | null): ToolCall[] {
  const list = Array.isArray(messages) ? messages : isRecord(messages) && Array.isArray(messages.messages) ? messages.messages : [];
  const out: ToolCall[] = [];
  for (const message of list) {
    if (!isRecord(message) || !Array.isArray(message.parts)) continue;
    for (const part of message.parts) {
      if (!isRecord(part) || part.type !== "tool") continue;
      const tool = typeof part.tool === "string" ? part.tool : typeof part.name === "string" ? part.name : "";
      if (!tool) continue;
      const state = isRecord(part.state) ? part.state : {};
      const input = isRecord(state.input) ? state.input : isRecord(part.input) ? part.input : {};
      const time = isRecord(state.time) ? state.time : {};
      const workdir = ["workdir", "cwd", "directory", "working_directory"].map((key) => input[key]).find((value) => typeof value === "string" && value.trim()) as string | undefined;
      const expanded = workdir ? expandHome(workdir.trim(), home) : null;
      const rawCommand = input.command ?? input.cmd ?? input.script;
      const command = typeof rawCommand === "string" ? rawCommand : Array.isArray(rawCommand) && rawCommand.every((item) => typeof item === "string") ? rawCommand.join(" ") : null;
      out.push({
        callId: typeof part.callID === "string" ? part.callID : typeof part.callId === "string" ? part.callId : typeof part.id === "string" ? part.id : null,
        tool,
        input,
        status: typeof state.status === "string" ? state.status : null,
        start: typeof time.start === "number" ? time.start : null,
        end: typeof time.end === "number" ? time.end : null,
        command: toolKind(tool) === "shell" ? command : null,
        cwd: expanded ? resolve(root, expanded) : root,
      });
    }
  }
  return out.map((call, index) => ({ call, index })).sort((a, b) => (a.call.start ?? 0) - (b.call.start ?? 0) || a.index - b.index).map(({ call }) => call);
}

/** File paths a read or write tool names (absolute). */
export function toolPaths(call: ToolCall, home: string | null): string[] {
  const out: string[] = [];
  const add = (value: unknown) => {
    if (typeof value !== "string" || !value.trim() || value.includes("\n") || value.length > 4096) return;
    const expanded = expandHome(value.trim(), home);
    if (expanded) out.push(resolve(call.cwd, expanded));
  };
  for (const key of PATH_KEYS) add(call.input[key]);
  if (Array.isArray(call.input.paths)) for (const value of call.input.paths) add(value);
  for (const key of ["patchText", "patch"]) {
    const body = call.input[key];
    if (typeof body === "string") for (const match of body.matchAll(/^\*\*\* (?:(?:Update|Add) File|Move to):[ \t]*(.+)$/gm)) add(match[1]);
  }
  return out;
}

// --- shell parsing --------------------------------------------------------------------

export type Token = { word: string } | { op: string };

/** Words and control/redirection operators; quotes and backslashes honoured; heredoc bodies skipped. */
export function tokenize(command: string): Token[] {
  const text = command.length > MAX_COMMAND_CHARS ? command.slice(0, MAX_COMMAND_CHARS) : command;
  const tokens: Token[] = [];
  let word = "";
  let started = false;
  let quote: "'" | '"' | null = null;
  const heredocs: string[] = [];
  const end = () => {
    if (started) tokens.push({ word });
    word = "";
    started = false;
  };
  for (let i = 0; i < text.length; i += 1) {
    const char = text[i]!;
    if (quote === "'") {
      if (char === "'") quote = null;
      else word += char;
      continue;
    }
    if (quote === '"') {
      if (char === '"') quote = null;
      else if (char === "\\" && '"\\$`'.includes(text[i + 1] ?? "")) word += text[++i]!;
      else word += char;
      continue;
    }
    if (char === "'" || char === '"') {
      quote = char;
      started = true;
      continue;
    }
    if (char === "\\" && text[i + 1] !== undefined && text[i + 1] !== "\n") {
      word += text[++i]!;
      started = true;
      continue;
    }
    if (char === "\n") {
      end();
      tokens.push({ op: "\n" });
      // Heredoc bodies: skip lines until each delimiter.
      while (heredocs.length > 0) {
        const delimiter = heredocs.shift()!;
        let next = text.indexOf("\n", i + 1);
        while (true) {
          const line = text.slice(i + 1, next < 0 ? undefined : next);
          i = next < 0 ? text.length : next;
          if (line.trim() === delimiter || next < 0) break;
          next = text.indexOf("\n", i + 1);
        }
      }
      continue;
    }
    if (char === "#" && !started) {
      while (i + 1 < text.length && text[i + 1] !== "\n") i += 1;
      continue;
    }
    if (/\s/.test(char)) {
      end();
      continue;
    }
    const three = text.slice(i, i + 3);
    const two = text.slice(i, i + 2);
    if (two === "<<" && three !== "<<<") {
      end();
      let j = i + 2;
      if (text[j] === "-") j += 1;
      while (text[j] === " ") j += 1;
      const match = /^(['"]?)([\w.-]+)\1/.exec(text.slice(j));
      if (match) {
        heredocs.push(match[2]!);
        i = j + match[0].length - 1;
      } else {
        i += 1;
      }
      tokens.push({ op: "<<" });
      continue;
    }
    const ops = ["&>>", "2>>", "&&", "||", ">>", "2>", "&>", ">|", ";", "|", "&", ">", "<", "(", ")", "`"];
    const op = ops.find((candidate) => text.startsWith(candidate, i));
    if (op && !(op === "2>" && started) && !(op === "2>>" && started)) {
      end();
      if (op === "&" && text[i + 1] === ">") continue;
      tokens.push({ op });
      i += op.length - 1;
      continue;
    }
    word += char;
    started = true;
  }
  end();
  return tokens;
}

const SEPARATORS = new Set([";", "&&", "||", "|", "&", "\n", "(", ")", "`"]);
const REDIRECT_WRITE = new Set([">", ">>", "2>", "2>>", "&>", "&>>", ">|"]);

/** Simple commands: words, the files they redirect into, and the operator before each. */
export function simpleCommands(command: string): Array<{ words: string[]; writes: string[]; reads: string[]; after: string | null }> {
  const out: Array<{ words: string[]; writes: string[]; reads: string[]; after: string | null }> = [];
  let current = { words: [] as string[], writes: [] as string[], reads: [] as string[], after: null as string | null };
  let pending: "write" | "read" | "skip" | null = null;
  for (const token of tokenize(command)) {
    if ("op" in token) {
      if (SEPARATORS.has(token.op)) {
        if (current.words.length || current.writes.length) out.push(current);
        current = { words: [], writes: [], reads: [], after: token.op };
        pending = null;
      } else if (REDIRECT_WRITE.has(token.op)) pending = "write";
      else if (token.op === "<") pending = "read";
      else if (token.op === "<<") pending = null;
      continue;
    }
    if (pending) {
      if (pending === "write" && !/^&\d$|^\/dev\//.test(token.word)) current.writes.push(token.word);
      if (pending === "read" && !token.word.startsWith("/dev/")) current.reads.push(token.word);
      pending = null;
      continue;
    }
    // Leading assignments (FOO=bar cmd) are not the command.
    if (current.words.length === 0 && /^[A-Za-z_][\w]*=/.test(token.word)) continue;
    current.words.push(token.word);
  }
  if (current.words.length || current.writes.length) out.push(current);
  return out;
}

export type FolderVia = "cd" | "mkdir" | "git clone" | "create" | "cargo new" | "init" | "copy" | "extract" | "workdir";
export type CommandEffects = {
  /** Folders the command changes into (`cd`) or creates. */
  folders: Array<{ path: string; via: FolderVia; created: boolean }>;
  /** Files it writes or modifies. */
  writes: string[];
  /** Scripts it runs (interpreted or executed by path). */
  executed: string[];
  /** Every path-like word, resolved (read/used candidates). */
  named: string[];
  /** On-the-fly tools. */
  ephemeral: Array<{ runner: string; package: string; requested: string | null }>;
};

const INTERPRETERS = new Set(["bash", "sh", "zsh", "dash", "ksh", "fish", "python", "python2", "python3", "node", "nodejs", "ruby", "perl", "php", "tsx", "ts-node", "pwsh", "powershell", "Rscript", "lua", "osascript", "groovy"]);
const VALUE_FLAGS: Record<string, Set<string>> = {
  git: new Set(["-b", "--branch", "--depth", "-o", "--origin", "-c", "--config", "--reference", "--filter", "-j", "--jobs", "--template", "--separate-git-dir", "-u", "--upload-pack", "--shallow-since", "--shallow-exclude"]),
};

function isPathLike(word: string): boolean {
  if (!word || word.length > 4096 || word.includes("://") || /[*?{}$]/.test(word) || word.startsWith("-")) return false;
  return /^(?:\/|~[\\/]|~$|\.{1,2}[\\/]|[A-Za-z]:[\\/])/.test(word) || word.includes("/") || /^[^\\/=:@]+\.[A-Za-z0-9]{1,12}$/.test(word);
}

/** The folder name `git clone <url>` makes when no directory is given. */
export function cloneDirName(url: string): string | null {
  const trimmed = url.replace(/[\\/]+$/, "").replace(/\.git$/, "");
  const name = trimmed.split(/[\\/:]/).at(-1);
  return name && name !== "." && name !== ".." ? name : null;
}

/**
 * What a shell command does to the file system, resolved against `cwd`
 * (which `cd` moves for the rest of an `&&`/`;` chain).
 */
export function commandEffects(command: string, cwd: string, home: string | null): CommandEffects {
  const effects: CommandEffects = { folders: [], writes: [], executed: [], named: [], ephemeral: [] };
  let dir = cwd;
  const abs = (value: string): string | null => {
    const expanded = expandHome(value, home);
    if (!expanded || expanded.includes("\0")) return null;
    return isAbsolute(expanded) ? resolve(expanded) : resolve(dir, expanded);
  };
  const folder = (value: string | undefined, via: FolderVia, created: boolean) => {
    if (!value || value.startsWith("-")) return;
    const path = abs(value);
    if (path) effects.folders.push({ path, via, created });
  };
  const nonFlags = (words: string[], from: number, valueFlags: Set<string> = new Set()) => {
    const out: string[] = [];
    for (let i = from; i < words.length; i += 1) {
      const word = words[i]!;
      if (word === "--") continue;
      if (word.startsWith("-")) {
        if (valueFlags.has(word)) i += 1;
        continue;
      }
      out.push(word);
    }
    return out;
  };
  for (const simple of simpleCommands(command)) {
    for (const target of simple.writes) {
      const path = abs(target);
      if (path) effects.writes.push(path);
    }
    for (const source of simple.reads) {
      const path = abs(source);
      if (path) effects.named.push(path);
    }
    let words = simple.words;
    // sudo/env/time/nohup/exec prefixes.
    while (words.length > 1 && ["sudo", "env", "time", "nohup", "exec", "command", "nice", "xargs"].includes(words[0]!)) {
      words = words.slice(1);
      while (words.length > 1 && (words[0]!.startsWith("-") || /^[A-Za-z_]\w*=/.test(words[0]!))) words = words.slice(1);
    }
    if (words.length === 0) continue;
    const head = basename(words[0]!).replace(/\.(?:exe|cmd)$/i, "");
    for (const word of words.slice(1)) {
      const value = word.startsWith("-") && word.includes("=") ? word.slice(word.indexOf("=") + 1) : word;
      if (isPathLike(value)) {
        const path = abs(value);
        if (path) effects.named.push(path);
      }
    }
    const spec = packageOfCommand(words);
    if (spec) {
      const runner = words[0] && ["pnpm", "yarn", "npm", "bun", "pipx", "uv"].includes(head) ? `${head} ${words[1]}` : head;
      effects.ephemeral.push({ runner: runner === "npm exec" ? "npx" : runner === "uv tool" ? "uvx" : runner, package: spec.package, requested: spec.version });
    }
    switch (head) {
      case "cd":
      case "pushd":
      case "Set-Location":
      case "sl": {
        const target = nonFlags(words, 1)[0];
        const path = target ? abs(target) : home;
        if (path) {
          effects.folders.push({ path, via: "cd", created: false });
          dir = path;
        }
        break;
      }
      case "mkdir":
      case "md":
      case "New-Item":
        for (const target of nonFlags(words, 1, new Set(["-m", "--mode", "-ItemType", "-Path"]))) folder(target, "mkdir", true);
        break;
      case "git": {
        const sub = nonFlags(words, 1, new Set(["-C", "-c"]));
        if (sub[0] === "clone") {
          const args = nonFlags(words, words.indexOf("clone") + 1, VALUE_FLAGS.git);
          const target = args[1] ?? (args[0] ? cloneDirName(args[0]) ?? undefined : undefined);
          folder(target, "git clone", true);
        } else if (sub[0] === "init" && sub[1]) folder(sub[1], "init", true);
        break;
      }
      case "npm":
      case "pnpm":
      case "yarn":
      case "bun": {
        const sub = words[1];
        if (sub === "dlx") {
          const args = nonFlags(words, 2);
          if (args[0] && /(?:^|\/)create-/.test(args[0])) folder(args[1], "create", true);
        } else if (sub === "create" || (sub === "init" && words[2] && !words[2].startsWith("-"))) {
          const args = nonFlags(words, 2);
          folder(args[1], "create", true);
        }
        break;
      }
      case "npx":
      case "pnpx":
      case "bunx": {
        const args = nonFlags(words, 1);
        if (args[0] && /(?:^|\/)create-/.test(args[0])) folder(args[1], "create", true);
        break;
      }
      case "cargo":
        if (words[1] === "new" || words[1] === "init") folder(nonFlags(words, 2, new Set(["--name", "--vcs", "--edition"]))[0], "cargo new", true);
        break;
      case "uv":
      case "poetry":
        if (words[1] === "init" || words[1] === "new") folder(nonFlags(words, 2)[0], "init", true);
        break;
      case "rails":
      case "django-admin":
        if (words[1] === "new" || words[1] === "startproject") folder(nonFlags(words, 2)[head === "rails" ? 0 : 1] ?? nonFlags(words, 2)[0], "create", true);
        break;
      case "composer":
        if (words[1] === "create-project") folder(nonFlags(words, 2)[1], "create", true);
        break;
      case "dotnet": {
        const at = words.findIndex((word) => word === "-o" || word === "--output");
        if (words[1] === "new" && at > 0) folder(words[at + 1], "create", true);
        break;
      }
      case "cp":
      case "rsync":
      case "Copy-Item": {
        const args = nonFlags(words, 1, new Set(["-t", "--target-directory", "-e"]));
        const target = args.at(-1);
        if (target && args.length >= 2) {
          const recursive = words.some((word) => /^-[a-zA-Z]*[rRa]/.test(word) || word === "--recursive" || word === "-Recurse") || head === "rsync";
          if (recursive) folder(target, "copy", true);
          else {
            const path = abs(target);
            if (path) effects.writes.push(path);
          }
        }
        break;
      }
      case "mv":
      case "Move-Item": {
        const args = nonFlags(words, 1);
        const path = args.length >= 2 ? abs(args.at(-1)!) : null;
        if (path) effects.writes.push(path);
        break;
      }
      case "tee":
      case "touch":
      case "Out-File":
      case "Set-Content":
        for (const target of nonFlags(words, 1)) {
          const path = abs(target);
          if (path) effects.writes.push(path);
        }
        break;
      case "sed":
      case "perl":
        if (words.some((word) => /^-[a-zA-Z]*i/.test(word))) {
          const target = nonFlags(words, 1, new Set(["-e", "-f"])).at(-1);
          const path = target ? abs(target) : null;
          if (path) effects.writes.push(path);
        }
        break;
      case "curl":
      case "wget": {
        const at = words.findIndex((word) => word === "-o" || word === "--output" || word === "-O" && head === "wget" || word === "--output-document");
        const value = at > 0 ? words[at + 1] : words.find((word) => /^--output(?:-document)?=/.test(word))?.split("=").slice(1).join("=");
        const path = value && value !== "-" ? abs(value) : null;
        if (path) effects.writes.push(path);
        break;
      }
      case "tar": {
        const at = words.findIndex((word) => word === "-C" || word === "--directory");
        if (at > 0 && words.some((word) => /^-?[a-zA-Z]*x/.test(word) || word === "--extract")) folder(words[at + 1], "extract", true);
        break;
      }
      case "unzip": {
        const at = words.indexOf("-d");
        if (at > 0) folder(words[at + 1], "extract", true);
        break;
      }
      case "source":
      case ".": {
        const path = words[1] ? abs(words[1]) : null;
        if (path) effects.executed.push(path);
        break;
      }
      default:
        break;
    }
    // Scripts run by an interpreter or by path.
    if (INTERPRETERS.has(head) || /^python\d+(?:\.\d+)*$/.test(head)) {
      const args = nonFlags(words, 1, new Set(["-m", "-c", "-e", "--eval", "-r", "--require", "-W", "-X", "--import", "--loader"]));
      if (!words.includes("-c") && !words.includes("-m") && !words.includes("-e") && !words.includes("--eval") && args[0]) {
        const path = abs(args[0]);
        if (path) effects.executed.push(path);
      }
    } else if (/[\\/]/.test(words[0]!) && !words[0]!.endsWith("/")) {
      const path = abs(words[0]!);
      if (path) effects.executed.push(path);
    } else if ((head === "deno" || head === "bun") && words[1] === "run" && words[2] && isPathLike(words[2])) {
      const path = abs(words[2]);
      if (path) effects.executed.push(path);
    }
    // Deno npm:/jsr: specifiers and `go run pkg@version` are on-the-fly tools too.
    if (head === "deno") {
      const spec = words.find((word) => /^(?:npm|jsr):/.test(word));
      if (spec) {
        const body = spec.replace(/^(?:npm|jsr):/, "");
        const at = body.lastIndexOf("@");
        effects.ephemeral.push({ runner: "deno run", package: `${spec.startsWith("jsr:") ? "jsr:" : ""}${at > 0 ? body.slice(0, at) : body}`, requested: at > 0 ? body.slice(at + 1).split("/")[0] || null : null });
      }
    }
    if (head === "go" && words[1] === "run") {
      const target = nonFlags(words, 2).find((word) => /^[\w.-]+\.[\w-]+\/[^@\s]+@\S+$/.test(word));
      if (target) {
        const at = target.lastIndexOf("@");
        effects.ephemeral.push({ runner: "go run", package: target.slice(0, at), requested: target.slice(at + 1) });
      }
    }
  }
  return effects;
}