talon-agent 1.34.1 → 1.36.0

package/src/core/mesh/teleport.ts

@@ -0,0 +1,104 @@
+/**
+ * Teleport state — the single "active node" the 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
+ * and is shared across the process (the native gateway actions read it on
+ * every call). Deliberately global, not per-chat: teleport is an operator
+ * mode for the whole daemon, matching how Dylan drives a single bot.
+ */
+
+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;
+};
+
+/** 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: TeleportState | null | undefined;
+
+/** The active teleport target, or null when operating locally. */
+export async function getTeleport(): Promise<TeleportState | null> {
+  if (cache !== undefined) return cache;
+  try {
+    const raw = await readFile(stateFile(), "utf8");
+    const parsed = JSON.parse(raw) as Partial<TeleportState>;
+    cache =
+      parsed && typeof parsed.deviceId === "string" && parsed.deviceId
+        ? {
+            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(),
+          }
+        : null;
+  } catch {
+    cache = null;
+  }
+  return cache;
+}
+
+/** Engage teleport onto a device. */
+export async function setTeleport(
+  deviceId: string,
+  deviceName: string,
+): Promise<TeleportState> {
+  const state: TeleportState = {
+    deviceId,
+    deviceName,
+    since: Date.now(),
+  };
+  cache = state;
+  await writePrivateJson(stateFile(), state);
+  return state;
+}
+
+/** Persist an updated working directory for the active teleport. */
+export async function setTeleportCwd(cwd: string): Promise<void> {
+  const current = await getTeleport();
+  if (!current) return;
+  const next: TeleportState = { ...current, cwd };
+  cache = next;
+  await writePrivateJson(stateFile(), next);
+}
+
+/** Return to local operation. Returns the prior target (for the message). */
+export async function clearTeleport(): Promise<TeleportState | null> {
+  const prior = await getTeleport();
+  cache = null;
+  await writePrivateJson(stateFile(), null);
+  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/mesh/types.ts

@@ -0,0 +1,137 @@
+/**
+ * Device-mesh domain types + normalizers.
+ *
+ * The canonical shapes for companion devices and their reported locations.
+ * They live in core (not a frontend) because the mesh is daemon-wide state:
+ * devices register through the native bridge transport, but the model reads
+ * them from ANY frontend via the shared `list_devices` /
+ * `get_device_location` gateway actions. The bridge protocol re-exports
+ * these types so the wire contract is unchanged.
+ */
+
+export type DevicePlatform = "android" | "macos" | "windows" | "linux" | "ios";
+
+export type DeviceInfo = {
+  id: string;
+  name: string;
+  platform: DevicePlatform;
+  appVersion: string;
+  online: boolean;
+  /** Epoch milliseconds. */
+  lastSeen: number;
+  /** Battery percent, 0-100. */
+  battery?: number;
+  charging?: boolean;
+  /**
+   * Command names this device can execute (e.g. "locate", "ring",
+   * "open_url"). Reported by the device at registration; absent for app
+   * versions that predate the command channel — treat as unknown, not
+   * empty.
+   */
+  capabilities?: string[];
+};
+
+/**
+ * An on-demand command pushed to one companion device over the mesh
+ * transport. The device executes it and answers with a DeviceCommandResult
+ * carrying the same `id`.
+ */
+export type DeviceCommand = {
+  /** Correlation id — echoed back as the result's `commandId`. */
+  id: string;
+  deviceId: string;
+  /** Command name (e.g. "ring", "open_url", "clipboard_get", "status"). */
+  name: string;
+  params: Record<string, unknown>;
+};
+
+/** A device's answer to a DeviceCommand. */
+export type DeviceCommandResult = {
+  commandId: string;
+  deviceId: string;
+  ok: boolean;
+  /** Human-readable outcome (shown to the model). */
+  message?: string;
+  /** Structured payload (e.g. clipboard text, status fields). */
+  data?: Record<string, unknown>;
+};
+
+export type DeviceLocation = {
+  deviceId: string;
+  lat: number;
+  lon: number;
+  accuracyM?: number;
+  altitudeM?: number;
+  speedMps?: number;
+  headingDeg?: number;
+  /** Epoch milliseconds. */
+  ts: number;
+  provider?: string;
+  batteryPct?: number;
+};
+
+export function toDeviceInfo(
+  value: DeviceInfo,
+  now = Date.now(),
+  offlineAfterMs = 90_000,
+): DeviceInfo {
+  const battery =
+    typeof value.battery === "number"
+      ? Math.max(0, Math.min(100, Math.round(value.battery)))
+      : undefined;
+  return {
+    id: value.id,
+    name: value.name,
+    platform: value.platform,
+    appVersion: value.appVersion,
+    online: now - value.lastSeen <= offlineAfterMs && value.online,
+    lastSeen: value.lastSeen,
+    ...(battery !== undefined ? { battery } : {}),
+    ...(typeof value.charging === "boolean"
+      ? { charging: value.charging }
+      : {}),
+    ...(value.capabilities?.length
+      ? { capabilities: [...value.capabilities] }
+      : {}),
+  };
+}
+
+/**
+ * Normalize a device's advertised capability list: strings only, trimmed,
+ * lowercased, deduped, and bounded so a misbehaving client can't bloat the
+ * persisted registry. Undefined when nothing valid remains.
+ */
+export function sanitizeCapabilities(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (typeof item !== "string") continue;
+    const cap = item.trim().toLowerCase().slice(0, 32);
+    if (cap) seen.add(cap);
+    if (seen.size >= 16) break;
+  }
+  return seen.size ? [...seen] : undefined;
+}
+
+export function toDeviceLocation(value: DeviceLocation): DeviceLocation {
+  return {
+    deviceId: value.deviceId,
+    lat: value.lat,
+    lon: value.lon,
+    ...(typeof value.accuracyM === "number"
+      ? { accuracyM: value.accuracyM }
+      : {}),
+    ...(typeof value.altitudeM === "number"
+      ? { altitudeM: value.altitudeM }
+      : {}),
+    ...(typeof value.speedMps === "number" ? { speedMps: value.speedMps } : {}),
+    ...(typeof value.headingDeg === "number"
+      ? { headingDeg: value.headingDeg }
+      : {}),
+    ts: value.ts,
+    ...(value.provider ? { provider: value.provider } : {}),
+    ...(typeof value.batteryPct === "number"
+      ? { batteryPct: Math.max(0, Math.min(100, Math.round(value.batteryPct))) }
+      : {}),
+  };
+}

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

@@ -21,6 +21,8 @@ import { skillTools } from "./skills.js";
 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[] = [
@@ -38,8 +40,18 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...webTools,
   ...adminTools,
   ...modelTools,
+  ...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.
  *
@@ -73,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),
 );
 
 /**
@@ -178,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;
 }
 
 /**
@@ -187,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(