talon-agent 5.0.0 → 5.0.1

package/src/core/engine/gateway-actions/native.ts

@@ -1,1035 +0,0 @@
-/**
- * Native tools — Talon's own shell/filesystem tools, replacing the SDK's
- * built-in Bash/Read/Write/Edit/Glob/Grep when `config.nativeTools` is on.
- *
- * Their defining feature: every one checks the current chat's active
- * `teleport` target. With no teleport for that chat, they run on the daemon
- * host (local spawn / local fs / local ripgrep). With a teleport engaged, they
- * run ON the companion device via the mesh exec/fs channel — so
- * `bash`/`read`/`write`/… transparently operate on the phone for that chat.
- *
- *   teleport(device)  → native tools target that device
- *   teleport_back()   → native tools run locally again
- *
- * The teleported path reuses the exec/fs command surface on MeshService; the
- * local path is a thin, well-scoped reimplementation of the built-ins.
- */
-
-import { spawn } from "node:child_process";
-import { closeSync, openSync } from "node:fs";
-import {
-  glob as fsGlob,
-  mkdir,
-  readFile,
-  stat as fsStat,
-  writeFile,
-} from "node:fs/promises";
-import { homedir, tmpdir } from "node:os";
-import { dirname, extname, join } from "node:path";
-import { getMeshService } from "../../mesh/index.js";
-import {
-  clearTeleport,
-  getTeleport,
-  setTeleport,
-  setTeleportCwd,
-} from "../../mesh/teleport.js";
-import {
-  clampExecOutput,
-  createOutputCapture,
-} from "../../../util/exec-output.js";
-import type { SharedActionHandlers } from "./types.js";
-
-type Result = {
-  ok: boolean;
-  text: string;
-  /** Set for image files so the tool result carries a viewable image block. */
-  image?: { data: string; mimeType: string };
-};
-
-/**
- * ripgrep binary, resolved from PATH (env-overridable for tests). NOT a
- * hardcoded absolute path: /usr/bin/rg only exists on some Linux installs,
- * and a missing binary must fall back loudly (or to the pure-JS walker),
- * never masquerade as "no matches".
- */
-function rgBin(): string {
-  return process.env.TALON_NATIVE_RG ?? "rg";
-}
-const DEFAULT_EXEC_TIMEOUT_MS = 60_000;
-const MAX_EXEC_TIMEOUT_MS = 300_000;
-/** Grace between SIGTERM and SIGKILL on timeout, so pipelines can flush. */
-const KILL_GRACE_MS = 2_000;
-/** How long a background launch waits to catch fast failures. */
-const BACKGROUND_SETTLE_MS = 1_200;
-/** Where background job output lands (one log file per job). */
-const BACKGROUND_LOG_DIR = join(tmpdir(), "talon-bash");
-/** Appended to a timed-out bash result so the model self-corrects. */
-const TIMEOUT_HINT =
-  "(Streaming/never-ending commands — adb logcat, tail -f, dev servers, watchers — " +
-  "will always hit this wall. Re-run with background:true to launch it detached with " +
-  "output captured to a log file, or bound the command itself: `adb logcat -d`, " +
-  "`timeout 30 …`, `head -n 200`.)";
-/** Same self-correction hint, phrased for a teleported (on-device) run. */
-const TELEPORT_TIMEOUT_HINT =
-  "(Streaming/never-ending commands can't ride a teleported foreground call — " +
-  "background it in-shell instead: `cmd > /tmp/out.log 2>&1 &`, then poll the log " +
-  "with read, or bound the command itself: `logcat -d`, `timeout 30 …`, `head -n 200`.)";
-const MAX_READ_LINES = 2_000;
-/**
- * Refuse to slurp huge files into memory: `read` loads the whole file to
- * slice lines, so an unbounded readFile of a multi-GB log balloons RSS.
- * Past this, bash is the right tool (`sed -n`, `tail`, `head`).
- */
-const MAX_READ_FILE_BYTES = 32 * 1024 * 1024;
-/**
- * Image extensions the model can actually view, mapped to their MIME type.
- * Reading one returns an image content block instead of the file's raw bytes
- * decoded as (garbage) UTF-8 — so `read`ing a photo/screenshot/design shows
- * the picture, not mojibake.
- */
-const IMAGE_MIME: Record<string, string> = {
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-};
-/** Anthropic caps a single image around 5MB; refuse larger with a downscale hint. */
-const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
-/** Caps for the pure-JS glob/search fallbacks (rg unavailable). */
-const MAX_JS_RESULTS = 2_000;
-const MAX_JS_FILE_BYTES = 2 * 1024 * 1024;
-const SKIP_DIRS_RE = /(^|[\\/])(node_modules|\.git)([\\/]|$)/;
-/** Markers used to recover the post-command working dir from a teleport shell. */
-const CWD_OPEN = "__TALON_CWD__";
-const CWD_CLOSE = "__TALON_CWD_END__";
-
-export const nativeHandlers: SharedActionHandlers = {
-  teleport: (body, chatId) => teleport(chatId, body.device),
-  teleport_back: (_body, chatId) => teleportBack(chatId),
-  native_bash: (body, chatId) =>
-    bash(chatId, body.command, body.cwd, body.timeout_sec, body.background),
-  native_read: (body, chatId) =>
-    read(chatId, body.path, body.offset, body.limit),
-  native_write: (body, chatId) => write(chatId, body.path, body.content),
-  native_edit: (body, chatId) =>
-    edit(chatId, body.path, body.old_string, body.new_string, body.replace_all),
-  native_glob: (body, chatId) => glob(chatId, body.pattern, body.path),
-  native_search: (body, chatId) =>
-    search(chatId, body.pattern, body.path, body.glob, body.case_insensitive),
-};
-
-// ── Teleport control ────────────────────────────────────────────────────────
-
-async function teleport(chatId: number, query: unknown): Promise<Result> {
-  const svc = getMeshService();
-  await svc.list();
-  const resolved = svc.resolveDevice(query);
-  if ("error" in resolved) return { ok: false, text: resolved.error };
-  const target = resolved.target;
-  if (!target.online) {
-    return {
-      ok: false,
-      text: `${target.name} appears offline — cannot teleport onto a device that isn't connected.`,
-    };
-  }
-  if (target.capabilities && !target.capabilities.includes("exec")) {
-    return {
-      ok: false,
-      text: `${target.name} does not advertise the "exec" capability, so teleport can't run commands on it.`,
-    };
-  }
-  await setTeleport(chatId, target.id, target.name);
-  return {
-    ok: true,
-    text: [
-      `🛰️ Teleported onto ${target.name}. Native bash/read/write/edit/glob/search now run ON that device.`,
-      `Working dir starts at the device default; \`cd\` in bash persists across calls.`,
-      `Call teleport_back to return to the daemon host.`,
-    ].join(" "),
-  };
-}
-
-async function teleportBack(chatId: number): Promise<Result> {
-  const prior = await clearTeleport(chatId);
-  return {
-    ok: true,
-    text: prior
-      ? `↩️ Teleported back from ${prior.deviceName}. Native tools run on the daemon host again.`
-      : "Not teleported — native tools already run on the daemon host.",
-  };
-}
-
-// ── bash ────────────────────────────────────────────────────────────────────
-
-async function bash(
-  chatId: number,
-  command: unknown,
-  cwd: unknown,
-  timeoutSec: unknown,
-  background?: unknown,
-): Promise<Result> {
-  const cmd = typeof command === "string" ? command : "";
-  if (!cmd.trim()) return { ok: false, text: "No command given." };
-  const timeoutMs = clampTimeout(timeoutSec);
-  const active = await getTeleport(chatId);
-
-  let dir = typeof cwd === "string" && cwd.trim() ? cwd.trim() : undefined;
-  if (dir !== undefined && !active) {
-    dir = resolvePathParam(dir, undefined);
-    // Validate here: a bad cwd makes spawn fail with "spawn bash ENOENT",
-    // which reads as "bash is missing" and sends the model down the wrong
-    // path. Name the actual problem instead.
-    try {
-      const st = await fsStat(dir);
-      if (!st.isDirectory())
-        return { ok: false, text: `cwd is not a directory: ${dir}` };
-    } catch {
-      return { ok: false, text: `Working directory does not exist: ${dir}` };
-    }
-  }
-
-  const result = await (async () => {
-    if (background === true) {
-      if (active) {
-        return {
-          ok: false,
-          text:
-            "background:true runs on the daemon host only. On a teleported device, " +
-            "background it in-shell instead: `cmd > /tmp/out.log 2>&1 &`, then poll " +
-            "the log with read.",
-        };
-      }
-      return bashBackground(cmd, dir);
-    }
-    if (active) return bashTeleported(chatId, active.deviceId, cmd, timeoutMs);
-    return bashLocal(cmd, dir, timeoutMs);
-  })();
-  return result;
-}
-
-/**
- * Launch a command detached from the request cycle: its own process group,
- * stdout+stderr appended to a per-job log file, tool returns immediately.
- * This is the sanctioned path for streaming/long-running commands (adb
- * logcat, dev servers, watchers) that would otherwise burn the whole
- * foreground timeout and come back "killed".
- *
- * A short settle window catches fast failures (typo'd binary, instant
- * non-zero exit) so those still surface as a normal error instead of a
- * "started" message pointing at a log with one line in it.
- */
-async function bashBackground(
-  cmd: string,
-  cwd: string | undefined,
-): Promise<Result> {
-  // The background contract is POSIX-shaped end to end: detached process
-  // group, `kill -- -pid` to stop, survives daemon restarts. Windows has
-  // none of those (and the CI legs showed the detached writer's output not
-  // reaching the log) — refuse loudly with the native alternative instead
-  // of pretending.
-  if (process.platform === "win32") {
-    return {
-      ok: false,
-      text:
-        "background:true needs POSIX process groups and isn't supported on a Windows " +
-        "daemon host. Run it foreground with a bound command (`timeout 30 …`, `head -n 200`) " +
-        "or start it yourself: `powershell Start-Process -WindowStyle Hidden` with output redirected to a file.",
-    };
-  }
-  try {
-    await mkdir(BACKGROUND_LOG_DIR, { recursive: true });
-  } catch (err) {
-    return {
-      ok: false,
-      text: `Cannot create log dir ${BACKGROUND_LOG_DIR}: ${(err as Error).message}`,
-    };
-  }
-  const slug =
-    cmd
-      .replace(/[^a-zA-Z0-9]+/g, "-")
-      .replace(/^-+|-+$/g, "")
-      .slice(0, 40) || "job";
-  const logPath = join(BACKGROUND_LOG_DIR, `${Date.now()}-${slug}.log`);
-  let fd: number;
-  try {
-    fd = openSync(logPath, "a");
-  } catch (err) {
-    return {
-      ok: false,
-      text: `Cannot open log file ${logPath}: ${(err as Error).message}`,
-    };
-  }
-  // Always detached: the win32 guard above returned already, so this only
-  // runs on POSIX where the job gets its own process group.
-  const child = spawn("bash", ["-c", cmd], {
-    ...(cwd ? { cwd } : {}),
-    env: process.env,
-    detached: true,
-    stdio: ["ignore", fd, fd],
-  });
-  return new Promise((resolvePromise) => {
-    let settled = false;
-    const done = (r: Result) => {
-      if (settled) return;
-      settled = true;
-      try {
-        closeSync(fd);
-      } catch {
-        // parent's dup only; the child keeps its own copy either way
-      }
-      resolvePromise(r);
-    };
-    child.on("error", (err) =>
-      done({ ok: false, text: `Failed to start: ${err.message}` }),
-    );
-    // Fast failure inside the settle window → report it like a normal run.
-    child.on("close", (code) => {
-      void (async () => {
-        let logged = "";
-        try {
-          logged = await readFile(logPath, "utf8");
-        } catch {
-          // log unreadable — report the exit alone
-        }
-        done({
-          ok: (code ?? 0) === 0,
-          text:
-            `Background command exited almost immediately (exit ${code ?? 0}).\n` +
-            renderExec("local", `exit ${code ?? 0}`, logged, "") +
-            `\nFull log: ${logPath}`,
-        });
-      })();
-    });
-    setTimeout(() => {
-      if (settled) return;
-      child.unref();
-      done({
-        ok: true,
-        text: [
-          `🚀 Started in background [local] — pid ${child.pid}.`,
-          `Output (stdout+stderr) → ${logPath}`,
-          `Follow it with read/bash (e.g. \`tail -n 50 ${logPath}\`).`,
-          `Stop it with \`kill -- -${child.pid}\` (whole process group).`,
-          `Unsupervised: it keeps running until it exits or is killed — it even survives a Talon restart.`,
-        ].join("\n"),
-      });
-    }, BACKGROUND_SETTLE_MS);
-  });
-}
-
-function bashLocal(
-  cmd: string,
-  cwd: string | undefined,
-  timeoutMs: number,
-): Promise<Result> {
-  return new Promise((resolvePromise) => {
-    // detached → own process group on POSIX, so a timeout can kill the whole
-    // tree (bash's children included), not just the shell itself.
-    const detached = process.platform !== "win32";
-    const child = spawn("bash", ["-c", cmd], {
-      ...(cwd ? { cwd } : {}),
-      env: process.env,
-      detached,
-    });
-    const stdout = createOutputCapture();
-    const stderr = createOutputCapture();
-    let killed = false;
-    // Timeout escalation: SIGTERM the whole process group first (lets
-    // pipelines flush + children clean up), SIGKILL any survivors after a
-    // short grace. Straight-to-SIGKILL used to eat buffered output.
-    const killTree = (signal: NodeJS.Signals) => {
-      if (detached && child.pid) {
-        try {
-          process.kill(-child.pid, signal);
-          return;
-        } catch {
-          // group already gone — fall through to the direct kill
-        }
-      }
-      try {
-        child.kill(signal);
-      } catch {
-        // already dead
-      }
-    };
-    let settled = false;
-    let killTimer: NodeJS.Timeout | undefined;
-    let forceTimer: NodeJS.Timeout | undefined;
-    const finish = (r: Result) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (killTimer) clearTimeout(killTimer);
-      if (forceTimer) clearTimeout(forceTimer);
-      resolvePromise(r);
-    };
-    const timedOutResult = () => {
-      const body = renderExec(
-        "local",
-        `⏱️ timed out after ${timeoutMs / 1000}s — killed; partial output kept below`,
-        stdout.value(),
-        stderr.value(),
-      );
-      return { ok: false, text: `${body}\n${TIMEOUT_HINT}` };
-    };
-    const timer = setTimeout(() => {
-      killed = true;
-      killTree("SIGTERM");
-      killTimer = setTimeout(() => killTree("SIGKILL"), KILL_GRACE_MS);
-      // `close` waits for the stdio pipes to drain — a surviving grandchild
-      // that inherited stdout (Windows has no process groups; a detached
-      // POSIX grandchild can escape the group kill) would otherwise hold
-      // this promise open long past the timeout. Force-resolve with the
-      // partial output once the escalation window has passed.
-      forceTimer = setTimeout(
-        () => finish(timedOutResult()),
-        KILL_GRACE_MS + 1_000,
-      );
-    }, timeoutMs);
-    child.stdout.on("data", stdout.push);
-    child.stderr.on("data", stderr.push);
-    child.on("error", (err) => {
-      finish({ ok: false, text: `Failed to run: ${err.message}` });
-    });
-    child.on("close", (code) => {
-      if (killed) {
-        finish(timedOutResult());
-        return;
-      }
-      finish({
-        ok: (code ?? 0) === 0,
-        text: renderExec(
-          "local",
-          `exit ${code ?? 0}`,
-          stdout.value(),
-          stderr.value(),
-        ),
-      });
-    });
-  });
-}
-
-async function bashTeleported(
-  chatId: number,
-  deviceId: string,
-  cmd: string,
-  timeoutMs: number,
-): Promise<Result> {
-  const active = await getTeleport(chatId);
-  const cwd = active?.cwd;
-  // Wrap so the resulting working dir is reported back and persists across
-  // calls (a `cd` in `cmd` carries forward), while the real exit code is
-  // preserved. printf can't fail in a way that masks the command's status.
-  const wrapped =
-    `${cwd ? `cd ${shellQuote(cwd)} 2>/dev/null; ` : ""}` +
-    `{ ${cmd}\n}; __talon_rc=$?; ` +
-    `printf '${CWD_OPEN}%s${CWD_CLOSE}' "$(pwd 2>/dev/null)"; exit $__talon_rc`;
-  const dispatched = await getMeshService().dispatchCommand(
-    deviceId,
-    "exec",
-    { cmd: wrapped, timeoutMs },
-    timeoutMs + 5_000,
-  );
-  if ("error" in dispatched) return { ok: false, text: dispatched.error };
-  const { target, result } = dispatched;
-  const data = result.data ?? {};
-  let stdout = typeof data.stdout === "string" ? data.stdout : "";
-  const stderr = typeof data.stderr === "string" ? data.stderr : "";
-  const via =
-    typeof data.via === "string" && data.via ? ` via ${data.via}` : "";
-  const exitCode =
-    typeof data.exitCode === "number" ? data.exitCode : undefined;
-  // Recover + strip the trailing cwd marker.
-  const open = stdout.lastIndexOf(CWD_OPEN);
-  if (open !== -1) {
-    const close = stdout.indexOf(CWD_CLOSE, open);
-    if (close !== -1) {
-      const newCwd = stdout.slice(open + CWD_OPEN.length, close).trim();
-      stdout = stdout.slice(0, open);
-      if (newCwd) await setTeleportCwd(chatId, newCwd);
-    }
-  }
-  if (!result.ok && exitCode === undefined) {
-    return {
-      ok: false,
-      text: result.message ?? `${target.name} could not run the command.`,
-    };
-  }
-  // The device marks a command it had to kill at its own exec budget with
-  // this stderr marker (see the companion's device_exec) — surface the same
-  // self-correction hint the local timeout path gets.
-  const timedOutOnDevice = stderr.includes("[killed: timeout]");
-  const body = renderExec(
-    `${target.name}${via}`,
-    `exit ${exitCode ?? "?"}`,
-    stdout,
-    stderr,
-  );
-  return {
-    ok: exitCode === 0,
-    text: timedOutOnDevice ? `${body}\n${TELEPORT_TIMEOUT_HINT}` : body,
-  };
-}
-
-// ── path parameter resolution ───────────────────────────────────────────────
-
-/** Expand a leading `~` — local runs only; a device's home is not ours. */
-function expandHome(path: string): string {
-  if (path === "~") return homedir();
-  if (path.startsWith("~/")) return join(homedir(), path.slice(2));
-  return path;
-}
-
-/**
- * One rule for every path parameter: `~` expands (local runs only),
- * everything else passes through untouched.
- *
- * The namespace has no tool-facing address scheme — its nodes are reached
- * by their real paths (`~/.talon/ns/…`, kept real by the symlink farm in
- * nsdir.ts and the FUSE layer in fusefs.ts). Real paths need no
- * translation and behave identically here, in a bare shell, in another
- * backend's built-in shell (Codex), and in any spawned child process.
- * Teleported, paths belong to the device and pass through verbatim.
- */
-function resolvePathParam(
-  path: string,
-  teleportedTo: string | undefined,
-): string {
-  return teleportedTo !== undefined ? path : expandHome(path);
-}
-
-// ── read / write / edit ─────────────────────────────────────────────────────
-
-async function read(
-  chatId: number,
-  path: unknown,
-  offset: unknown,
-  limit: unknown,
-): Promise<Result> {
-  const address = str(path);
-  if (!address) return { ok: false, text: "A file path is required." };
-  const active = await getTeleport(chatId);
-  const where = active ? active.deviceName : "local";
-
-  const p = resolvePathParam(address, active?.deviceName);
-  const shown = p === address ? p : `${address} → ${p}`;
-
-  // Image files: return a viewable image block, not the raw bytes decoded as
-  // UTF-8. Without this, `read`ing a photo/screenshot/design hands the model
-  // mojibake and it can't see the picture at all.
-  const mime = IMAGE_MIME[extname(p).toLowerCase()];
-  if (mime) {
-    let bytes: Buffer;
-    if (active) {
-      const res = await getMeshService().readFileBytes(active.deviceId, p);
-      if ("error" in res) return { ok: false, text: res.error };
-      bytes = res.data;
-    } else {
-      try {
-        // stat first — no point slurping a 40MB photo just to refuse it.
-        const st = await fsStat(p);
-        if (st.size > MAX_IMAGE_BYTES)
-          return oversizeImageResult(shown, where, st.size, p);
-        bytes = await readFile(p);
-      } catch (err) {
-        return {
-          ok: false,
-          text: `Cannot read ${shown}: ${(err as Error).message}`,
-        };
-      }
-    }
-    if (bytes.length > MAX_IMAGE_BYTES) {
-      return oversizeImageResult(shown, where, bytes.length, p);
-    }
-    return {
-      ok: true,
-      text: `${shown} [${where}] — image (${mime}, ${bytes.length} bytes)`,
-      image: { data: bytes.toString("base64"), mimeType: mime },
-    };
-  }
-
-  // Clamp: a negative offset would silently flip slice() into
-  // count-from-the-end (with line numbers that lie), and a zero/negative
-  // limit would return an empty read that looks like an empty file.
-  const start = Math.max(0, Math.trunc(num(offset) ?? 0));
-  const max = Math.min(
-    Math.max(1, Math.trunc(num(limit) ?? MAX_READ_LINES)),
-    MAX_READ_LINES,
-  );
-  let content: string;
-  if (active) {
-    const res = await getMeshService().readFileBytes(active.deviceId, p);
-    if ("error" in res) return { ok: false, text: res.error };
-    if (res.data.length > MAX_READ_FILE_BYTES)
-      return oversizeReadResult(shown, where, res.data.length, p);
-    content = res.data.toString("utf8");
-  } else {
-    try {
-      const st = await fsStat(p);
-      if (st.isFile() && st.size > MAX_READ_FILE_BYTES)
-        return oversizeReadResult(shown, where, st.size, p);
-      content = await readFile(p, "utf8");
-    } catch (err) {
-      return {
-        ok: false,
-        text: `Cannot read ${shown}: ${(err as Error).message}`,
-      };
-    }
-  }
-  // Binary files decoded as UTF-8 are mojibake the model can't use — same
-  // rationale as the image branch, but with no viewable representation to
-  // return. Point at the shell tools that can actually inspect the bytes.
-  if (content.includes("\0")) {
-    return {
-      ok: false,
-      text:
-        `${shown} [${where}] looks binary — refusing to render it as text. ` +
-        `Inspect it with bash instead: \`file '${p}'\`, \`xxd '${p}' | head\`, \`strings '${p}'\`.`,
-    };
-  }
-  const lines = content.split("\n");
-  if (start >= lines.length) {
-    return {
-      ok: false,
-      text: `${shown} [${where}] has ${lines.length} lines — offset ${start} is past the end.`,
-    };
-  }
-  const slice = lines.slice(start, start + max);
-  const numbered = slice
-    .map((line, i) => `${String(start + i + 1).padStart(6)}\t${line}`)
-    .join("\n");
-  const more =
-    lines.length > start + max
-      ? `\n… (${lines.length - start - max} more lines; raise limit/offset)`
-      : "";
-  return {
-    ok: true,
-    text: `${shown} [${where}] — ${lines.length} lines\n${numbered}${more}`,
-  };
-}
-
-async function write(
-  chatId: number,
-  path: unknown,
-  content: unknown,
-): Promise<Result> {
-  const address = str(path);
-  if (!address) return { ok: false, text: "A file path is required." };
-  const body = typeof content === "string" ? content : "";
-  const active = await getTeleport(chatId);
-  const p = resolvePathParam(address, active?.deviceName);
-  const shown = p === address ? p : `${address} → ${p}`;
-  if (active) {
-    return getMeshService().writeFileToDevice(active.deviceId, p, body);
-  }
-  try {
-    await mkdir(dirname(p), { recursive: true });
-    await writeFile(p, body);
-  } catch (err) {
-    return {
-      ok: false,
-      text: `Cannot write ${shown}: ${(err as Error).message}`,
-    };
-  }
-  return {
-    ok: true,
-    text: `Wrote ${Buffer.byteLength(body, "utf8")} bytes to ${shown} [local].`,
-  };
-}
-
-async function edit(
-  chatId: number,
-  path: unknown,
-  oldString: unknown,
-  newString: unknown,
-  replaceAll: unknown,
-): Promise<Result> {
-  const address = str(path);
-  if (!address) return { ok: false, text: "A file path is required." };
-  const from = typeof oldString === "string" ? oldString : "";
-  const to = typeof newString === "string" ? newString : "";
-  if (from === to)
-    return { ok: false, text: "old_string and new_string are identical." };
-  const active = await getTeleport(chatId);
-  const p = resolvePathParam(address, active?.deviceName);
-  const shown = p === address ? p : `${address} → ${p}`;
-  const svc = getMeshService();
-
-  let content: string;
-  if (active) {
-    const res = await svc.readFileBytes(active.deviceId, p);
-    if ("error" in res) return { ok: false, text: res.error };
-    content = res.data.toString("utf8");
-  } else {
-    try {
-      content = await readFile(p, "utf8");
-    } catch (err) {
-      return {
-        ok: false,
-        text: `Cannot read ${shown}: ${(err as Error).message}`,
-      };
-    }
-  }
-
-  // Binary guard: decoding binary as UTF-8 is lossy (invalid sequences
-  // become U+FFFD), so a read→replace→write round-trip would corrupt every
-  // non-text byte — even when old_string matches a clean region.
-  if (content.includes("\0")) {
-    return {
-      ok: false,
-      text: `${shown} looks binary — refusing a text edit that would corrupt it. Use bash for byte-level changes.`,
-    };
-  }
-
-  const count = from ? content.split(from).length - 1 : 0;
-  if (count === 0) {
-    return {
-      ok: false,
-      text: `old_string not found in ${shown}.${nearMissHint(content, from)}`,
-    };
-  }
-  if (count > 1 && replaceAll !== true) {
-    return {
-      ok: false,
-      text: `old_string appears ${count}× in ${shown}; pass replace_all or make it unique.`,
-    };
-  }
-  // Splice, not String.replace: replace() treats dollar-sign substitution
-  // patterns ($&, $', $BACKTICK, $$) in the replacement as directives, silently
-  // corrupting any new_string that contains them (shell snippets, regexes,
-  // Makefiles...). split/join and index-splice are both literal.
-  const updated =
-    replaceAll === true
-      ? content.split(from).join(to)
-      : spliceOnce(content, from, to);
-  const firstLine = content.slice(0, content.indexOf(from)).split("\n").length;
-
-  if (active) {
-    const res = await svc.writeFileToDevice(active.deviceId, p, updated);
-    return res.ok
-      ? {
-          ok: true,
-          text: `Edited ${shown} [${active.deviceName}] (${count} replacement${count === 1 ? "" : "s"}, first at line ${firstLine}).`,
-        }
-      : res;
-  }
-  try {
-    await writeFile(p, updated);
-  } catch (err) {
-    return {
-      ok: false,
-      text: `Cannot write ${shown}: ${(err as Error).message}`,
-    };
-  }
-  return {
-    ok: true,
-    text: `Edited ${shown} [local] (${count} replacement${count === 1 ? "" : "s"}, first at line ${firstLine}).`,
-  };
-}
-
-// ── glob / search ───────────────────────────────────────────────────────────
-
-async function glob(
-  chatId: number,
-  pattern: unknown,
-  path: unknown,
-): Promise<Result> {
-  const pat = str(pattern);
-  if (!pat) return { ok: false, text: "A glob pattern is required." };
-  const active = await getTeleport(chatId);
-  const root = resolvePathParam(str(path) ?? ".", active?.deviceName);
-  if (active) {
-    // Prefer rg on the device; fall back to find (basename patterns via
-    // -name, path patterns via -path). `command -v` gates the choice so a
-    // no-match rg exit (1) isn't misread as "rg missing, run find too".
-    const findExpr = pat.includes("/")
-      ? `-type f -path ${shellQuote(`*${pat}`)}`
-      : `-type f -name ${shellQuote(pat)}`;
-    const cmd =
-      `if command -v rg >/dev/null 2>&1; ` +
-      `then rg --files -g ${shellQuote(pat)} ${shellQuote(root)}; ` +
-      `else find ${shellQuote(root)} ${findExpr} 2>/dev/null; fi`;
-    return bashTeleported(chatId, active.deviceId, cmd, 30_000);
-  }
-  const res = await runLocal(rgBin(), ["--files", "-g", pat, root]);
-  let files: string[];
-  if (res.code === 127) {
-    // rg not installed — pure-JS fallback rather than lying "no matches".
-    files = await globJs(pat, root);
-  } else if (res.code > 1 && !res.stdout.trim()) {
-    // exit 2 with output = partial results (e.g. permission-denied subdirs);
-    // exit 2 with none = a real error worth surfacing.
-    return {
-      ok: false,
-      text: `glob failed: ${res.stderr.trim() || `ripgrep exit ${res.code}`}`,
-    };
-  } else {
-    files = res.stdout.trim().split("\n").filter(Boolean);
-  }
-  // rg's parallel directory walk (and the JS fallback's) emit in
-  // nondeterministic order — sort so identical calls render identically.
-  files.sort();
-  return {
-    ok: true,
-    text: files.length
-      ? `${files.length} match(es):\n${files.slice(0, 200).join("\n")}${files.length > 200 ? `\n… (${files.length - 200} more)` : ""}`
-      : `No files match ${pat} under ${root}.`,
-  };
-}
-
-async function search(
-  chatId: number,
-  pattern: unknown,
-  path: unknown,
-  globPat: unknown,
-  caseInsensitive: unknown,
-): Promise<Result> {
-  const pat = str(pattern);
-  if (!pat) return { ok: false, text: "A search pattern is required." };
-  const active = await getTeleport(chatId);
-  const root = resolvePathParam(str(path) ?? ".", active?.deviceName);
-  const g = str(globPat);
-  const ci = caseInsensitive === true;
-  // `-e` keeps a pattern that starts with "-" from being parsed as a flag
-  // (same idiom for rg and grep).
-  const flags = [
-    "-n",
-    "--color=never",
-    ...(ci ? ["-i"] : []),
-    ...(g ? ["-g", g] : []),
-  ];
-  if (active) {
-    // Prefer rg on the device, fall back to grep (Android toybox has grep
-    // but rarely rg). --include is grep's closest analogue of -g.
-    const grepFlags = [
-      "-rn",
-      ...(ci ? ["-i"] : []),
-      ...(g ? [`--include=${g}`] : []),
-    ];
-    const cmd =
-      `if command -v rg >/dev/null 2>&1; ` +
-      `then rg ${flags.map(shellQuote).join(" ")} -e ${shellQuote(pat)} ${shellQuote(root)}; ` +
-      `else grep ${grepFlags.map(shellQuote).join(" ")} -e ${shellQuote(pat)} ${shellQuote(root)} 2>/dev/null; fi`;
-    return bashTeleported(chatId, active.deviceId, cmd, 30_000);
-  }
-  const res = await runLocal(rgBin(), [...flags, "-e", pat, root]);
-  let lines: string[];
-  if (res.code === 127) {
-    // rg not installed — pure-JS fallback rather than lying "no matches".
-    try {
-      lines = await searchJs(pat, root, g, ci);
-    } catch (err) {
-      return { ok: false, text: `search failed: ${(err as Error).message}` };
-    }
-  } else if (res.code > 1 && !res.stdout.trim()) {
-    // exit 2 with output = partial results; exit 2 with none = real error.
-    return {
-      ok: false,
-      text: `search failed: ${res.stderr.trim() || `ripgrep exit ${res.code}`}`,
-    };
-  } else {
-    const out = res.stdout.trim();
-    lines = out ? out.split("\n") : [];
-  }
-  return {
-    ok: true,
-    text: lines.length
-      ? `${lines.length} match line(s):\n${lines.slice(0, 200).join("\n")}${lines.length > 200 ? `\n… (${lines.length - 200} more)` : ""}`
-      : `No matches for ${pat} under ${root}.`,
-  };
-}
-
-// ── pure-JS glob/search fallbacks (no ripgrep on the host) ──────────────────
-
-/**
- * Glob without ripgrep, via node:fs `glob`. Mirrors rg's -g semantics for
- * bare names (a pattern without "/" matches at any depth) and skips
- * node_modules/.git, which rg would exclude via gitignore.
- */
-async function globJs(pat: string, root: string): Promise<string[]> {
-  const pattern = pat.includes("/") ? pat : `**/${pat}`;
-  const out: string[] = [];
-  try {
-    for await (const entry of fsGlob(pattern, {
-      cwd: root,
-      exclude: (e: unknown) => {
-        const name =
-          typeof e === "string" ? e : ((e as { name?: string }).name ?? "");
-        return (
-          SKIP_DIRS_RE.test(name) || name === "node_modules" || name === ".git"
-        );
-      },
-    })) {
-      out.push(join(root, String(entry)));
-      if (out.length >= MAX_JS_RESULTS) break;
-    }
-  } catch {
-    // unreadable root etc. — empty result, caller reports "no matches"
-  }
-  return out;
-}
-
-/** Content search without ripgrep: walk text files and regex-match lines. */
-async function searchJs(
-  pat: string,
-  root: string,
-  globPat: string | undefined,
-  caseInsensitive: boolean,
-): Promise<string[]> {
-  const re = new RegExp(pat, caseInsensitive ? "i" : "");
-  let files: string[];
-  try {
-    const st = await fsStat(root);
-    files = st.isFile() ? [root] : await globJs(globPat ?? "**/*", root);
-  } catch {
-    return [];
-  }
-  const lines: string[] = [];
-  for (const f of files) {
-    let content: string;
-    try {
-      const st = await fsStat(f);
-      if (!st.isFile() || st.size > MAX_JS_FILE_BYTES) continue;
-      content = await readFile(f, "utf8");
-    } catch {
-      continue;
-    }
-    if (content.includes("\0")) continue; // binary
-    const fileLines = content.split("\n");
-    for (let i = 0; i < fileLines.length; i++) {
-      if (re.test(fileLines[i])) lines.push(`${f}:${i + 1}:${fileLines[i]}`);
-      if (lines.length >= MAX_JS_RESULTS) return lines;
-    }
-  }
-  return lines;
-}
-
-function oversizeReadResult(
-  shown: string,
-  where: string,
-  size: number,
-  p: string,
-): Result {
-  return {
-    ok: false,
-    text:
-      `${shown} [${where}] is ${(size / 1_048_576).toFixed(1)}MB — over the ` +
-      `${MAX_READ_FILE_BYTES / 1_048_576}MB read limit. Slice it with bash instead: ` +
-      `\`sed -n '1,200p' '${p}'\`, \`tail -n 200 '${p}'\`, or \`grep\` for what you need.`,
-  };
-}
-
-function oversizeImageResult(
-  shown: string,
-  where: string,
-  size: number,
-  p: string,
-): Result {
-  return {
-    ok: false,
-    text:
-      `${shown} [${where}] is ${(size / 1_048_576).toFixed(1)}MB — over the ` +
-      `${MAX_IMAGE_BYTES / 1_048_576}MB image limit. Downscale it first ` +
-      `(e.g. \`convert '${p}' -resize 1568x /tmp/small.jpg\`) and read that.`,
-  };
-}
-
-/**
- * When an edit's old_string doesn't match verbatim, the cause is almost
- * always invisible: indentation, tabs vs spaces, or a trailing space. Point
- * at the closest-looking line so the model re-reads that region instead of
- * blindly retrying the same string.
- */
-function nearMissHint(content: string, from: string): string {
-  const probe =
-    from
-      .split("\n")
-      .map((l) => l.trim())
-      .find((l) => l.length >= 8) ?? from.trim();
-  if (!probe) return "";
-  const lines = content.split("\n");
-  const idx = lines.findIndex((l) => l.trim().includes(probe));
-  if (idx === -1) return "";
-  return (
-    `\nLine ${idx + 1} looks close — whitespace/indentation must match the file byte-for-byte. ` +
-    `Re-read that region before retrying:\n${String(idx + 1).padStart(6)}\t${lines[idx]}`
-  );
-}
-
-/** Replace the first occurrence of `from` with `to`, both taken literally. */
-function spliceOnce(content: string, from: string, to: string): string {
-  const idx = content.indexOf(from);
-  if (idx === -1) return content;
-  return content.slice(0, idx) + to + content.slice(idx + from.length);
-}
-
-// ── helpers ─────────────────────────────────────────────────────────────────
-
-function runLocal(
-  bin: string,
-  args: string[],
-): Promise<{ code: number; stdout: string; stderr: string }> {
-  return new Promise((resolvePromise) => {
-    const child = spawn(bin, args, { env: process.env });
-    const stdout = createOutputCapture();
-    const stderr = createOutputCapture();
-    child.stdout.on("data", stdout.push);
-    child.stderr.on("data", stderr.push);
-    child.on("error", () =>
-      resolvePromise({
-        code: 127,
-        stdout: stdout.value(),
-        stderr: stderr.value(),
-      }),
-    );
-    child.on("close", (code) =>
-      resolvePromise({
-        code: code ?? 0,
-        stdout: stdout.value(),
-        stderr: stderr.value(),
-      }),
-    );
-  });
-}
-
-function renderExec(
-  where: string,
-  status: string,
-  stdout: string,
-  stderr: string,
-): string {
-  const parts = [`[${where}] ${status}`];
-  if (stdout.trim())
-    parts.push(
-      `--- stdout ---\n${clampExecOutput(stdout.replace(/\s+$/, ""))}`,
-    );
-  if (stderr.trim())
-    parts.push(
-      `--- stderr ---\n${clampExecOutput(stderr.replace(/\s+$/, ""))}`,
-    );
-  if (!stdout.trim() && !stderr.trim()) parts.push("(no output)");
-  return parts.join("\n");
-}
-
-function clampTimeout(value: unknown): number {
-  const sec = typeof value === "number" ? value : Number(value);
-  if (!Number.isFinite(sec) || sec <= 0) return DEFAULT_EXEC_TIMEOUT_MS;
-  return Math.min(
-    MAX_EXEC_TIMEOUT_MS,
-    Math.max(1_000, Math.round(sec * 1_000)),
-  );
-}
-
-function shellQuote(s: string): string {
-  return `'${s.replace(/'/g, `'\\''`)}'`;
-}
-
-function str(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}
-
-function num(value: unknown): number | undefined {
-  const n = typeof value === "number" ? value : Number(value);
-  return Number.isFinite(n) ? n : undefined;
-}