talon-agent 1.40.1 → 1.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.40.1",
+  "version": "1.41.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/core/background/dream.ts

@@ -22,6 +22,7 @@ import { getDefaultModel } from "../models/catalog.js";
 import type { OneShotAgentParams } from "../types.js";
 import type { Backend } from "../agent-runtime/capabilities.js";
 import { getSoul } from "../soul/service.js";
+import { FailureBackoff } from "./failure-backoff.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -53,6 +54,13 @@ const DREAM_LOGS_DIR = resolve(dirs.logs, "dreams");
 // ── State ────────────────────────────────────────────────────────────────────
 
 let dreaming = false; // in-process guard (one dream at a time)
+/**
+ * A failed dream does not advance last_run, and maybeStartDream runs on
+ * every invocation — without a backoff a broken backend gets re-fired on
+ * every message (observed live: a model outage produced 403 identical
+ * consolidation failures). Exported for tests.
+ */
+export const dreamFailureBackoff = new FailureBackoff();
 let configRef: {
   model?: string;
   dreamModel?: string;
@@ -101,6 +109,9 @@ export function initDream(cfg: {
 export function maybeStartDream(): void {
   if (dreaming) return;
   if (configRef?.enabled === false) return;
+  // Inside a failure backoff window — stay quiet instead of re-firing the
+  // same error on every invocation. (Logged once, when the window was set.)
+  if (dreamFailureBackoff.active()) return;
 
   const state = readDreamState();
   const now = Date.now();
@@ -134,6 +145,7 @@ async function executeDream(trigger: "auto" | "forced"): Promise<void> {
   try {
     const dreamLogPath = await runDreamAgent(state?.last_run ?? 0);
     writeDreamState({ last_run: Date.now(), status: "idle" });
+    dreamFailureBackoff.succeed();
     log(
       "dream",
       `Memory consolidation complete (${trigger}), log: ${dreamLogPath}`,
@@ -145,6 +157,14 @@ async function executeDream(trigger: "auto" | "forced"): Promise<void> {
   } catch (err) {
     logError("dream", `Memory consolidation failed (${trigger})`, err);
     writeDreamState({ last_run: state?.last_run ?? 0, status: "idle" });
+    // A failed dream keeps the old last_run, so it would re-fire on the very
+    // next invocation — back off instead (forceDream bypasses the window).
+    const until = dreamFailureBackoff.fail(err);
+    logWarn(
+      "dream",
+      `Backing off until ${new Date(until).toISOString()} ` +
+        `after ${dreamFailureBackoff.failures} consecutive failure(s)`,
+    );
     if (trigger === "forced") throw err;
   } finally {
     dreaming = false;

package/src/core/background/failure-backoff.ts

@@ -0,0 +1,102 @@
+/**
+ * Failure backoff for background agents (heartbeat, dream, …).
+ *
+ * A failed background run typically does NOT advance its `last_run` marker,
+ * so whatever cadence check re-evaluates "is a run due?" re-fires the same
+ * failing run on every tick — observed live as hundreds of identical
+ * failures minutes apart (session-limit nights, model outages, auth
+ * breakage). This module centralizes the cure:
+ *
+ *   - generic failures back off exponentially (5 → 10 → 20 → 40 → 60min cap)
+ *   - session/rate-limit errors that state their own reset time
+ *     ("… resets 12:20am (UTC)") wait until then (+buffer) instead of
+ *     guessing
+ *   - a success clears the window
+ *
+ * Backoff state is in-memory only: a process restart forgets it, which is
+ * fine — the first post-restart attempt either works or re-arms the window.
+ */
+
+const FAILURE_BACKOFF_BASE_MS = 5 * 60 * 1000;
+const FAILURE_BACKOFF_MAX_MS = 60 * 60 * 1000;
+/** Safety margin added past a parsed limit-reset time (clock skew, rollout). */
+const LIMIT_RESET_BUFFER_MS = 2 * 60 * 1000;
+
+/**
+ * Parse the reset wall-clock time out of a session/rate-limit error message,
+ * e.g. "You've hit your session limit · resets 12:20am (UTC)" or
+ * "… resets 3pm (UTC)". Returns the epoch ms of the NEXT occurrence of that
+ * UTC time after `now`, or null when the message doesn't carry one.
+ */
+export function parseSessionLimitResetMs(
+  message: string,
+  now: number,
+): number | null {
+  const m = /resets\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)\s*\(UTC\)/i.exec(
+    message,
+  );
+  if (!m) return null;
+  const rawHour = Number(m[1]);
+  const minute = m[2] ? Number(m[2]) : 0;
+  if (rawHour < 1 || rawHour > 12 || minute > 59) return null;
+  let hour = rawHour % 12;
+  if (m[3].toLowerCase() === "pm") hour += 12;
+  const d = new Date(now);
+  d.setUTCHours(hour, minute, 0, 0);
+  let t = d.getTime();
+  if (t <= now) t += 24 * 60 * 60 * 1000;
+  return t;
+}
+
+/**
+ * When to next allow a run after the Nth consecutive failure (1-based).
+ * Limit errors with a stated reset time wait until then (+buffer);
+ * everything else doubles from 5min up to a 60min cap.
+ */
+export function failureBackoffUntil(
+  err: unknown,
+  consecutiveFailures: number,
+  now: number,
+): number {
+  const message = err instanceof Error ? err.message : String(err);
+  if (/session limit|rate limit/i.test(message)) {
+    const reset = parseSessionLimitResetMs(message, now);
+    if (reset !== null) return reset + LIMIT_RESET_BUFFER_MS;
+  }
+  const exp = Math.min(
+    FAILURE_BACKOFF_BASE_MS * 2 ** Math.max(0, consecutiveFailures - 1),
+    FAILURE_BACKOFF_MAX_MS,
+  );
+  return now + exp;
+}
+
+/**
+ * Per-component backoff holder. Cadence checks gate on `active()`; run
+ * completions call `succeed()` / `fail(err)`.
+ */
+export class FailureBackoff {
+  private consecutiveFailures = 0;
+  private until = 0;
+
+  /** True while inside the backoff window — the caller should skip firing. */
+  active(now = Date.now()): boolean {
+    return now < this.until;
+  }
+
+  /** Record a failure; returns the epoch ms the window is armed until. */
+  fail(err: unknown, now = Date.now()): number {
+    this.consecutiveFailures += 1;
+    this.until = failureBackoffUntil(err, this.consecutiveFailures, now);
+    return this.until;
+  }
+
+  /** Record a success — clears the window and the failure streak. */
+  succeed(): void {
+    this.consecutiveFailures = 0;
+    this.until = 0;
+  }
+
+  get failures(): number {
+    return this.consecutiveFailures;
+  }
+}

package/src/core/background/heartbeat/scheduler.ts

@@ -22,65 +22,6 @@ import { HeartbeatTimeoutError, runHeartbeatAgent } from "./agent.js";
 const STARTUP_DELAY_MS = 5 * 60 * 1000; // 5-minute delay before first run
 const DUE_CHECK_INTERVAL_MS = 60 * 1000;
 
-// Failure backoff. A failed run does NOT advance last_run, so without a
-// backoff the every-minute due check re-fires the heartbeat 60×/hour against
-// the same error (observed live: a session-limit night produced hundreds of
-// identical failures a minute apart). Generic failures back off
-// exponentially; session/rate-limit errors that state their own reset time
-// wait for it instead of guessing.
-const FAILURE_BACKOFF_BASE_MS = 5 * 60 * 1000;
-const FAILURE_BACKOFF_MAX_MS = 60 * 60 * 1000;
-/** Safety margin added past a parsed limit-reset time (clock skew, rollout). */
-const LIMIT_RESET_BUFFER_MS = 2 * 60 * 1000;
-
-/**
- * Parse the reset wall-clock time out of a session/rate-limit error message,
- * e.g. "You've hit your session limit · resets 12:20am (UTC)" or
- * "… resets 3pm (UTC)". Returns the epoch ms of the NEXT occurrence of that
- * UTC time after `now`, or null when the message doesn't carry one.
- */
-export function parseSessionLimitResetMs(
-  message: string,
-  now: number,
-): number | null {
-  const m = /resets\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)\s*\(UTC\)/i.exec(
-    message,
-  );
-  if (!m) return null;
-  const rawHour = Number(m[1]);
-  const minute = m[2] ? Number(m[2]) : 0;
-  if (rawHour < 1 || rawHour > 12 || minute > 59) return null;
-  let hour = rawHour % 12;
-  if (m[3].toLowerCase() === "pm") hour += 12;
-  const d = new Date(now);
-  d.setUTCHours(hour, minute, 0, 0);
-  let t = d.getTime();
-  if (t <= now) t += 24 * 60 * 60 * 1000;
-  return t;
-}
-
-/**
- * When to next allow an auto heartbeat after the Nth consecutive failure
- * (1-based). Limit errors with a stated reset time wait until then (+buffer);
- * everything else doubles from 5min up to a 60min cap.
- */
-export function failureBackoffUntil(
-  err: unknown,
-  consecutiveFailures: number,
-  now: number,
-): number {
-  const message = err instanceof Error ? err.message : String(err);
-  if (/session limit|rate limit/i.test(message)) {
-    const reset = parseSessionLimitResetMs(message, now);
-    if (reset !== null) return reset + LIMIT_RESET_BUFFER_MS;
-  }
-  const exp = Math.min(
-    FAILURE_BACKOFF_BASE_MS * 2 ** Math.max(0, consecutiveFailures - 1),
-    FAILURE_BACKOFF_MAX_MS,
-  );
-  return now + exp;
-}
-
 export function initHeartbeat(cfg: HeartbeatConfig): void {
   hb.config = cfg;
 }
@@ -130,7 +71,7 @@ function runIfDue(intervalMs: number, startup: boolean): void {
   if (hb.running) return;
   // Inside a failure backoff window — stay quiet instead of re-firing the
   // same error every due check. (Logged once, when the window was set.)
-  if (Date.now() < hb.backoffUntil) return;
+  if (hb.failureBackoff.active()) return;
   const lastRun = readHeartbeatState()?.last_run ?? 0;
   if (lastRun <= 0) {
     // Never ran on this install — fire now to establish the cadence.
@@ -240,8 +181,7 @@ async function executeHeartbeat(trigger: "auto" | "forced"): Promise<void> {
         status: "idle",
         run_count: previousRunCount + 1,
       });
-      hb.consecutiveFailures = 0;
-      hb.backoffUntil = 0;
+      hb.failureBackoff.succeed();
       log(
         "heartbeat",
         `Heartbeat #${previousRunCount + 1} complete (${trigger}), log: ${heartbeatLogPath}`,
@@ -267,16 +207,11 @@ async function executeHeartbeat(trigger: "auto" | "forced"): Promise<void> {
       // spaces the next attempt. Every other failure retries against the same
       // last_run — back off so the due check doesn't hammer it every minute.
       if (!isTimeout) {
-        hb.consecutiveFailures += 1;
-        hb.backoffUntil = failureBackoffUntil(
-          err,
-          hb.consecutiveFailures,
-          Date.now(),
-        );
+        const until = hb.failureBackoff.fail(err);
         logWarn(
           "heartbeat",
-          `Backing off until ${new Date(hb.backoffUntil).toISOString()} ` +
-            `after ${hb.consecutiveFailures} consecutive failure(s)`,
+          `Backing off until ${new Date(until).toISOString()} ` +
+            `after ${hb.failureBackoff.failures} consecutive failure(s)`,
         );
       }
       if (trigger === "forced") throw err;

package/src/core/background/heartbeat/state.ts

@@ -10,6 +10,7 @@ import { files as pathFiles } from "../../../util/paths.js";
 import { kvGet, kvSet } from "../../../storage/kv.js";
 import { importLegacyJson } from "../../../storage/legacy-import.js";
 import type { Backend } from "../../agent-runtime/capabilities.js";
+import { FailureBackoff } from "../failure-backoff.js";
 
 export type HeartbeatState = {
   /** Unix millisecond timestamp of the last successfully completed heartbeat run. */
@@ -71,10 +72,8 @@ export const hb: {
   intervalMinutesRef: number;
   config: HeartbeatConfig | null;
   logFileSequence: number;
-  /** Consecutive failed runs — drives the failure backoff curve. */
-  consecutiveFailures: number;
-  /** Epoch ms before which auto runs are suppressed after a failure. */
-  backoffUntil: number;
+  /** Suppresses auto runs after failures (see failure-backoff.ts). */
+  failureBackoff: FailureBackoff;
 } = {
   running: false,
   currentRunPromise: null,
@@ -83,8 +82,7 @@ export const hb: {
   intervalMinutesRef: 60,
   config: null,
   logFileSequence: 0,
-  consecutiveFailures: 0,
-  backoffUntil: 0,
+  failureBackoff: new FailureBackoff(),
 };
 
 // ── State-file I/O ───────────────────────────────────────────────────────────

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

@@ -18,6 +18,9 @@ export const meshHandlers: SharedActionHandlers = {
   get_device_history: (body) =>
     getMeshService().deviceHistory(body.device, body.hours),
   ring_device: (body) => getMeshService().ringDevice(body.device, body.message),
+  // Registry hygiene: drop a stale/superseded device entry. Requires an
+  // explicit target — a destructive action must never default-pick a device.
+  remove_device: (body) => getMeshService().removeDevice(body.device),
   get_device_status: (body) => getMeshService().getDeviceStatus(body.device),
   // Exec + filesystem surface — the substrate teleport routes through.
   device_exec: (body) =>

package/src/core/mesh/registry.ts

@@ -91,10 +91,48 @@ export class MeshRegistry {
       now,
     );
     this.devices.set(device.id, device);
+    // Stale-duplicate eviction. A reinstall (or an old app build) carries its
+    // own persisted device id, so the same physical machine re-registers
+    // under a fresh identity and the old entry lingers forever as an offline
+    // ghost. Same name + platform under a different id, currently OFFLINE →
+    // superseded install, drop it. An online doppelganger is kept: two live
+    // devices can legitimately share a name.
+    let evicted = false;
+    for (const [id, d] of this.devices) {
+      if (id === device.id) continue;
+      if (d.name !== device.name || d.platform !== device.platform) continue;
+      if (toDeviceInfo(d, now, PRESENCE_TIMEOUT_MS).online) continue;
+      this.devices.delete(id);
+      this.locations.delete(id);
+      this.history.delete(id);
+      evicted = true;
+    }
     await this.persistDevices();
+    if (evicted) {
+      await this.persistLocations();
+      await this.persistHistory();
+    }
     return device;
   }
 
+  /**
+   * Drop a device (and its location + history) from the registry. Returns
+   * the removed device, or undefined when the id is unknown. Note a still-
+   * connected companion re-registers on its next heartbeat — removal is for
+   * stale entries.
+   */
+  async removeDevice(deviceId: string): Promise<DeviceInfo | undefined> {
+    const device = this.devices.get(deviceId);
+    if (!device) return undefined;
+    this.devices.delete(deviceId);
+    const hadLocation = this.locations.delete(deviceId);
+    const hadHistory = this.history.delete(deviceId);
+    await this.persistDevices();
+    if (hadLocation) await this.persistLocations();
+    if (hadHistory) await this.persistHistory();
+    return toDeviceInfo(device, device.lastSeen);
+  }
+
   async storeLocation(
     body: Record<string, unknown>,
     now = Date.now(),

package/src/core/mesh/service.ts

@@ -340,6 +340,36 @@ export class MeshService {
     return { ok: true, text: this.locationSummary(target, loc) };
   }
 
+  /**
+   * `remove_device`: drop a stale device from the mesh registry (with its
+   * location + history). Destructive, so it requires an explicit target —
+   * no "default to the most recent device" like the read tools.
+   */
+  async removeDevice(query?: unknown): Promise<MeshToolResult> {
+    await this.load();
+    if (typeof query !== "string" || !query.trim()) {
+      return {
+        ok: false,
+        text: "remove_device needs an explicit device id or name — there is no default target for a destructive operation. See list_devices.",
+      };
+    }
+    const resolved = this.resolveDevice(query);
+    if ("error" in resolved) return { ok: false, text: resolved.error };
+    const target = resolved.target;
+    const removed = await this.registry.removeDevice(target.id);
+    if (!removed) {
+      return { ok: false, text: this.noSuchDevice(query).text };
+    }
+    return {
+      ok: true,
+      text:
+        `Removed ${removed.name} [id: ${removed.id}] (${removed.platform}, last seen ${age(Date.now() - removed.lastSeen)}) from the mesh registry.` +
+        (target.online
+          ? " Note: it was still online — a connected companion re-registers within ~60s, so quit the app first if it keeps coming back."
+          : ""),
+    };
+  }
+
   /** `ring_device`: make the device sound/vibrate so it can be found. */
   ringDevice(query?: unknown, message?: unknown): Promise<MeshToolResult> {
     return this.commandTool(query, "ring", {

package/src/core/tools/mesh.ts

@@ -60,6 +60,20 @@ export const meshTools: ToolDefinition[] = [
     execute: (params, bridge) => bridge("ring_device", params),
     tag: "mesh",
   },
+  {
+    name: "remove_device",
+    description:
+      "Remove a stale device from the mesh registry (with its stored location and history). Use for superseded installs and old duplicates — e.g. a reinstalled companion that re-registered under a new id, leaving the old entry as an offline ghost. Requires an explicit device id or name (no default target). Removing a still-connected device is pointless: it re-registers on its next heartbeat within ~60s.",
+    schema: {
+      device: z
+        .string()
+        .describe(
+          "Device id, exact name, or unique name fragment of the entry to remove (see list_devices). Prefer the id when duplicates share a name.",
+        ),
+    },
+    execute: (params, bridge) => bridge("remove_device", params),
+    tag: "mesh",
+  },
   {
     name: "get_device_status",
     description:
@@ -71,7 +85,7 @@ export const meshTools: ToolDefinition[] = [
   {
     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.",
+      "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. For persistent streams (log tailing, watchers), background with output redirected to a file — `cmd > /tmp/out.log 2>&1 &` returns immediately; poll the file with device_read_file.",
     schema: {
       device: deviceParam,
       cmd: z.string().describe("The shell command to run on the device."),