@tyvm/knowhow 0.0.109 → 0.0.110

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.109",
+  "version": "0.0.110",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {

package/scripts/build-for-node.sh

@@ -7,11 +7,10 @@
 # This script:
 #   1. Compiles TypeScript with Node 20 (required for workspace deps)
 #   2. Creates /tmp/knowhow-node-<major> with the compiled output
-#   3. Installs the correct isolated-vm version for the target node in that dir
-#   4. Symlinks the package globally for ALL installed nvm versions matching the target
+#   3. Symlinks the package globally for ALL installed nvm versions matching the target
 #
-# This approach avoids polluting the workspace node_modules with a different
-# isolated-vm ABI, so Node 20 and Node 24 builds can coexist.
+# Note: isolated-vm is now in @tyvm/knowhow-module-script — install that separately
+# for the correct node version if you need script execution support.
 
 set -e
 
@@ -81,23 +80,11 @@ fi
 
 # Use the last (latest patch) for building
 TARGET_NODE_BIN="${TARGET_NODE_BINS[${#TARGET_NODE_BINS[@]}-1]}"
-TARGET_NODE_NPM="$(dirname "$TARGET_NODE_BIN")/npm"
-TARGET_NODE_DIR="$(dirname "$TARGET_NODE_BIN")"
 TARGET_NODE_ACTUAL_VERSION="$("$TARGET_NODE_BIN" --version)"
 
 echo "🎯 Found Node $TARGET_VERSION installs: ${TARGET_NODE_BINS[*]}"
 echo "🔨 Building with: $TARGET_NODE_BIN ($TARGET_NODE_ACTUAL_VERSION)"
 
-# --- Pick the right isolated-vm version for the target node ---
-# isolated-vm@5.x supports Node <22, isolated-vm@6.x requires Node >=22
-if [ "$TARGET_MAJOR" -ge 22 ]; then
-  IVM_VERSION="^6.0.0"
-  echo "📌 Using isolated-vm@6.x (Node >= 22)"
-else
-  IVM_VERSION="^5.0.4"
-  echo "📌 Using isolated-vm@5.x (Node < 22)"
-fi
-
 # --- Create staging directory ---
 STAGING_DIR="/tmp/knowhow-node-${TARGET_MAJOR}"
 rm -rf "$STAGING_DIR"
@@ -114,13 +101,11 @@ for item in README.md LICENSE .npmignore; do
   [ -e "$PACKAGE_DIR/$item" ] && cp "$PACKAGE_DIR/$item" "$STAGING_DIR/" || true
 done
 
-# --- Patch package.json for target isolated-vm version ---
-echo "📝 Patching package.json for isolated-vm $IVM_VERSION..."
+# --- Patch package.json to remove workspace protocol deps ---
+echo "📝 Patching package.json..."
 "$NODE20_BIN" -e "
   const fs = require('fs');
   const pkg = JSON.parse(fs.readFileSync('$STAGING_DIR/package.json', 'utf8'));
-  pkg.dependencies['isolated-vm'] = '$IVM_VERSION';
-  // Remove workspace protocol deps that won't resolve outside the monorepo
   if (pkg.dependencies) {
     for (const [k, v] of Object.entries(pkg.dependencies)) {
       if (String(v).startsWith('workspace:')) delete pkg.dependencies[k];
@@ -130,13 +115,14 @@ echo "📝 Patching package.json for isolated-vm $IVM_VERSION..."
   console.log('✅ package.json patched');
 "
 
-# --- Install deps in staging dir using target node ---
+# --- Install dependencies in staging dir with target Node ---
+TARGET_NODE_NPM="$(dirname "$TARGET_NODE_BIN")/npm"
 echo ""
 echo "📦 Installing dependencies in staging dir with Node $TARGET_MAJOR..."
 cd "$STAGING_DIR"
-# Prepend target node bin to PATH so npm/node-gyp uses the correct node version
-PATH="$TARGET_NODE_DIR:$PATH" "$TARGET_NODE_NPM" install --no-save 2>&1
-echo "✅ Dependencies installed (isolated-vm compiled for Node $TARGET_MAJOR)"
+"$TARGET_NODE_NPM" install --omit=dev
+echo "✅ Dependencies installed"
+cd "$PACKAGE_DIR"
 
 # --- Symlink globally for ALL matching Node version installs ---
 PKG_NAME="$("$NODE20_BIN" -e "console.log(require('$STAGING_DIR/package.json').name)")"

package/src/agents/tools/list.ts

@@ -156,8 +156,8 @@ export const includedTools = [
           },
           model: {
             type: "string",
-            description: "The model to use (default: 'gpt-4o')",
-            default: "gpt-4o",
+            description: "The model to use (default: 'gpt-5.4-nano')",
+            default: "gpt-5.4-nano",
           },
         },
         required: ["imageUrl", "question"],

package/src/ai.ts

@@ -79,59 +79,103 @@ function estimateTokens(text: string): number {
   return Math.ceil(text.length / 4);
 }
 
-export async function summarizeTexts(
+/**
+ * Returns true if the error looks like a context-window-exceeded error from any provider.
+ */
+function isContextLengthError(err: any): boolean {
+  const msg: string = (err?.message || "").toLowerCase();
+  return (
+    msg.includes("context window") ||
+    msg.includes("context length") ||
+    msg.includes("maximum context") ||
+    msg.includes("input too long") ||
+    msg.includes("too long") ||
+    msg.includes("exceeds the context") ||
+    msg.includes("input exceeds") ||
+    (err?.status === 400 && msg.includes("context"))
+  );
+}
+
+/**
+ * Recursively summarize an array of texts using a split-and-summarize approach.
+ * When the combined texts exceed the context window (either by estimate or actual API error),
+ * split the array in half, summarize each half recursively, then combine.
+ */
+async function summarizeTextsRecursive(
   texts: string[],
   template: string,
-  model = "",
-  agent = ""
-) {
-  const effectiveModel = model || Models.openai.GPT_54_Nano;
+  model: string,
+  agent: string,
+  contextLimit: number,
+  depth = 0
+): Promise<string> {
+  const indent = "  ".repeat(depth);
+
+  // Base case: single text — just run the prompt directly
+  if (texts.length === 1) {
+    const content = template.replaceAll("{text}", texts[0]);
+    console.log(`${indent}summarizeTexts[depth=${depth}]: single text, ~${estimateTokens(content)} tokens`);
+    return singlePrompt(content, model, agent);
+  }
 
-  // Estimate total tokens if we were to combine all texts into one prompt
+  // Check if combined fits in context window by estimate
   const combinedText = texts.join("\n\n");
   const combinedContent = template.replaceAll("{text}", combinedText);
   const estimatedTokens = estimateTokens(combinedContent);
-  const contextLimit = getModelContextLimit(effectiveModel);
-
-  console.log(
-    `summarizeTexts: ${texts.length} text(s), ~${estimatedTokens} estimated tokens, context limit: ${contextLimit}`
-  );
 
-  // If everything fits in one context window, do a single prompt
   if (estimatedTokens < contextLimit) {
-    console.log("summarizeTexts: fits in context window, using single prompt");
-    return singlePrompt(combinedContent, model, agent).catch((err) => {
-      return `Texts of combined length ${combinedText.length} could not be summarized due to error: ${err.message}`;
-    });
+    // Try single combined prompt — if context error, fall through to split
+    console.log(`${indent}summarizeTexts[depth=${depth}]: ${texts.length} texts, ~${estimatedTokens} tokens, trying combined`);
+    try {
+      return await singlePrompt(combinedContent, model, agent);
+    } catch (err: any) {
+      if (!isContextLengthError(err)) throw err;
+      console.log(`${indent}summarizeTexts[depth=${depth}]: API rejected (context too long), splitting in half`);
+    }
+  } else {
+    console.log(`${indent}summarizeTexts[depth=${depth}]: ${texts.length} texts, ~${estimatedTokens} tokens exceeds limit, splitting in half`);
   }
 
-  // Otherwise summarize each text individually, then combine
-  console.log(
-    "summarizeTexts: exceeds context window, summarizing texts individually"
-  );
-  const summaries = [];
-  for (const text of texts) {
-    const content = template.replaceAll("{text}", text);
+  // Split texts in half and recurse
+  const mid = Math.ceil(texts.length / 2);
+  const left = texts.slice(0, mid);
+  const right = texts.slice(mid);
 
-    console.log(content);
+  const [leftSummary, rightSummary] = await Promise.all([
+    summarizeTextsRecursive(left, template, model, agent, contextLimit, depth + 1),
+    summarizeTextsRecursive(right, template, model, agent, contextLimit, depth + 1),
+  ]);
 
-    const summary = await singlePrompt(content, model, agent).catch((err) => {
-      return `Text of length ${text.length} could not be summarized due to error: ${err.message}`;
-    });
-    summaries.push(summary);
-  }
+  // Combine the two halves with a final summary prompt
+  const combinedSummaries = [leftSummary, rightSummary].join("\n\n");
+  const finalContent = template.replaceAll("{text}", combinedSummaries);
+  const finalEstimate = estimateTokens(finalContent);
+  console.log(`${indent}summarizeTexts[depth=${depth}]: combining halves, ~${finalEstimate} tokens`);
 
-  if (summaries.length === 1) {
-    return summaries[0];
+  if (finalEstimate < contextLimit) {
+    return singlePrompt(finalContent, model, agent);
   }
 
-  // Otherwise form a final summary of the pieces
-  const finalPrompt =
-    `Generate a final output for this prompt ${template} with these incremental summaries: ` +
-    summaries.join("\n\n");
+  // If even the combined summaries are too long, recurse one more level
+  return summarizeTextsRecursive([leftSummary, rightSummary], template, model, agent, contextLimit, depth + 1);
+}
+
+export async function summarizeTexts(
+  texts: string[],
+  template: string,
+  model = "",
+  agent = ""
+) {
+  const effectiveModel = model || Models.openai.GPT_54_Nano;
+  const contextLimit = getModelContextLimit(effectiveModel);
+
+  console.log(
+    `summarizeTexts: ${texts.length} text(s), context limit: ${contextLimit}, model: ${effectiveModel}`
+  );
 
-  const finalSummary = await singlePrompt(finalPrompt, model, agent);
-  return finalSummary;
+  return summarizeTextsRecursive(texts, template, model, agent, contextLimit).catch((err) => {
+    return `Texts of combined length ${texts.reduce((a, t) => a + t.length, 0)} could not be summarized due to error: ${err.message}`;
+  });
 }
 
 export async function chunkText(text: string, chunkSize?: number) {

package/src/chat/CliChatService.ts

@@ -38,7 +38,7 @@ export class CliChatService implements ChatService {
       searchMode: false,
       voiceMode: false,
       multilineMode: false,
-      currentModel: "gpt-4o",
+      currentModel: "gpt-5.4-nano",
       currentProvider: "openai",
       chatHistory: this.chatHistory,
       plugins,

package/src/chat/modules/AgentModule.ts

@@ -517,7 +517,12 @@ export class AgentModule extends BaseChatModule {
 
       // Restore the full message history from the last thread
       const threads = session.threads || [];
-      const lastThread = threads.length > 0 ? threads[threads.length - 1] : [];
+      // Guard against sessions saved with a flat Message[] instead of Message[][]
+      // (a bug where threadUpdate emitted a single thread instead of all threads)
+      const normalizedThreads: Message[][] = threads.length > 0 && !Array.isArray(threads[0])
+        ? [threads as unknown as Message[]]
+        : threads as Message[][];
+      const lastThread = normalizedThreads.length > 0 ? normalizedThreads[normalizedThreads.length - 1] : [];
       const resumeMessages = [...lastThread];
 
       // Append the resume prompt to the last user message (or add a new one)
@@ -701,7 +706,7 @@ export class AgentModule extends BaseChatModule {
 
       // Set up session update listener
       const threadUpdateHandler = async (threadState: any) => {
-        this.updateSession(taskId, threadState);
+        this.updateSession(taskId, agent.getThreads());
         taskInfo.totalCost = agent.getTotalCostUsd();
       };
       agent.agentEvents.on(agent.eventTypes.threadUpdate, threadUpdateHandler);

package/src/chat/modules/SessionsModule.ts

@@ -362,8 +362,47 @@ export class SessionsModule extends BaseChatModule {
     // Check filesystem agent (may have metadata with threads)
     const fsAgentPath = path.join(".knowhow", "processes", "agents", id);
     if (fs.existsSync(fsAgentPath)) {
+      // Try to load threads from metadata.json and resume
+      const metadataPath = path.join(fsAgentPath, "metadata.json");
+      if (fs.existsSync(metadataPath)) {
+        try {
+          const raw = fs.readFileSync(metadataPath, "utf-8");
+          const metadata = JSON.parse(raw);
+          const threads: any[] = metadata.threads || [];
+          const agentName = metadata.agentName || "Developer";
+
+          // Try to get initialInput from the saved session file (more complete)
+          // since metadata.json doesn't always store it
+          const savedSession = sessionManager.loadSession(id);
+          const initialInput = savedSession?.initialInput || metadata.initialInput || metadata.prompt || "";
+
+          console.log(`\n📋 Found task in filesystem: ${id}`);
+          console.log(`   Agent  : ${agentName}`);
+          console.log(`   Task   : ${initialInput}`);
+          console.log(`   Status : ${metadata.status || "unknown"}`);
+
+          const additionalContext = await this.chatService?.getInput(
+            "Add any additional context for resuming this session (or press Enter to skip): "
+          );
+
+          // Normalize threads: if flat Message[] (old buggy format), wrap in array
+          const normalizedThreads = threads.length > 0 && !Array.isArray(threads[0])
+            ? [threads]
+            : threads;
+
+          await this.agentModule.resumeFromMessages({
+            agentName,
+            taskId: id,
+            threads: normalizedThreads,
+            input: additionalContext?.trim() || initialInput || "",
+          });
+          return;
+        } catch (e: any) {
+          console.error(`⚠️  Failed to load metadata for task ${id}: ${e.message}`);
+        }
+      }
       console.log(
-        `⚠️  Task ${id} exists in the filesystem but has no saved session.\n` +
+        `⚠️  Task ${id} exists in the filesystem but has no saved session or metadata.\n` +
           `   Use /attach ${id} if it is still running.`
       );
       return;

package/src/chat/modules/SystemModule.ts

@@ -45,7 +45,7 @@ export class SystemModule extends BaseChatModule {
     const agent = context?.selectedAgent;
     const Clients = agent.clientService;
     const currentProvider = context?.currentProvider || "openai";
-    const currentModel = context?.currentModel || "gpt-4o";
+    const currentModel = context?.currentModel || "gpt-5.4-nano";
 
     const models = Clients.getRegisteredModels(currentProvider);
     console.log(models);
@@ -86,7 +86,7 @@ export class SystemModule extends BaseChatModule {
     const Clients = agent.clientService;
 
     const currentProvider = context?.currentProvider || "openai";
-    const currentModel = context?.currentModel || "gpt-4o";
+    const currentModel = context?.currentModel || "gpt-5.4-nano";
 
     const providers = Object.keys(Clients.clients);
     console.log(providers);

package/src/clients/anthropic.ts

@@ -376,7 +376,7 @@ export class GenericAnthropicClient implements GenericClient {
           tool_choice: { type: "auto" },
           tools,
         }),
-      });
+      }, { signal: options.signal });
 
       if (!response.content || !response.content.length) {
         console.log("no content in Anthropic response", response);

package/src/clients/index.ts

@@ -33,6 +33,7 @@ import { ContextLimits } from "./contextLimits";
 import { OpenAiTextPricing } from "./pricing/openai";
 import { AnthropicTextPricing } from "./pricing/anthropic";
 import { GeminiPricing } from "./pricing/google";
+import { withRetry } from "./withRetry";
 import {
   XaiTextPricing,
   XaiImagePricing,
@@ -665,7 +666,10 @@ export class AIClient {
         } model registered. Try using ${JSON.stringify(this.listAllModels())}`
       );
     }
-    return client.createChatCompletion({ ...options, model });
+    return withRetry(
+      (signal) => client.createChatCompletion({ ...options, model, signal }),
+      options
+    );
   }
 
   async createEmbedding(
@@ -680,7 +684,10 @@ export class AIClient {
         } model registered. Try using ${JSON.stringify(this.listAllModels())}`
       );
     }
-    return client.createEmbedding({ ...options, model });
+    return withRetry(
+      (signal) => client.createEmbedding({ ...options, model, signal }),
+      options
+    );
   }
 
   async createAudioTranscription(
@@ -693,7 +700,10 @@ export class AIClient {
         `Provider ${provider} does not support audio transcription.`
       );
     }
-    return client.createAudioTranscription(options);
+    return withRetry(
+      (signal) => client.createAudioTranscription({ ...options, signal }),
+      options
+    );
   }
 
   async createAudioGeneration(
@@ -711,7 +721,10 @@ export class AIClient {
         `Model ${options.model} not registered for provider ${provider}.`
       );
     }
-    return client.createAudioGeneration({ ...options, model });
+    return withRetry(
+      (signal) => client.createAudioGeneration({ ...options, model, signal }),
+      options
+    );
   }
 
   async createImageGeneration(
@@ -729,7 +742,10 @@ export class AIClient {
         `Model ${options.model} not registered for provider ${provider}.`
       );
     }
-    return client.createImageGeneration({ ...options, model });
+    return withRetry(
+      (signal) => client.createImageGeneration({ ...options, model, signal }),
+      options
+    );
   }
 
   async createVideoGeneration(
@@ -747,7 +763,10 @@ export class AIClient {
         `Model ${options.model} not registered for provider ${provider}.`
       );
     }
-    return client.createVideoGeneration({ ...options, model });
+    return withRetry(
+      (signal) => client.createVideoGeneration({ ...options, model, signal }),
+      options
+    );
   }
 
   async getVideoStatus(

package/src/clients/openai.ts

@@ -63,6 +63,10 @@ export class GenericOpenAiClient implements GenericClient {
     });
   }
 
+  /**
+   * Execute a function with timeout, retries, and exponential backoff.
+   * Retriable errors: 5xx, timeout, ECONNRESET, ETIMEDOUT, rate limits (429).
+   */
   reasoningEffort(
     messages: CompletionOptions["messages"]
   ): "low" | "medium" | "high" {
@@ -155,12 +159,11 @@ export class GenericOpenAiClient implements GenericClient {
         max_completion_tokens: Math.max(options.max_tokens ?? 0, 16_000),
         reasoning_effort: this.resolveReasoningEffort(options),
       }),
-
       ...(options.tools && {
         tools: options.tools,
         tool_choice: "auto",
       }),
-    });
+    }, { signal: options.signal });
 
     const usdCost = this.calculateCost(options.model, response.usage);
 
@@ -453,7 +456,7 @@ export class GenericOpenAiClient implements GenericClient {
       prompt: options.prompt,
       response_format: options.response_format || "verbose_json",
       temperature: options.temperature,
-    });
+    }, { signal: options.signal });
 
     // Calculate cost: $0.006 per minute for Whisper
     const duration = typeof response === "object" && "duration" in response && typeof response.duration === "number"
@@ -489,7 +492,7 @@ export class GenericOpenAiClient implements GenericClient {
       voice: options.voice as any,
       response_format: options.response_format || "mp3",
       speed: options.speed,
-    });
+    }, { signal: options.signal });
 
     const buffer = Buffer.from(await response.arrayBuffer());
 
@@ -518,7 +521,7 @@ export class GenericOpenAiClient implements GenericClient {
       style: options.style,
       response_format: options.response_format,
       user: options.user,
-    });
+    }, { signal: options.signal });
 
     // Cost calculation varies by model and settings
     // DALL-E 3: $0.040-$0.120 per image depending on quality/size

package/src/clients/types.ts

@@ -57,7 +57,30 @@ export interface ToolCall {
   };
 }
 
-export interface CompletionOptions {
+export interface RetryOptions {
+  /**
+   * Request timeout in milliseconds per attempt. If the request does not complete
+   * within this time it is aborted and retried according to maxRetries.
+   */
+  timeout?: number;
+  /**
+   * Maximum number of retry attempts for retriable errors (5xx, timeout, ECONNRESET, 429).
+   * Default: 2. Set to 0 to disable retries.
+   */
+  maxRetries?: number;
+  /**
+   * Base backoff delay in milliseconds for exponential retry backoff.
+   * Default: 1000ms. Each retry waits backoffMs * 2^attempt ms.
+   */
+  backoffMs?: number;
+  /**
+   * Optional external AbortSignal. When the signal is aborted the current
+   * attempt is cancelled immediately and no further retries are made.
+   */
+  signal?: AbortSignal;
+}
+
+export interface CompletionOptions extends RetryOptions {
   model: string;
   messages: Message[];
   tools?: Tool[];
@@ -113,7 +136,7 @@ export interface CompletionResponse {
   usd_cost?: number;
 }
 
-export interface EmbeddingOptions {
+export interface EmbeddingOptions extends RetryOptions {
   input: string;
   model?: string;
 }
@@ -132,7 +155,7 @@ export interface EmbeddingResponse {
   usd_cost?: number;
 }
 
-export interface AudioTranscriptionOptions {
+export interface AudioTranscriptionOptions extends RetryOptions {
   file: Blob | File | any; // Support for Node.js ReadStream or web File/Blob
   model?: string;
   language?: string;
@@ -162,7 +185,7 @@ export interface AudioTranscriptionResponse {
   usd_cost?: number;
 }
 
-export interface AudioGenerationOptions {
+export interface AudioGenerationOptions extends RetryOptions {
   model: string;
   input: string;
   voice: string; // e.g. "alloy", "echo", "fable", "onyx", "nova", "shimmer" for OpenAI; "Kore", "Puck" etc. for Gemini
@@ -176,7 +199,7 @@ export interface AudioGenerationResponse {
   usd_cost?: number;
 }
 
-export interface ImageGenerationOptions {
+export interface ImageGenerationOptions extends RetryOptions {
   model: string;
   prompt: string;
   n?: number;
@@ -197,7 +220,7 @@ export interface ImageGenerationResponse {
   usd_cost?: number;
 }
 
-export interface VideoGenerationOptions {
+export interface VideoGenerationOptions extends RetryOptions {
   model: string;
   prompt: string;
   duration?: number; // seconds

package/src/clients/withRetry.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared retry/timeout helper for all AI clients.
+ *
+ * Executes `fn` with exponential backoff for retriable errors:
+ * - Rate limits (429)
+ * - Timeouts (AbortError, ETIMEDOUT, ECONNRESET)
+ * - Server errors (5xx)
+ *
+ * @param fn               Function to execute. Receives a combined AbortSignal
+ *                         that fires on per-attempt timeout OR external signal abort.
+ * @param opts             Any object with optional RetryOptions fields (timeout, maxRetries,
+ *                         backoffMs, signal). Extra fields are ignored — so you can pass the
+ *                         full options object from any AI method directly.
+ *                         - timeout: Per-attempt timeout in ms. No timeout if omitted.
+ *                         - maxRetries: Max retry attempts after first failure. Default: 2.
+ *                         - backoffMs: Base backoff delay in ms. Default: 1000.
+ *                         - signal: Optional external AbortSignal. When aborted, the current
+ *                         attempt is cancelled and no further retries are made.
+ */
+import type { RetryOptions } from "./types";
+
+export async function withRetry<T>(
+  fn: (signal?: AbortSignal) => Promise<T>,
+  opts: RetryOptions = {}
+): Promise<T> {
+  const maxRetries = opts.maxRetries ?? 2;
+  const backoffMs = opts.backoffMs ?? 1000;
+  const timeout = opts.timeout;
+  const externalSignal = opts.signal;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    // If the external signal is already aborted, bail out immediately.
+    if (externalSignal?.aborted) {
+      throw externalSignal.reason ?? new DOMException("Aborted", "AbortError");
+    }
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    // Combine per-attempt timeout with the external signal into one controller.
+    const controller = timeout || externalSignal ? new AbortController() : undefined;
+
+    if (controller) {
+      if (timeout) {
+        timer = setTimeout(() => controller.abort(new DOMException("Request timed out", "TimeoutError")), timeout);
+      }
+      // Forward external signal abort into our combined controller.
+      if (externalSignal) {
+        const onExternalAbort = () => controller.abort(externalSignal.reason ?? new DOMException("Aborted", "AbortError"));
+        if (externalSignal.aborted) {
+          controller.abort(externalSignal.reason ?? new DOMException("Aborted", "AbortError"));
+        } else {
+          externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+          // Clean up the listener after the attempt resolves/rejects.
+          controller.signal.addEventListener("abort", () =>
+            externalSignal.removeEventListener("abort", onExternalAbort), { once: true }
+          );
+        }
+      }
+    }
+
+    try {
+      const result = await fn(controller?.signal);
+      return result;
+    } catch (err: unknown) {
+      clearTimeout(timer);
+      // If the external signal was aborted, don't retry — propagate immediately.
+      if (externalSignal?.aborted) {
+        throw err;
+      }
+      const errStr = String(err);
+      const isRetriable =
+        errStr.includes('429') ||
+        errStr.includes('timeout') ||
+        errStr.includes('TimeoutError') ||
+        errStr.includes('ECONNRESET') ||
+        errStr.includes('ETIMEDOUT') ||
+        errStr.includes('AbortError') ||
+        /5\d\d/.test(errStr);
+      if (isRetriable && attempt < maxRetries) {
+        const delay = backoffMs * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        continue;
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  throw new Error('withRetry: exhausted retries');
+}