talon-agent 1.35.0 → 1.37.0

package/src/core/mesh/teleport.ts

@@ -0,0 +1,158 @@
+/**
+ * Teleport state — the active node each chat's native tools route through.
+ *
+ * When a node is active, Talon's native shell/file tools (bash/read/write/
+ * edit/glob/search) execute ON that companion device via the mesh exec/fs
+ * channel instead of on the daemon host — Talon acts as if it were running
+ * on the phone. `teleport_back` clears it and everything runs locally again.
+ *
+ * State is a tiny JSON sidecar under the Talon root so it survives restarts.
+ * The sidecar is keyed by chat id: teleporting in one chat must not redirect
+ * native tools in another chat.
+ */
+
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { dirs } from "../../util/paths.js";
+import { writePrivateJson } from "./persist.js";
+
+export type TeleportState = {
+  /** Target device id (as registered in the mesh). */
+  deviceId: string;
+  /** Human name for messages. */
+  deviceName: string;
+  /**
+   * Working directory tracked across native `bash` calls so a teleported
+   * session feels persistent (a `cd` in one command carries to the next).
+   * Undefined until the first command resolves it.
+   */
+  cwd?: string;
+  /** When the teleport was engaged (epoch ms). */
+  since: number;
+};
+
+type TeleportStore = {
+  chats: Record<string, TeleportState>;
+};
+
+/** Resolved lazily so a test can point it at a tmp file via env. */
+function stateFile(): string {
+  return (
+    process.env.TALON_TELEPORT_STATE_FILE ??
+    resolve(dirs.root, "teleport-state.json")
+  );
+}
+
+let cache: TeleportStore | undefined;
+
+function emptyStore(): TeleportStore {
+  return { chats: Object.create(null) as Record<string, TeleportState> };
+}
+
+function normalizeChatId(chatId: number | string): string {
+  return String(chatId);
+}
+
+function parseState(value: unknown): TeleportState | null {
+  const parsed = value as Partial<TeleportState> | null;
+  if (!parsed || typeof parsed.deviceId !== "string" || !parsed.deviceId) {
+    return null;
+  }
+  return {
+    deviceId: parsed.deviceId,
+    deviceName:
+      typeof parsed.deviceName === "string" && parsed.deviceName
+        ? parsed.deviceName
+        : parsed.deviceId,
+    ...(typeof parsed.cwd === "string" ? { cwd: parsed.cwd } : {}),
+    since: typeof parsed.since === "number" ? parsed.since : Date.now(),
+  };
+}
+
+async function readStore(): Promise<TeleportStore> {
+  if (cache !== undefined) return cache;
+  try {
+    const raw = await readFile(stateFile(), "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    const store = emptyStore();
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      "chats" in parsed &&
+      parsed.chats &&
+      typeof parsed.chats === "object"
+    ) {
+      for (const [chatId, state] of Object.entries(
+        parsed.chats as Record<string, unknown>,
+      )) {
+        const normalized = parseState(state);
+        if (normalized) store.chats[chatId] = normalized;
+      }
+    } else {
+      // Legacy singleton file from pre-chat-scoped teleport. Keep reading it
+      // harmlessly, but do not bind it to any chat.
+    }
+    cache = store;
+  } catch {
+    cache = emptyStore();
+  }
+  return cache;
+}
+
+/** The active teleport target, or null when operating locally. */
+export async function getTeleport(
+  chatId: number | string,
+): Promise<TeleportState | null> {
+  const store = await readStore();
+  return store.chats[normalizeChatId(chatId)] ?? null;
+}
+
+/** Engage teleport onto a device. */
+export async function setTeleport(
+  chatId: number | string,
+  deviceId: string,
+  deviceName: string,
+): Promise<TeleportState> {
+  const state: TeleportState = {
+    deviceId,
+    deviceName,
+    since: Date.now(),
+  };
+  const store = await readStore();
+  store.chats[normalizeChatId(chatId)] = state;
+  cache = store;
+  await writePrivateJson(stateFile(), store);
+  return state;
+}
+
+/** Persist an updated working directory for the active teleport. */
+export async function setTeleportCwd(
+  chatId: number | string,
+  cwd: string,
+): Promise<void> {
+  const current = await getTeleport(chatId);
+  if (!current) return;
+  const next: TeleportState = { ...current, cwd };
+  const store = await readStore();
+  store.chats[normalizeChatId(chatId)] = next;
+  cache = store;
+  await writePrivateJson(stateFile(), store);
+}
+
+/** Return to local operation. Returns the prior target (for the message). */
+export async function clearTeleport(
+  chatId: number | string,
+): Promise<TeleportState | null> {
+  const store = await readStore();
+  const key = normalizeChatId(chatId);
+  const prior = store.chats[key] ?? null;
+  delete store.chats[key];
+  cache = store;
+  await writePrivateJson(stateFile(), store);
+  return prior;
+}
+
+/** Test seam — drop the in-memory cache so the next read hits disk. */
+export function resetTeleportCache(): void {
+  cache = undefined;
+}

package/src/core/mesh/transfers.ts

@@ -0,0 +1,186 @@
+/**
+ * TransferStore — one-time tokens for streaming device file transfers.
+ *
+ * The chunked command channel moves file bytes at 256KB–1MB per full mesh
+ * round trip (SSE command out, HTTP result back) — fine for small text,
+ * hopeless for real files. The streaming path costs ONE command round trip
+ * to arrange the transfer, then the file body flows as a single raw HTTP
+ * stream between the companion and the bridge at full TCP throughput:
+ *
+ *   pull (device → daemon):
+ *     daemon: token = createPull(deviceId, destPath)
+ *     daemon → device (command): upload_file { token, path }
+ *     device → daemon (HTTP):    POST /devices/file?transfer=token  (raw body)
+ *     bridge route:              acceptUpload(token, stream) → tmp+rename
+ *     device → daemon (command result): ok + bytes — the command round trip
+ *     doubles as the completion signal.
+ *
+ *   push (daemon → device):
+ *     daemon: token = createPush(deviceId, sourcePath)
+ *     daemon → device (command): download_file { token, path }
+ *     device → daemon (HTTP):    GET /devices/file?transfer=token
+ *     bridge route:              openDownload(token) → stream the source
+ *     device writes to its path, answers the command with ok + bytes.
+ *
+ * Tokens are single-use, bound to one device + one path, and expire unused.
+ * The registry never trusts the HTTP caller with a path — the token IS the
+ * authorization, and it only reaches the device over the authed mesh
+ * channel (the HTTP routes additionally sit behind the bridge bearer token).
+ */
+
+import { randomBytes } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { mkdir, rename, rm, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { pipeline } from "node:stream/promises";
+import type { Readable } from "node:stream";
+
+/** Unused tokens die after this long (transfer not started). */
+const TOKEN_TTL_MS = 10 * 60 * 1000;
+
+type Transfer = {
+  token: string;
+  direction: "pull" | "push";
+  deviceId: string;
+  /** pull: destination on the daemon host; push: source on the daemon host. */
+  localPath: string;
+  createdAt: number;
+  /** Set once the HTTP leg has started (single-use latch). */
+  consumed: boolean;
+  /** pull only — resolved by acceptUpload with the byte count. */
+  uploadDone?: {
+    promise: Promise<number>;
+    resolve: (bytes: number) => void;
+    reject: (err: Error) => void;
+  };
+};
+
+export class TransferStore {
+  private readonly transfers = new Map<string, Transfer>();
+
+  /** Arrange a device→daemon transfer. Returns the token to send to the
+   *  device and a promise that resolves (bytes) when the upload lands. */
+  createPull(
+    deviceId: string,
+    destPath: string,
+  ): { token: string; done: Promise<number> } {
+    this.sweep();
+    const token = randomBytes(24).toString("base64url");
+    let resolve!: (bytes: number) => void;
+    let reject!: (err: Error) => void;
+    const promise = new Promise<number>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    // A pull whose upload never arrives must not leave an eternally-pending
+    // promise; callers race it with the command result, which times out.
+    promise.catch(() => {});
+    this.transfers.set(token, {
+      token,
+      direction: "pull",
+      deviceId,
+      localPath: destPath,
+      createdAt: Date.now(),
+      consumed: false,
+      uploadDone: { promise, resolve, reject },
+    });
+    return { token, done: promise };
+  }
+
+  /** Arrange a daemon→device transfer of `sourcePath`. */
+  createPush(deviceId: string, sourcePath: string): { token: string } {
+    this.sweep();
+    const token = randomBytes(24).toString("base64url");
+    this.transfers.set(token, {
+      token,
+      direction: "push",
+      deviceId,
+      localPath: sourcePath,
+      createdAt: Date.now(),
+      consumed: false,
+    });
+    return { token };
+  }
+
+  /** Drop a token (transfer arrangement failed before the HTTP leg). */
+  cancel(token: string): void {
+    const t = this.transfers.get(token);
+    if (t?.uploadDone && !t.consumed) {
+      t.uploadDone.reject(new Error("transfer cancelled"));
+    }
+    this.transfers.delete(token);
+  }
+
+  /**
+   * Bridge route: a device is streaming a pull's file body up. Writes to a
+   * temp file and renames into place, so a dropped connection can't leave a
+   * half-written destination. Resolves the pull's `done` promise.
+   */
+  async acceptUpload(
+    token: string,
+    body: Readable,
+  ): Promise<{ ok: true; bytes: number } | { ok: false; error: string }> {
+    const t = this.take(token, "pull");
+    if (!t)
+      return { ok: false, error: "Unknown or already-used transfer token." };
+    const tmp = `${t.localPath}.part-${randomBytes(4).toString("hex")}`;
+    try {
+      await mkdir(dirname(t.localPath), { recursive: true });
+      let bytes = 0;
+      body.on("data", (d: Buffer) => (bytes += d.length));
+      await pipeline(body, createWriteStream(tmp, { mode: 0o600 }));
+      await rename(tmp, t.localPath);
+      this.transfers.delete(token);
+      t.uploadDone?.resolve(bytes);
+      return { ok: true, bytes };
+    } catch (err) {
+      await rm(tmp, { force: true }).catch(() => {});
+      this.transfers.delete(token);
+      const error = `Upload for ${t.localPath} failed mid-stream: ${(err as Error).message}`;
+      t.uploadDone?.reject(new Error(error));
+      return { ok: false, error };
+    }
+  }
+
+  /**
+   * Bridge route: a device wants a push's file body. Returns the source
+   * path to stream (single use) or null for unknown/used tokens.
+   */
+  async openDownload(
+    token: string,
+  ): Promise<{ path: string; size: number } | null> {
+    const t = this.take(token, "push");
+    if (!t) return null;
+    try {
+      const s = await stat(t.localPath);
+      if (!s.isFile()) throw new Error("not a file");
+      return { path: t.localPath, size: s.size };
+    } catch {
+      this.transfers.delete(token);
+      return null;
+    } finally {
+      // Single-use either way; the device retries by re-arranging.
+      this.transfers.delete(token);
+    }
+  }
+
+  /** Validate + latch a token for its HTTP leg. */
+  private take(token: string, direction: Transfer["direction"]) {
+    this.sweep();
+    const t = this.transfers.get(token);
+    if (!t || t.direction !== direction || t.consumed) return null;
+    if (Date.now() - t.createdAt > TOKEN_TTL_MS) {
+      this.cancel(token);
+      return null;
+    }
+    t.consumed = true;
+    return t;
+  }
+
+  private sweep(): void {
+    const now = Date.now();
+    for (const [token, t] of this.transfers) {
+      if (!t.consumed && now - t.createdAt > TOKEN_TTL_MS) this.cancel(token);
+    }
+  }
+}

package/src/core/tools/bridge.ts

@@ -5,8 +5,51 @@
  * exactly one copy of callBridge / textResult.
  */
 
+import { Agent, fetch as undiciFetch } from "undici";
 import type { BridgeFunction } from "./types.js";
 
+/** Default wall-clock budget for a bridge action. */
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+/**
+ * Actions that can legitimately outlive the default budget. Device file
+ * transfers are chunked with no size cap, so they get a very generous
+ * ceiling; exec-style actions are bounded by their own 300s command cap
+ * (+ margin). Native read/write/edit route to a device when a teleport is
+ * engaged, so they inherit transfer-grade budgets too.
+ */
+const LONG_ACTION_TIMEOUTS_MS: Record<string, number> = {
+  device_pull_file: 3_600_000,
+  device_push_file: 3_600_000,
+  device_read_file: 3_600_000,
+  device_write_file: 3_600_000,
+  native_read: 3_600_000,
+  native_write: 3_600_000,
+  native_edit: 3_600_000,
+  device_exec: 330_000,
+  native_bash: 330_000,
+  native_glob: 330_000,
+  native_search: 330_000,
+};
+
+/**
+ * Long-haul actions (>300s budgets) can't ride Node's built-in fetch: its
+ * default dispatcher fails any request whose response headers take >300s,
+ * which would kill a long transfer regardless of our AbortSignal — and the
+ * built-in fetch brand-checks `dispatcher`, rejecting an Agent from the npm
+ * undici package ("fetch failed"). So long-haul calls use the npm undici's
+ * OWN fetch with its own Agent (watchdogs off); the deadline is then
+ * governed solely by the per-action AbortSignal. Everything else keeps the
+ * plain global fetch (fast path, easily stubbed in tests).
+ */
+let longHaulAgent: Agent | undefined;
+function dispatcher(): Agent {
+  longHaulAgent ??= new Agent({ headersTimeout: 0, bodyTimeout: 0 });
+  return longHaulAgent;
+}
+/** Built-in fetch's default dispatcher fails headers slower than this. */
+const BUILTIN_FETCH_HEADERS_CEILING_MS = 300_000;
+
 /**
  * Create a bridge caller bound to a default URL and chat.
  *
@@ -18,6 +61,11 @@ import type { BridgeFunction } from "./types.js";
  * gateway routes to it, AND keeps `chat_id` in the body as a signal
  * that this is an explicit-routing request (the gateway uses that signal
  * to skip the active-context-required check it normally enforces).
+ *
+ * Failure contract: every failure mode THROWS with a message that names
+ * the action and what went wrong. The MCP server layer converts a throw
+ * into an `isError` tool result, so the model always gets told — a tool
+ * call can time out, but it can never silently vanish.
  */
 export function createBridge(
   bridgeUrl: string,
@@ -30,14 +78,43 @@ export function createBridge(
         ? String((params as Record<string, unknown>).chat_id)
         : null;
     const effectiveChatId = explicitChatId ?? chatId;
-    const resp = await fetch(`${bridgeUrl}/action`, {
+    const timeoutMs = LONG_ACTION_TIMEOUTS_MS[action] ?? DEFAULT_TIMEOUT_MS;
+    const init = {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       // chat_id stays in body when set — gateway uses its presence as the
       // "explicit routing" signal. _chatId is the routing key either way.
       body: JSON.stringify({ action, ...params, _chatId: effectiveChatId }),
-      signal: AbortSignal.timeout(120_000),
-    });
+      signal: AbortSignal.timeout(timeoutMs),
+    };
+    // Minimal common surface of DOM Response and undici's Response.
+    let resp: {
+      ok: boolean;
+      status: number;
+      text(): Promise<string>;
+      json(): Promise<unknown>;
+    };
+    try {
+      resp =
+        timeoutMs > BUILTIN_FETCH_HEADERS_CEILING_MS
+          ? await undiciFetch(`${bridgeUrl}/action`, {
+              ...init,
+              dispatcher: dispatcher(),
+            })
+          : await fetch(`${bridgeUrl}/action`, init);
+    } catch (err) {
+      const cause = err as Error & { name?: string };
+      if (cause.name === "TimeoutError" || cause.name === "AbortError") {
+        throw new Error(
+          `"${action}" did not complete within ${Math.round(timeoutMs / 1000)}s. ` +
+            `The operation may still be running on the daemon — check its ` +
+            `outcome (e.g. list the target directory) before retrying.`,
+        );
+      }
+      throw new Error(
+        `"${action}" could not reach the Talon gateway: ${cause.message}`,
+      );
+    }
     if (!resp.ok) {
       const text = await resp.text();
       throw new Error(`Bridge error (${resp.status}): ${text}`);
@@ -49,11 +126,15 @@ export function createBridge(
 /** Wrap a bridge result into the MCP content format. */
 export function textResult(result: unknown): {
   content: Array<{ type: "text"; text: string }>;
+  isError?: boolean;
 } {
-  const r = result as { text?: string; error?: string };
+  const r = result as { ok?: boolean; text?: string; error?: string };
   return {
     content: [
       { type: "text" as const, text: r.text ?? JSON.stringify(result) },
     ],
+    // Gateway results carry ok:false on failure — mark those as tool errors
+    // so the model treats the message as a failure, not a success payload.
+    ...(r && typeof r === "object" && r.ok === false ? { isError: true } : {}),
   };
 }

package/src/core/tools/index.ts

@@ -22,6 +22,7 @@ import { webTools } from "./web.js";
 import { adminTools } from "./admin.js";
 import { modelTools } from "./models.js";
 import { meshTools } from "./mesh.js";
+import { nativeTools } from "./native.js";
 
 /** All built-in tool definitions. */
 export const ALL_TOOLS: readonly ToolDefinition[] = [
@@ -42,6 +43,15 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...meshTools,
 ];
 
+/**
+ * Native tools (bash/read/write/edit/glob/search + teleport) are kept OUT of
+ * ALL_TOOLS on purpose: they are an opt-in replacement for the SDK built-ins,
+ * surfaced only when `composeTools({ includeNativeTools: true })` is asked
+ * (driven by `config.nativeTools`). Keeping them separate preserves the
+ * "no options → the full built-in set" invariant every other caller relies on.
+ */
+export { nativeTools };
+
 /**
  * Names of tools that explicitly terminate the model's turn.
  *
@@ -75,7 +85,7 @@ const DELIVERY_TOOL_NAMES: ReadonlySet<string> = new Set(
  * Kilo's `<server>_<bare>` instead of MCP's canonical `mcp__<server>__<bare>`).
  */
 const ALL_TOOL_NAMES: ReadonlySet<string> = new Set(
-  ALL_TOOLS.map((t) => t.name),
+  [...ALL_TOOLS, ...nativeTools].map((t) => t.name),
 );
 
 /**
@@ -180,6 +190,13 @@ export interface ComposeOptions {
   excludeTags?: ToolTag[];
   /** Exclude specific tools by name. */
   excludeNames?: string[];
+  /**
+   * Include the `native` tool set (bash/read/write/edit/glob/search +
+   * teleport). Off unless explicitly requested — these are only meant to be
+   * live when `config.nativeTools` replaces the SDK built-ins, so every other
+   * caller (and tests) gets the built-in surface by default.
+   */
+  includeNativeTools?: boolean;
 }
 
 /**
@@ -189,7 +206,11 @@ export interface ComposeOptions {
  * Callers describe what they need and get back matching definitions.
  */
 export function composeTools(options: ComposeOptions = {}): ToolDefinition[] {
-  let tools = [...ALL_TOOLS];
+  // Native tools are opt-in — appended only when replacing the SDK built-ins,
+  // so every default caller (and tests) gets exactly the built-in set.
+  let tools = options.includeNativeTools
+    ? [...ALL_TOOLS, ...nativeTools]
+    : [...ALL_TOOLS];
 
   if (options.frontend) {
     tools = tools.filter(

package/src/core/tools/mesh.ts

@@ -12,7 +12,7 @@ const deviceParam = z
   .string()
   .optional()
   .describe(
-    "Device id or part of the device name (see list_devices). Defaults to the most recently seen mobile mesh device.",
+    "Device id, exact name, or unique name fragment (case/separator-insensitive; see list_devices). A fragment matching several devices errors unless exactly one is online — prefer the id when duplicates exist. Defaults to the most recently seen mobile mesh device.",
   );
 
 export const meshTools: ToolDefinition[] = [
@@ -68,4 +68,86 @@ export const meshTools: ToolDefinition[] = [
     execute: (params, bridge) => bridge("get_device_status", params),
     tag: "mesh",
   },
+  {
+    name: "device_exec",
+    description:
+      "Run a shell command ON a Talon companion device (e.g. the phone) and return its stdout/stderr/exit code. The device executes it in its own sandbox (Android: app UID, or elevated via Shizuku if available). Use for on-device tasks like tidying a folder. Prefer `teleport` for a sustained session.",
+    schema: {
+      device: deviceParam,
+      cmd: z.string().describe("The shell command to run on the device."),
+      cwd: z
+        .string()
+        .optional()
+        .describe("Working directory on the device to run in."),
+      timeout_sec: z
+        .number()
+        .optional()
+        .describe("Max seconds to allow (default 60, max 300)."),
+    },
+    execute: (params, bridge) => bridge("device_exec", params),
+    tag: "mesh",
+  },
+  {
+    name: "device_list_dir",
+    description:
+      "List a directory on a Talon companion device (name, type, size per entry).",
+    schema: {
+      device: deviceParam,
+      path: z.string().describe("Absolute directory path on the device."),
+    },
+    execute: (params, bridge) => bridge("device_list_dir", params),
+    tag: "mesh",
+  },
+  {
+    name: "device_read_file",
+    description:
+      "Read a (text) file off a Talon companion device and return its contents. Small files ride the command channel; big files stream over HTTP automatically. No size cap.",
+    schema: {
+      device: deviceParam,
+      path: z.string().describe("Absolute file path on the device."),
+    },
+    execute: (params, bridge) => bridge("device_read_file", params),
+    tag: "mesh",
+  },
+  {
+    name: "device_write_file",
+    description:
+      "Write text content to a file on a Talon companion device (creates/overwrites).",
+    schema: {
+      device: deviceParam,
+      path: z.string().describe("Absolute file path on the device."),
+      content: z.string().describe("Text content to write."),
+    },
+    execute: (params, bridge) => bridge("device_write_file", params),
+    tag: "mesh",
+  },
+  {
+    name: "device_pull_file",
+    description:
+      "Copy a file FROM a Talon companion device to the daemon host (workspace). Streams disk-to-disk in a single HTTP request at full throughput (no size cap; chunked fallback for old app builds). Lands in workspace/mesh-pull/ unless a local path is given.",
+    schema: {
+      device: deviceParam,
+      remote_path: z.string().describe("Absolute source path on the device."),
+      local_path: z
+        .string()
+        .optional()
+        .describe("Destination under the workspace (optional)."),
+    },
+    execute: (params, bridge) => bridge("device_pull_file", params),
+    tag: "mesh",
+  },
+  {
+    name: "device_push_file",
+    description:
+      "Copy a file FROM the daemon host (workspace) TO a Talon companion device. Streams disk-to-disk in a single HTTP request at full throughput (no size cap; chunked fallback for old app builds).",
+    schema: {
+      device: deviceParam,
+      local_path: z.string().describe("Source path under the workspace."),
+      remote_path: z
+        .string()
+        .describe("Absolute destination path on the device."),
+    },
+    execute: (params, bridge) => bridge("device_push_file", params),
+    tag: "mesh",
+  },
 ];