talon-agent 1.34.0 → 1.35.0

package/src/core/tools/index.ts

@@ -21,6 +21,7 @@ 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";
 
 /** All built-in tool definitions. */
 export const ALL_TOOLS: readonly ToolDefinition[] = [
@@ -38,6 +39,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...webTools,
   ...adminTools,
   ...modelTools,
+  ...meshTools,
 ];
 
 /**
@@ -55,6 +57,17 @@ const TURN_TERMINATOR_NAMES: ReadonlySet<string> = new Set(
   ALL_TOOLS.filter((t) => t.endsTurn).map((t) => t.name),
 );
 
+/**
+ * Names of reply-delivery tools (`delivery: true` on the definition):
+ * their observable effect is the message/reaction itself, which
+ * frontends already surface as first-class output. Kept separate from
+ * `TURN_TERMINATOR_NAMES` — `send_message` delivers without ending the
+ * turn, and a future terminator need not be a delivery tool.
+ */
+const DELIVERY_TOOL_NAMES: ReadonlySet<string> = new Set(
+  ALL_TOOLS.filter((t) => t.delivery).map((t) => t.name),
+);
+
 /**
  * All tool names registered in Talon's tool catalog. Used by
  * `stripMcpPrefix` to recognise the bare name when a backend prefixes
@@ -139,6 +152,24 @@ export function isTurnTerminator(
   return true;
 }
 
+/**
+ * Whether a tool call by this name is reply-delivery plumbing
+ * (`delivery: true` on its definition) — `end_turn`, `send`,
+ * `send_message`, `react`, … Its effect reaches the user as a chat
+ * message or reaction, so activity timelines ("what the model did")
+ * must exclude it or the reply gets double-reported as work.
+ *
+ * Accepts bare names (`end_turn`) and every prefixed form
+ * `stripMcpPrefix` understands (`mcp__desktop-tools__end_turn`,
+ * Kilo's `desktop-tools_end_turn`).
+ */
+export function isDeliveryTool(toolName: string): boolean {
+  return (
+    DELIVERY_TOOL_NAMES.has(toolName) ||
+    DELIVERY_TOOL_NAMES.has(stripMcpPrefix(toolName))
+  );
+}
+
 /** Filter options for composing a tool set. */
 export interface ComposeOptions {
   /** Include only tools available on this frontend. */

package/src/core/tools/mesh.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+/**
+ * Device-mesh tools. Deliberately NOT frontend-restricted: the mesh is
+ * daemon-wide state served by shared gateway actions, so the model can see,
+ * locate, and command companion devices from any chat surface.
+ */
+
+/** Shared device-target parameter: id or name fragment; default = mobile. */
+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.",
+  );
+
+export const meshTools: ToolDefinition[] = [
+  {
+    name: "list_devices",
+    description:
+      "List all Talon companion mesh devices with id, platform, online presence, last-seen age, battery state, last-known location, and supported commands.",
+    schema: {},
+    execute: (_params, bridge) => bridge("list_devices", {}),
+    tag: "mesh",
+  },
+  {
+    name: "get_device_location",
+    description:
+      "Get any Talon companion device's current or last-known location. Sends an on-demand locate request first, waits briefly for a fresh GPS fix, then falls back to last-known. With no device, uses the most recently seen mobile device.",
+    schema: { device: deviceParam },
+    execute: (params, bridge) => bridge("get_device_location", params),
+    tag: "mesh",
+  },
+  {
+    name: "get_device_history",
+    description:
+      "Movement and battery history for a Talon companion device: a timeline of its reported locations over a window (default 24h, max 168h), with distance traveled and battery trend. Answers questions like where a device was earlier or how fast its battery is draining.",
+    schema: {
+      device: deviceParam,
+      hours: z
+        .number()
+        .optional()
+        .describe("History window in hours (1-168, default 24)."),
+    },
+    execute: (params, bridge) => bridge("get_device_history", params),
+    tag: "mesh",
+  },
+  {
+    name: "ring_device",
+    description:
+      "Make a Talon companion device ring/vibrate so it can be found (find-my-phone). Optionally include a short message the device may display.",
+    schema: {
+      device: deviceParam,
+      message: z
+        .string()
+        .optional()
+        .describe("Optional short note to show on the device."),
+    },
+    execute: (params, bridge) => bridge("ring_device", params),
+    tag: "mesh",
+  },
+  {
+    name: "get_device_status",
+    description:
+      "Get live status straight from a Talon companion device: battery and charging state, platform/OS details, app version, and mesh sharing settings.",
+    schema: { device: deviceParam },
+    execute: (params, bridge) => bridge("get_device_status", params),
+    tag: "mesh",
+  },
+];

package/src/core/tools/messaging.ts

@@ -113,6 +113,7 @@ Notes:
     frontends: ["telegram", "teams", "discord", "native"],
     tag: "messaging",
     endsTurn: true,
+    delivery: true,
   },
 
   // ── Telegram unified send ─────────────────────────────────────────────
@@ -372,6 +373,7 @@ Examples:
     },
     frontends: ["telegram", "discord"],
     tag: "messaging",
+    delivery: true,
   },
 
   // ── Native send_message ────────────────────────────────────────────────
@@ -388,6 +390,7 @@ Examples:
     execute: (params, bridge) => bridge("send_message", params),
     frontends: ["teams", "native"],
     tag: "messaging",
+    delivery: true,
   },
 
   // ── Native send_message_with_buttons ──────────────────────────────────
@@ -412,6 +415,7 @@ Example: send_message_with_buttons(text="Choose:", rows=[[{"text":"Docs","url":"
     execute: (params, bridge) => bridge("send_message_with_buttons", params),
     frontends: ["teams", "native"],
     tag: "messaging",
+    delivery: true,
   },
 
   // ── react ─────────────────────────────────────────────────────────────
@@ -469,6 +473,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
     frontends: ["telegram", "discord", "native"],
     tag: "messaging",
     endsTurn: true,
+    delivery: true,
   },
 
   // ── edit_message ──────────────────────────────────────────────────────

package/src/core/tools/types.ts

@@ -26,7 +26,8 @@ export type ToolTag =
   | "skills"
   | "web"
   | "admin"
-  | "models";
+  | "models"
+  | "mesh";
 
 /** The bridge caller signature — injected into execute(). */
 export type BridgeFunction = (
@@ -78,4 +79,15 @@ export interface ToolDefinition {
    * is the shared declarative signal, not the implementation.
    */
   readonly endsTurn?: boolean;
+
+  /**
+   * Reply-delivery plumbing: the tool's observable effect IS the
+   * message/reaction the user receives, which every frontend already
+   * surfaces as first-class output (a chat message, a reaction). Tools
+   * flagged here are excluded from activity timelines — the tool
+   * events a frontend shows or persists as "what the model did" —
+   * because reporting them there double-counts the reply as work.
+   * Declared on the definition so consumers never classify by name.
+   */
+  readonly delivery?: boolean;
 }

package/src/core/weaver/index.ts

@@ -1,9 +1,16 @@
 export { Thread, type Warp, type ThreadSnapshot } from "./thread.js";
 export { ThreadSession, type SessionSummary } from "./thread-session.js";
-export { Loom } from "./loom.js";
+export { Loom, type ContextRegistry } from "./loom.js";
+export { carryTurnEvents, type EventSink } from "./shuttle.js";
+export { startTypingLoop, TYPING_REFRESH_MS } from "./typing-loop.js";
+export { prefetchMemory } from "./memory-prefetch.js";
+export {
+  resolveWarp,
+  type WarpResolution,
+  type WarpResolverDeps,
+} from "./warp-resolver.js";
 export {
   Weaver,
-  getWeaver,
   getActiveLoom,
   initWeaver,
   type WeaverDeps,

package/src/core/weaver/loom.ts

@@ -1,4 +1,30 @@
-import { Thread } from "./thread.js";
+import { Thread, type ThreadSnapshot } from "./thread.js";
+
+/**
+ * The context-tracking face of the Loom — everything the gateway needs
+ * to bracket turns and answer numeric-keyed queries, and nothing else.
+ * The gateway depends on this interface (not the concrete Loom), so its
+ * contract with the registry is explicit and a test can substitute a
+ * stub without dragging in Thread creation or eviction.
+ */
+export interface ContextRegistry {
+  /** Acquire the execution context for a turn. See `Loom.acquireContext`. */
+  acquireContext(numericChatId: number, stringId?: string): Thread;
+  /** Release one context hold, addressed by numeric or string id. */
+  releaseContext(id: number | string): void;
+  /** Count one bridge-sent message against the chat's current turn. */
+  noteMessageSent(numericChatId: number): void;
+  /** Messages the bridge has sent during the chat's current turn. */
+  messageCount(numericChatId: number): number;
+  /** Whether a turn is currently holding the chat's execution context. */
+  hasActiveContext(numericChatId: number): boolean;
+  /** Number of chats currently holding an execution context. */
+  activeContextCount(): number;
+  /** Resolve a string chat id to the numeric id of its active context. */
+  numericForStringId(stringId: string): number | null;
+  /** Number of live Threads in the registry. */
+  size(): number;
+}
 
 /**
  * Loom — the single registry of live chat Threads.
@@ -9,7 +35,7 @@ import { Thread } from "./thread.js";
  * route inbound tool calls and report active chats without owning any
  * per-chat state of its own.
  */
-export class Loom {
+export class Loom implements ContextRegistry {
   private readonly threads = new Map<string, Thread>();
   private readonly byNumeric = new Map<number, Thread>();
 
@@ -44,6 +70,11 @@ export class Loom {
     return [...this.threads.keys()];
   }
 
+  /** An immutable view of every live Thread. Reading is side-effect free. */
+  snapshot(): ThreadSnapshot[] {
+    return [...this.threads.values()].map((thread) => thread.describe());
+  }
+
   // ── Execution context (gateway-facing; absorbed ChatContext) ────────────────
 
   /**

package/src/core/weaver/memory-prefetch.ts

@@ -0,0 +1,49 @@
+/**
+ * Memory prefetch (Phase B) — optional pre-retrieval of palace memory
+ * for live user messages, strictly fail-closed: a broken palace must
+ * never block chat delivery. The result is dynamic turn context passed
+ * through ChatRunParams; it never touches the frozen prompt.
+ */
+
+import type { RetrievedMemory } from "../agent-runtime/capabilities.js";
+import type { MemoryRetriever } from "../memory/retrieval.js";
+import { logDebug, logWarn } from "../../util/log.js";
+
+export type PrefetchMemoryInput = {
+  chatId: string;
+  text: string;
+  senderName: string;
+  isGroup: boolean;
+  /** Request id for log correlation. */
+  reqId: string;
+};
+
+export async function prefetchMemory(
+  retrieve: MemoryRetriever,
+  input: PrefetchMemoryInput,
+): Promise<RetrievedMemory | undefined> {
+  try {
+    const retrieved = await retrieve({
+      runKind: "chat",
+      chatId: input.chatId,
+      text: input.text,
+      senderName: input.senderName,
+      isGroup: input.isGroup,
+    });
+    if (retrieved) {
+      logDebug(
+        "dispatcher",
+        `[${input.reqId}] memory pre-retrieval: ${retrieved.items.length} item(s), ` +
+          `${retrieved.items.reduce((n, i) => n + i.text.length, 0)} chars`,
+      );
+    }
+    return retrieved;
+  } catch (err) {
+    logWarn(
+      "dispatcher",
+      `[${input.reqId}] memory pre-retrieval failed (running turn without it): ` +
+        (err instanceof Error ? err.message : String(err)),
+    );
+    return undefined;
+  }
+}

package/src/core/weaver/shuttle.ts

@@ -0,0 +1,63 @@
+/**
+ * Shuttle — carries the weft across the warp: consumes a backend's
+ * canonical `AgentEvent` stream and forwards every event to the
+ * frontend's `onEvent` sink (no callback bridge, no back-translation).
+ *
+ * The Shuttle owns the three stream-consumption invariants so no caller
+ * can get them subtly wrong:
+ *
+ *   - **ordering** — events are awaited in stream order, so a consumer
+ *     that needs serial delivery gets it;
+ *   - **ack settlement** — `assistant_message.deliveryAck` is ALWAYS
+ *     settled, even when no `onEvent` sink is supplied or the sink
+ *     ignores the event. Otherwise the callback-shaped backend
+ *     (handler-to-events) blocks forever awaiting delivery
+ *     confirmation. The frontend's job is just to deliver and throw on
+ *     failure; the Shuttle maps that onto the ack (resolve on success →
+ *     block delivered; reject on throw → backend retries, e.g. Codex
+ *     oversized-message path);
+ *   - **terminators** — the `completed` event's `AgentResult` is
+ *     captured for the return value, and an `error` terminator is
+ *     rethrown as `AgentRunError` so callers' catch paths keep working.
+ */
+
+import {
+  AgentRunError,
+  type AgentEvent,
+  type AgentResult,
+} from "../agent-runtime/events.js";
+
+export type EventSink = (event: AgentEvent) => void | Promise<void>;
+
+/**
+ * Pump the stream to completion. Returns the `completed` event's
+ * result (if the backend emitted one); throws `AgentRunError` when the
+ * stream terminates with an `error` event.
+ */
+export async function carryTurnEvents(
+  stream: AsyncIterable<AgentEvent>,
+  onEvent?: EventSink,
+): Promise<AgentResult | undefined> {
+  let agentResult: AgentResult | undefined;
+  for await (const event of stream) {
+    if (event.type === "completed") {
+      agentResult = event.result;
+    }
+
+    if (event.type === "assistant_message" && event.deliveryAck) {
+      try {
+        await onEvent?.(event);
+        event.deliveryAck.resolve();
+      } catch (err) {
+        event.deliveryAck.reject(err);
+      }
+      continue;
+    }
+
+    await onEvent?.(event);
+    if (event.type === "error") {
+      throw new AgentRunError(event.error);
+    }
+  }
+  return agentResult;
+}

package/src/core/weaver/typing-loop.ts

@@ -0,0 +1,36 @@
+/**
+ * Typing loop — keeps the frontend's typing indicator alive for the
+ * duration of a turn. Sends immediately, then re-sends on an interval;
+ * every send is fail-soft (logged, never thrown) because a dropped
+ * indicator must not fail the turn.
+ */
+
+import { logWarn } from "../../util/log.js";
+
+/** Platforms expire typing indicators after ~5s; refresh under that. */
+export const TYPING_REFRESH_MS = 4000;
+
+export type SendTyping = (
+  numericChatId: number,
+  stringId?: string,
+) => Promise<void>;
+
+/** Start the loop. Call the returned function to stop it. */
+export function startTypingLoop(
+  sendTyping: SendTyping,
+  numericChatId: number,
+  stringId: string,
+  intervalMs = TYPING_REFRESH_MS,
+): () => void {
+  const send = (label: string) => {
+    sendTyping(numericChatId, stringId).catch((err: unknown) => {
+      logWarn(
+        "dispatcher",
+        `${label} failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    });
+  };
+  send("sendTyping");
+  const timer = setInterval(() => send("sendTyping interval"), intervalMs);
+  return () => clearInterval(timer);
+}

package/src/core/weaver/warp-resolver.ts

@@ -0,0 +1,123 @@
+/**
+ * WarpResolver — turns an incoming turn into the model/backend binding
+ * (the warp) it will run on.
+ *
+ * Owns the whole resolution ladder so the Weaver never sees a partial
+ * state: active-model resolution, the send-time null-model guard, and
+ * the per-run override (triggers/cron) with its fall-back-to-chat-model
+ * safety. The result is a discriminated union — either a bound warp or
+ * a refusal with the user-facing message to deliver — so callers can't
+ * forget to handle the "no model" case.
+ */
+
+import type { ModelRef } from "../agent-runtime/model-ref.js";
+import { logDebug, logWarn } from "../../util/log.js";
+
+export type WarpResolverDeps = {
+  /**
+   * Walks the 5-step active-model resolution chain for the chat. When
+   * `model`/`ref` are both `null` (catalog-driven backend with no
+   * per-chat pick and no operator default) the turn is refused — see
+   * `resolve()`.
+   */
+  resolveActiveModel: (chatId: string) => Promise<{
+    model: string | null;
+    ref: ModelRef | null;
+    backendId: string;
+  }>;
+  /**
+   * Validates + materialises an explicit per-run model id against the
+   * chat's backend. Returns `null` when the id isn't selectable, so
+   * the resolver falls back to the chat model. Restricted to the
+   * chat's own backend so the session still resumes.
+   */
+  resolveModelOverride?: (
+    chatId: string,
+    modelId: string,
+  ) => Promise<ModelRef | null>;
+};
+
+export type ResolveWarpInput = {
+  chatId: string;
+  /** Optional per-run model override (triggers/cron). */
+  modelOverride?: string;
+  /** Turn source, used only for override logging. */
+  source: string;
+  /** Request id for log correlation. */
+  reqId: string;
+};
+
+export type WarpResolution =
+  | {
+      ok: true;
+      /** The ModelRef the turn runs on (post-override). */
+      ref: ModelRef;
+      backendId: string;
+      /** A per-run override was applied for this turn. */
+      overridden: boolean;
+    }
+  | {
+      ok: false;
+      backendId: string;
+      /** User-facing refusal ("use /model to pick one"). */
+      message: string;
+    };
+
+export async function resolveWarp(
+  deps: WarpResolverDeps,
+  input: ResolveWarpInput,
+): Promise<WarpResolution> {
+  const { chatId, modelOverride, source, reqId } = input;
+
+  // Send-time null-model guard. When the active-model resolver returns
+  // no usable model, refuse to call the backend — it would either error
+  // opaquely or run on the wrong default.
+  const { model, ref, backendId } = await deps.resolveActiveModel(chatId);
+  if (model === null || ref === null) {
+    logWarn(
+      "dispatcher",
+      `[${reqId}] refusing query: no model resolved (chat=${chatId}, backend=${backendId})`,
+    );
+    return {
+      ok: false,
+      backendId,
+      message:
+        `No model selected for backend \`${backendId}\`. ` +
+        `Use /model to pick one — or set ` +
+        `\`backendDefaults.${backendId}\` in talon.json to apply a ` +
+        `default for all chats on this backend.`,
+    };
+  }
+
+  // Per-run model override (triggers/cron). Resolve against the chat's
+  // backend; on success swap the ref for this turn only, on failure fall
+  // back to the chat model so a stale override never kills the run.
+  let runRef = ref;
+  if (modelOverride && deps.resolveModelOverride) {
+    try {
+      const overrideRef = await deps.resolveModelOverride(
+        chatId,
+        modelOverride,
+      );
+      if (overrideRef) {
+        runRef = overrideRef;
+        logDebug(
+          "dispatcher",
+          `[${reqId}] model override → ${modelOverride} (${source})`,
+        );
+      } else {
+        logWarn(
+          "dispatcher",
+          `[${reqId}] model override "${modelOverride}" not resolvable on backend ${backendId}; using chat model`,
+        );
+      }
+    } catch (err) {
+      logWarn(
+        "dispatcher",
+        `[${reqId}] model override resolution threw: ${err instanceof Error ? err.message : String(err)}; using chat model`,
+      );
+    }
+  }
+
+  return { ok: true, ref: runRef, backendId, overridden: runRef !== ref };
+}