talon-agent 1.33.0 → 1.34.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.33.0",
+  "version": "1.34.1",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -100,8 +100,8 @@
     "@grammyjs/transformer-throttler": "^1.2.1",
     "@kilocode/sdk": "^7.2.22",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openai/agents": "^0.12.0",
-    "@openai/codex-sdk": "^0.142.0",
+    "@openai/agents": "^0.13.0",
+    "@openai/codex-sdk": "^0.143.0",
     "@opencode-ai/sdk": "^1.17.4",
     "@playwright/mcp": "^0.0.77",
     "@types/cross-spawn": "^6.0.6",

package/src/backend/claude-sdk/handler.ts

@@ -384,6 +384,19 @@ export async function* runChatTurn(
         armPostResultWatchdog();
       }
     }
+
+    // The SDK doesn't throw on API errors — it converts them into a
+    // synthetic assistant message and finishes the turn with an error-
+    // flagged result (usage limits, 429s, auth failures all land here).
+    // Rethrow the captured error text so this turn takes the SAME path
+    // as a thrown SDK error: retry decision, failed-turn accounting, and
+    // an `error` event carrying the real message — instead of being
+    // treated as a normal reply (which, with no delivery tool call,
+    // would trip the flow-violation re-prompt loop and burn more turns
+    // against an already-exhausted limit).
+    if (state.resultErrorText) {
+      throw new Error(state.resultErrorText);
+    }
   } catch (err) {
     if (!postResultForceClosed) {
       const buildRetryStream = (

package/src/backend/claude-sdk/stream.ts

@@ -75,6 +75,17 @@ export type StreamState = {
    * doesn't poison the visible-text delta buffer.
    */
   unflushedThinkingDelta: string;
+  /**
+   * Set when the SDK's final result message reported a failed turn —
+   * either an error subtype (`error_during_execution`, `error_max_turns`,
+   * …) or `is_error: true` on a `success` result. The latter is how API
+   * errors surface: the SDK converts them (usage limits, 429s, auth
+   * failures) into a synthetic assistant message and finishes the turn
+   * "successfully" with the error text in `result` — it never throws.
+   * Carries the best error text available so the handler can fail the
+   * turn with the REAL message instead of treating it as a normal reply.
+   */
+  resultErrorText: string | undefined;
 };
 
 export function createStreamState(): StreamState {
@@ -96,6 +107,7 @@ export function createStreamState(): StreamState {
     turnTerminated: false,
     unflushedTextDelta: "",
     unflushedThinkingDelta: "",
+    resultErrorText: undefined,
   };
 }
 
@@ -358,6 +370,27 @@ export function processResultMessage(
   ) {
     state.currentBlockText = msg.result;
   }
+
+  // Failed turn. Two shapes (see StreamState.resultErrorText):
+  //  - error subtype: no `result` field, but `errors[]` carries diagnostics.
+  //  - success subtype with is_error: `result` (and the trailing assistant
+  //    text) IS the API error message, e.g. "You've hit your weekly limit
+  //    · resets Jul 10, 9am". Prefer that text — it's the user-facing one.
+  if (msg.subtype !== "success") {
+    const diagnostics = (msg.errors ?? [])
+      .filter((e) => typeof e === "string" && !e.startsWith("[ede_diagnostic]"))
+      .join("; ")
+      .slice(0, 500);
+    state.resultErrorText =
+      state.lastTrailingText.trim() ||
+      diagnostics ||
+      `Claude SDK turn failed (${msg.subtype})`;
+  } else if (msg.is_error) {
+    state.resultErrorText =
+      (typeof msg.result === "string" && msg.result.trim()) ||
+      state.lastTrailingText.trim() ||
+      "Claude SDK turn failed (API error)";
+  }
 }
 
 // ── Trailing-text fallback dedup ────────────────────────────────────────────

package/src/bootstrap.ts

@@ -28,7 +28,7 @@ import {
   initTriggers,
   resumeAfterRestart as resumeTriggersAfterRestart,
 } from "./core/background/triggers/index.js";
-import { initDream } from "./core/background/dream.js";
+import { initDream, maybeStartDream } from "./core/background/dream.js";
 import { initHeartbeat } from "./core/background/heartbeat/index.js";
 import { log, logWarn, logDebug } from "./util/log.js";
 import type { TalonConfig } from "./util/config.js";
@@ -409,6 +409,10 @@ export async function initBackendAndDispatcher(
         chatId,
       ),
     onActivity: () => resetPulseTimer(),
+    // Turn-start hook: fire-and-forget dream (background memory
+    // consolidation) check. Wired here so the Weaver stays ignorant of
+    // the dream subsystem.
+    onTurnStart: maybeStartDream,
   });
 
   initPulse();

package/src/core/agent-runtime/events.ts

@@ -259,6 +259,10 @@ export function addUsage(a: UsageSnapshot, b: UsageSnapshot): UsageSnapshot {
  */
 const REASON_TO_KIND: Partial<Record<TalonError["reason"], AgentErrorKind>> = {
   rate_limit: "rate_limit",
+  // Subscription usage limits share the rate_limit kind — same family for
+  // event consumers; `retryable: false` (carried through) is what
+  // distinguishes them from a transient 429.
+  usage_limit: "rate_limit",
   overloaded: "overload",
   context_length: "context_overflow",
   session_expired: "session_expired",

package/src/core/engine/gateway.ts

@@ -16,7 +16,7 @@ import {
 import pRetry, { AbortError } from "p-retry";
 import { classify } from "../errors.js";
 import { getActiveCount } from "./dispatcher.js";
-import { Loom, getActiveLoom } from "../weaver/index.js";
+import { Loom, getActiveLoom, type ContextRegistry } from "../weaver/index.js";
 import { getHealthStatus } from "../../util/watchdog.js";
 import { getActiveSessionCount } from "../../storage/sessions.js";
 import { log, logError, logDebug } from "../../util/log.js";
@@ -89,13 +89,14 @@ export async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
 export class Gateway {
   /**
    * Per-chat live state is owned by the Weaver's Loom. The gateway holds no
-   * registry of its own — it delegates here. `getActiveLoom()` returns the
-   * Weaver's Loom once the dispatcher is wired; the standalone fallback covers
-   * unit tests and the brief startup window before init (when no turn — and so
-   * no context — can exist anyway).
+   * registry of its own — it delegates here, and only through the
+   * `ContextRegistry` face (the gateway never creates or evicts Threads).
+   * `getActiveLoom()` returns the Weaver's Loom once the dispatcher is wired;
+   * the standalone fallback covers unit tests and the brief startup window
+   * before init (when no turn — and so no context — can exist anyway).
    */
   private readonly ownLoom = new Loom();
-  private get loom(): Loom {
+  private get loom(): ContextRegistry {
     return getActiveLoom() ?? this.ownLoom;
   }
 

package/src/core/errors.ts

@@ -9,6 +9,7 @@
 
 type ErrorReason =
   | "rate_limit"
+  | "usage_limit"
   | "overloaded"
   | "network"
   | "auth"
@@ -19,6 +20,19 @@ type ErrorReason =
   | "telegram_api"
   | "unknown";
 
+/**
+ * Claude subscription usage-limit messages, as produced by Claude Code /
+ * the Agent SDK (see rateLimitMessages.ts upstream: "You've hit your
+ * weekly limit · resets Jul 10, 9am", "You're out of extra usage", …)
+ * plus the legacy "Claude AI usage limit reached|<ts>" format. These are
+ * already user-facing text — classification marks them `usage_limit` so
+ * `friendlyMessage` passes them through instead of collapsing them to a
+ * generic template. Unlike `rate_limit` (a transient 429), a usage limit
+ * doesn't clear on a short retry, so `retryable` stays false.
+ */
+const USAGE_LIMIT_RE =
+  /you['’]ve hit your .{0,40}limit|you['’]re out of extra usage|claude ai usage limit reached|usage limit reached/i;
+
 // ── TalonError class ────────────────────────────────────────────────────────
 
 export class TalonError extends Error {
@@ -74,6 +88,18 @@ export function classify(err: unknown): TalonError {
   const statusMatch = msg.match(/\b([45]\d{2})\b/);
   const status = statusMatch ? parseInt(statusMatch[1], 10) : undefined;
 
+  // Subscription usage limit — checked before the generic rate-limit
+  // branch ("usage limit reached" would otherwise never be reached, and
+  // "You've hit your…" carries no 429/rate-limit marker at all).
+  if (USAGE_LIMIT_RE.test(msg)) {
+    return new TalonError(msg, {
+      reason: "usage_limit",
+      retryable: false,
+      status: status ?? 429,
+      cause,
+    });
+  }
+
   // Rate limit
   if (/rate.?limit|429|too many requests/i.test(msg)) {
     const retryMatch = msg.match(/retry.?after[:\s]*(\d+)/i);
@@ -190,6 +216,7 @@ export function classify(err: unknown): TalonError {
 
 const FRIENDLY_MESSAGES: Record<ErrorReason, string> = {
   rate_limit: "Rate limited. Try again in a moment.",
+  usage_limit: "Usage limit reached. Try again after it resets.",
   overloaded:
     "Upstream model is busy right now. Retrying with a faster fallback...",
   network: "Connection issue. Retrying shortly.",
@@ -203,8 +230,30 @@ const FRIENDLY_MESSAGES: Record<ErrorReason, string> = {
   unknown: "Something went wrong. Try again or /reset.",
 };
 
+/**
+ * Reasons whose template alone tells the user nothing actionable — the
+ * underlying error detail is appended so "Something went wrong" always
+ * says WHAT went wrong. Templated reasons like `network`/`overloaded`
+ * stay terse: they're transient and the detail is just transport noise.
+ */
+const DETAIL_REASONS: ReadonlySet<ErrorReason> = new Set([
+  "auth",
+  "bad_request",
+  "forbidden",
+  "unknown",
+]);
+
+/** Collapse whitespace and clip the raw error for inline display. */
+function clipDetail(msg: string, max = 300): string {
+  const flat = msg.replace(/\s+/g, " ").trim();
+  if (!flat || flat === "[non-stringifiable error]") return "";
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
 /**
  * Get a user-friendly error message. For rate limits, includes retry timing.
+ * Usage-limit and session-expired messages pass through verbatim (they're
+ * already user-facing); generic reasons carry the underlying detail.
  */
 export function friendlyMessage(err: unknown): string {
   const classified = err instanceof TalonError ? err : classify(err);
@@ -214,10 +263,19 @@ export function friendlyMessage(err: unknown): string {
     return `Rate limited. Try again in ${seconds} seconds.`;
   }
 
-  // Session expired messages are already user-friendly from the backend
-  if (classified.reason === "session_expired") {
-    return classified.message;
+  // Already user-friendly from the backend — pass through as-is.
+  if (
+    classified.reason === "session_expired" ||
+    classified.reason === "usage_limit"
+  ) {
+    return classified.message || FRIENDLY_MESSAGES[classified.reason];
   }
 
-  return FRIENDLY_MESSAGES[classified.reason];
+  const base = FRIENDLY_MESSAGES[classified.reason];
+  if (DETAIL_REASONS.has(classified.reason)) {
+    const detail = clipDetail(classified.message);
+    // Skip when the detail adds nothing over the template itself.
+    if (detail && detail !== base) return `${base}\n\nDetail: ${detail}`;
+  }
+  return base;
 }

package/src/core/tools/index.ts

@@ -55,6 +55,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 +150,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/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

@@ -78,4 +78,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);
+}