talon-agent 5.0.0 → 5.1.0

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

@@ -0,0 +1,85 @@
+/**
+ * `native_bash` on a teleported device — dispatched over the mesh exec
+ * channel.
+ *
+ * The command is wrapped so the shell's resulting working directory comes
+ * back in markers and persists across calls (a `cd` carries forward) without
+ * disturbing the real exit code. glob/search reuse this path for their
+ * on-device rg/find/grep fallbacks.
+ */
+
+import { getMeshService } from "../../../mesh/index.js";
+import { getTeleport, setTeleportCwd } from "../../../mesh/teleport.js";
+import { renderExec, type Result } from "./results.js";
+import { shellQuote } from "./shell.js";
+
+/** 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`.)";
+/** 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 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,
+  };
+}

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

@@ -0,0 +1,182 @@
+/**
+ * `native_bash` — the entry point and the local foreground run.
+ *
+ * The handler picks one of three paths: a detached background launch
+ * (exec-background.ts), a teleported on-device run (exec-remote.ts), or the
+ * local spawn below, which owns the timeout escalation (SIGTERM the process
+ * group, SIGKILL the survivors) so a runaway pipeline can still flush what
+ * it produced.
+ */
+
+import { spawn } from "node:child_process";
+import { stat as fsStat } from "node:fs/promises";
+import { getTeleport } from "../../../mesh/teleport.js";
+import { createOutputCapture } from "../../../../util/exec-output.js";
+import { bashBackground } from "./exec-background.js";
+import { bashTeleported } from "./exec-remote.js";
+import { resolvePathParam } from "./params.js";
+import { renderExec, type Result } from "./results.js";
+import type { SharedActionHandlers } from "../types.js";
+
+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;
+/** 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`.)";
+
+export const execHandlers: SharedActionHandlers = {
+  native_bash: (body, chatId) =>
+    bash(chatId, body.command, body.cwd, body.timeout_sec, body.background),
+};
+
+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;
+}
+
+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(),
+        ),
+      });
+    });
+  });
+}
+
+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)),
+  );
+}

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

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ *
+ * One module per concern; this file is only the registry:
+ *
+ *   - `teleport`        — teleport / teleport_back
+ *   - `exec`            — native_bash (dispatch + local foreground run)
+ *   - `exec-background` — the detached background launch
+ *   - `exec-remote`     — the on-device run over the mesh exec channel
+ *   - `read`            — native_read
+ *   - `write`           — native_write / native_edit
+ *   - `search`          — native_glob / native_search
+ *
+ * The spread order below reproduces the key order of the single object
+ * literal these came from. Action names are the model's tool vocabulary and
+ * sit in the prompt-cache prefix via the tool descriptions, so neither the
+ * names nor their order may change (pinned by native-tools.test.ts).
+ */
+
+import { teleportHandlers } from "./teleport.js";
+import { execHandlers } from "./exec.js";
+import { readHandlers } from "./read.js";
+import { writeHandlers } from "./write.js";
+import { searchHandlers } from "./search.js";
+import type { SharedActionHandlers } from "../types.js";
+
+export const nativeHandlers: SharedActionHandlers = {
+  ...teleportHandlers,
+  ...execHandlers,
+  ...readHandlers,
+  ...writeHandlers,
+  ...searchHandlers,
+};

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

@@ -0,0 +1,46 @@
+/**
+ * Tool-argument resolution: the one rule for every path parameter, plus the
+ * string/number coercions that turn an untyped request body field into
+ * something the handlers can use.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// — 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.
+ */
+export function resolvePathParam(
+  path: string,
+  teleportedTo: string | undefined,
+): string {
+  return teleportedTo !== undefined ? path : expandHome(path);
+}
+
+// — scalar coercion --------------------------------------------------------
+
+export function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export function num(value: unknown): number | undefined {
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? n : undefined;
+}

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

@@ -0,0 +1,182 @@
+/**
+ * `native_read` — read a file from the daemon host or, when teleported, from
+ * the device.
+ *
+ * Two things it refuses rather than fakes: a file too big to slurp into
+ * memory (bash can slice it) and binary content decoded as UTF-8. Images are
+ * the exception — they come back as a viewable image block instead of bytes.
+ */
+
+import { readFile, stat as fsStat } from "node:fs/promises";
+import { extname } from "node:path";
+import { getMeshService } from "../../../mesh/index.js";
+import { getTeleport } from "../../../mesh/teleport.js";
+import { num, resolvePathParam, str } from "./params.js";
+import type { Result } from "./results.js";
+import type { SharedActionHandlers } from "../types.js";
+
+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;
+
+export const readHandlers: SharedActionHandlers = {
+  native_read: (body, chatId) =>
+    read(chatId, body.path, body.offset, body.limit),
+};
+
+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}`,
+  };
+}
+
+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.`,
+  };
+}

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

@@ -0,0 +1,34 @@
+/**
+ * What a native tool hands back: the `Result` shape every handler in this
+ * directory returns, and the renderer that turns an exec run (local or
+ * teleported) into the `[where] status / stdout / stderr` block the model
+ * reads.
+ */
+
+import { clampExecOutput } from "../../../../util/exec-output.js";
+
+export type Result = {
+  ok: boolean;
+  text: string;
+  /** Set for image files so the tool result carries a viewable image block. */
+  image?: { data: string; mimeType: string };
+};
+
+export 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");
+}