@lobu/worker 7.0.0 → 7.2.0

package/src/openclaw/transcript-snapshot.ts

@@ -0,0 +1,238 @@
+/**
+ * Per-run snapshot client for OpenClaw's `session.jsonl`.
+ *
+ * Why this exists: today's PVC-backed `workspaces/` directory is read-write-
+ * once, which forces the helm chart to pin `replicaCount: 1` for the
+ * gateway/worker. Mirroring the post-run session.jsonl to Postgres lets a
+ * second pod hydrate the file on boot and resume the conversation, which is
+ * the prerequisite for dropping the PVC (Phase 5, separate PR).
+ *
+ * Design contract for the next reader:
+ *   - We do NOT fork or wrap `@mariozechner/pi-coding-agent`'s `SessionManager`.
+ *     It owns the file on disk; we read it back at terminal time and write
+ *     the bytes verbatim to PG. The next boot writes those bytes back to
+ *     disk verbatim before SessionManager.open(), so SessionManager observes
+ *     a byte-identical file to what it last wrote.
+ *   - The snapshot is taken in `OpenClawWorker.cleanup()` on every terminal
+ *     status — `completed`, `failed`, `timeout`, `cancelled`. Hydrate filters
+ *     for `terminal_status='completed'` so a failed run can't poison the
+ *     next worker with a dangling `tool_use` content block. Older completed
+ *     snapshots remain readable; the hydrate query takes the latest one.
+ *   - The worker is sandboxed — no PG access. Two new endpoints live on the
+ *     existing worker gateway: `GET /worker/transcript/snapshot` for
+ *     hydrate, `POST /worker/transcript/snapshot` for write. (org, agent,
+ *     conv) are pulled from the worker JWT on the gateway side, so the
+ *     worker can't impersonate another conversation.
+ *   - Phase 5: snapshot mode is the default. `LOBU_SESSION_STORE=file`
+ *     opts out for legacy/local-dev single-replica deploys. Phase 6
+ *     drops the env var entirely.
+ *
+ * Trade-off accepted: a mid-run crash loses the partial transcript for that
+ * run. The next attempt re-runs from the previous user message. Tools must
+ * be idempotent (or accept user-visible re-execution).
+ */
+
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { createLogger } from "@lobu/core";
+
+const logger = createLogger("transcript-snapshot");
+
+export type TerminalStatus = "completed" | "failed" | "timeout" | "cancelled";
+
+export interface TranscriptSnapshotOptions {
+  /** Absolute path to the session.jsonl SessionManager reads/writes. */
+  sessionFile: string;
+  /** Gateway base URL (e.g. `http://127.0.0.1:8787/lobu`). */
+  gatewayUrl: string;
+  /** Worker JWT. The gateway pulls (org, agent, conv) from this token. */
+  workerToken: string;
+}
+
+/**
+ * Pull the latest `terminal_status='completed'` snapshot for this worker's
+ * (org, agent, conv) and write the bytes to `sessionFile`. Must run BEFORE
+ * SessionManager.open() so the rehydrated content is visible at open time.
+ *
+ * Returns `true` if a snapshot was found and written, `false` if no snapshot
+ * exists yet (first turn). Throws on transport errors — caller decides
+ * whether to fall back to a fresh session.
+ */
+export async function hydrateFromSnapshot(
+  opts: TranscriptSnapshotOptions
+): Promise<boolean> {
+  const url = `${opts.gatewayUrl}/worker/transcript/snapshot`;
+  const res = await fetch(url, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${opts.workerToken}` },
+    signal: AbortSignal.timeout(30_000),
+  });
+
+  // 404 = no completed snapshot for this (org, agent, conv). First turn or
+  // every previous attempt failed/timed out. Caller should start fresh.
+  if (res.status === 404) {
+    return false;
+  }
+  if (!res.ok) {
+    throw new Error(
+      `transcript hydrate failed: ${res.status} ${res.statusText}`
+    );
+  }
+
+  const body = await res.text();
+  await fs.mkdir(path.dirname(opts.sessionFile), { recursive: true });
+  // writeFile truncates atomically (open with O_TRUNC); no partial state
+  // is visible to SessionManager.open() because that call runs after this
+  // function resolves.
+  await fs.writeFile(opts.sessionFile, body, "utf-8");
+  // fsync so a pod crash between this return and SessionManager.open()
+  // doesn't leave the file half-written. The cost is one extra disk flush
+  // on every worker boot — acceptable.
+  const handle = await fs.open(opts.sessionFile, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+
+  logger.info(
+    `Hydrated session file from snapshot: ${body.length} bytes → ${opts.sessionFile}`
+  );
+  return true;
+}
+
+/**
+ * Read the session file in full and POST it to the gateway. Called once per
+ * worker run at terminal time, from `OpenClawWorker.cleanup()`. The
+ * `terminal_status` discriminator lets the hydrate path skip failed/timeout
+ * snapshots so a dangling `tool_use` doesn't poison the next attempt.
+ *
+ * Failure to snapshot is logged but does NOT throw — there's nothing the
+ * caller can do beyond what cleanup already does (the worker is exiting).
+ * The next attempt will hydrate from the previous successful snapshot.
+ */
+export async function writeSnapshot(
+  opts: TranscriptSnapshotOptions & {
+    terminalStatus: TerminalStatus;
+    /**
+     * The runs.id this worker claimed. Sent in the POST body so the route
+     * binds the snapshot to the correct run unambiguously; the route then
+     * verifies the runId actually belongs to the JWT's (org, agent, conv)
+     * tuple before INSERTing. Codex P1#1 on PR #865 — without this, the
+     * route fell back to a "latest run for (org, agent, conv)" lookup
+     * which raced with the next user message enqueuing a fresh run.
+     */
+    runId: number;
+  }
+): Promise<void> {
+  // Hydrate filters `terminal_status='completed'` — failed/timeout/cancelled
+  // snapshots are never used. POSTing them is pure network waste; the
+  // route would store them but no future hydrate would pick them up.
+  // Skip at the source so any caller (cleanup() today, future paths
+  // tomorrow) stays out of the wasteful write. Codex round 2 quality
+  // win C on PR #865.
+  if (opts.terminalStatus !== "completed") {
+    logger.debug(
+      `Skipping snapshot POST: terminal_status='${opts.terminalStatus}' is never read by hydrate`
+    );
+    return;
+  }
+
+  let body: string;
+  try {
+    body = await fs.readFile(opts.sessionFile, "utf-8");
+  } catch (err) {
+    // No session file = nothing to snapshot. Common when the worker exits
+    // before SessionManager.open() ran (early error path).
+    const isMissing =
+      err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT";
+    if (isMissing) {
+      logger.debug(`No session file at ${opts.sessionFile}; skipping snapshot`);
+      return;
+    }
+    logger.warn(
+      `Failed to read session file for snapshot: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return;
+  }
+
+  if (body.length === 0) {
+    logger.debug("Empty session file; skipping snapshot");
+    return;
+  }
+
+  const url = `${opts.gatewayUrl}/worker/transcript/snapshot`;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${opts.workerToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        terminalStatus: opts.terminalStatus,
+        snapshotJsonl: body,
+        runId: opts.runId,
+      }),
+      // Snapshots can be large (633 KB max measured); 60s timeout covers
+      // slow links + PG TOAST writes.
+      signal: AbortSignal.timeout(60_000),
+    });
+    if (!res.ok) {
+      // 409 = UNIQUE (org, agent, conv, run_id) collision. Means another
+      // pod (or a retry) already wrote this snapshot — benign, drop it.
+      if (res.status === 409) {
+        logger.info(
+          `Snapshot for run already exists (status=${opts.terminalStatus}); skipping duplicate`
+        );
+        return;
+      }
+      logger.error(`Snapshot POST failed: ${res.status} ${res.statusText}`);
+      return;
+    }
+    logger.info(
+      `Wrote snapshot: ${body.length} bytes, status=${opts.terminalStatus}`
+    );
+  } catch (err) {
+    logger.error(
+      `Snapshot POST threw: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return;
+  }
+}
+
+/**
+ * Purge all snapshot rows for this worker's (org, agent, conv). Called
+ * by the session-reset path so the next boot doesn't rehydrate the
+ * conversation from Postgres after a `/new`. Idempotent — a 404 / empty
+ * result is treated as success.
+ *
+ * Failures are logged but not thrown — reset is best-effort; if the
+ * purge HTTP call fails the worst case is the next boot hydrates from
+ * the previous transcript (the legacy file-mode behaviour). The local
+ * session.jsonl unlink is the primary signal; this is the multi-replica
+ * complement to it.
+ */
+export async function clearSnapshots(
+  opts: Pick<TranscriptSnapshotOptions, "gatewayUrl" | "workerToken">
+): Promise<void> {
+  const url = `${opts.gatewayUrl}/worker/transcript/snapshot`;
+  try {
+    const res = await fetch(url, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${opts.workerToken}` },
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok) {
+      logger.warn(
+        `Snapshot DELETE failed: ${res.status} ${res.statusText} — next boot may rehydrate stale history`
+      );
+      return;
+    }
+    logger.info("Purged conversation snapshots for session reset");
+  } catch (err) {
+    logger.warn(
+      `Snapshot DELETE threw: ${err instanceof Error ? err.message : String(err)} — next boot may rehydrate stale history`
+    );
+  }
+}

package/src/openclaw/worker.ts

@@ -54,6 +54,12 @@ import {
   resolveModelRef,
 } from "./model-resolver";
 import { checkSandboxLeak } from "./sandbox-leak";
+import {
+  clearSnapshots,
+  hydrateFromSnapshot,
+  type TerminalStatus,
+  writeSnapshot,
+} from "./transcript-snapshot";
 import {
   loadPlugins,
   runPluginHooks,
@@ -275,28 +281,40 @@ export class OpenClawWorker implements WorkerExecutor {
   public workerTransport: WorkerTransport;
   private config: WorkerConfig;
   private progressProcessor: OpenClawProgressProcessor;
+  /**
+   * Terminal status for the current run, used by `cleanup()` to discriminate
+   * the snapshot row. Defaults to `failed` (pessimistic) so an early crash
+   * before any return-path assignment is recorded as a failure, not silently
+   * accepted as a completion. Set to `completed` only on the success path
+   * in `execute()`. Resets on every `execute()` invocation.
+   */
+  private terminalStatus: TerminalStatus = "failed";
+  /**
+   * Path to the OpenClaw session file for the current run. Captured in
+   * `runAISession()` (where SessionManager opens it) so `cleanup()` can
+   * read it back for the snapshot without re-deriving the path.
+   */
+  private sessionFilePath: string | null = null;
 
   constructor(config: WorkerConfig) {
     this.config = config;
     this.workspaceManager = new WorkspaceManager(config.workspace);
     this.progressProcessor = new OpenClawProgressProcessor();
 
-    // Verify required environment variables
     const gatewayUrl = process.env.DISPATCHER_URL;
     const workerToken = process.env.WORKER_TOKEN;
-
     if (!gatewayUrl || !workerToken) {
       throw new Error(
         "DISPATCHER_URL and WORKER_TOKEN environment variables are required"
       );
     }
-
     if (!config.teamId) {
       throw new Error("teamId is required for worker initialization");
     }
     if (!config.conversationId) {
       throw new Error("conversationId is required for worker initialization");
     }
+
     this.workerTransport = new HttpWorkerTransport({
       gatewayUrl,
       workerToken,
@@ -316,6 +334,33 @@ export class OpenClawWorker implements WorkerExecutor {
    */
   async execute(): Promise<void> {
     const executeStartTime = Date.now();
+    // Reset terminal status for this run. Defaults to `failed` (pessimistic);
+    // assigned to `completed` only on the success path below. SESSION_TIMEOUT
+    // throws and is reassigned in the catch block.
+    this.terminalStatus = "failed";
+
+    // Fail loud when snapshot mode is enabled but the per-run scope the
+    // gateway is supposed to provide hasn't reached this job. A silent
+    // skip in cleanup() would hide a configuration bug across many
+    // turns; throwing here surfaces it on the first turn and the runs
+    // queue's retry path handles re-delivery. Codex round 2 quality
+    // win D on PR #865.
+    //
+    // Phase 5: snapshot is the default; setting LOBU_SESSION_STORE=file
+    // opts out (legacy / local-dev path that keeps reading session.jsonl
+    // straight off disk without writing to Postgres).
+    if (process.env.LOBU_SESSION_STORE !== "file") {
+      if (typeof this.config.runId !== "number") {
+        throw new Error(
+          "Snapshot mode (LOBU_SESSION_STORE != 'file') but WorkerConfig.runId is missing — runs-queue dispatch did not stamp runId on the job payload"
+        );
+      }
+      if (!this.config.runJobToken) {
+        throw new Error(
+          "Snapshot mode (LOBU_SESSION_STORE != 'file') but WorkerConfig.runJobToken is missing — MessageConsumer did not mint a per-run worker token"
+        );
+      }
+    }
 
     try {
       this.progressProcessor.reset();
@@ -327,13 +372,11 @@ export class OpenClawWorker implements WorkerExecutor {
         `[TIMING] Worker execute() started at: ${new Date(executeStartTime).toISOString()}`
       );
 
-      // Decode user prompt
       const userPrompt = Buffer.from(this.config.userPrompt, "base64").toString(
         "utf-8"
       );
       logger.info(`User prompt: ${userPrompt.substring(0, 100)}...`);
 
-      // Setup workspace
       logger.info("Setting up workspace...");
 
       await Sentry.startSpan(
@@ -360,13 +403,9 @@ export class OpenClawWorker implements WorkerExecutor {
         }
       );
 
-      // Setup I/O directories for file handling
       await this.setupIODirectories();
-
-      // Download input files if any
       await this.downloadInputFiles();
 
-      // Generate custom instructions
       let customInstructions = await generateCustomInstructions(
         [
           new OpenClawCoreInstructionProvider(),
@@ -385,7 +424,7 @@ export class OpenClawWorker implements WorkerExecutor {
         }
       );
 
-      // Call module onSessionStart hooks to allow modules to modify system prompt
+      // Module hooks may modify the system prompt before agent execution.
       try {
         const { onSessionStart } = await import("../modules/lifecycle");
         const moduleContext = await onSessionStart({
@@ -407,7 +446,6 @@ export class OpenClawWorker implements WorkerExecutor {
       // Add file I/O instructions AFTER module hooks so they aren't overwritten
       customInstructions += this.getFileIOInstructions();
 
-      // Execute AI session
       logger.info(
         `[TIMING] Starting OpenClaw session at: ${new Date().toISOString()}`
       );
@@ -468,7 +506,6 @@ export class OpenClawWorker implements WorkerExecutor {
         }
       );
 
-      // Collect module data before sending final response
       const { collectModuleData } = await import("../modules/lifecycle");
       const moduleData = await collectModuleData({
         workspaceDir: this.workspaceManager.getCurrentWorkingDirectory(),
@@ -477,8 +514,11 @@ export class OpenClawWorker implements WorkerExecutor {
       });
       this.workerTransport.setModuleData(moduleData);
 
-      // Handle result
       if (result.success) {
+        // Snapshot writer in cleanup() reads this to discriminate the row.
+        // Hydrate skips non-completed snapshots, so getting this right is
+        // what stops a failed turn from poisoning the next attempt.
+        this.terminalStatus = "completed";
         const outputSnapshot = this.progressProcessor.getOutputSnapshot();
         const hintGatewayUrl = process.env.DISPATCHER_URL;
         const hintWorkerToken = process.env.WORKER_TOKEN;
@@ -532,6 +572,12 @@ export class OpenClawWorker implements WorkerExecutor {
         const isTimeout = result.exitCode === 124;
 
         if (isTimeout) {
+          // Mark the snapshot as `timeout` instead of `failed` so operators
+          // can distinguish runaway agents from genuine failures in the
+          // dashboard. The catch block below sees `SESSION_TIMEOUT` and
+          // keeps this assignment intact (it only forces `failed` on
+          // exceptions that aren't already marked).
+          this.terminalStatus = "timeout";
           logger.info(
             `Session timed out (exit code 124) - will be retried automatically, not showing error to user`
           );
@@ -562,6 +608,55 @@ export class OpenClawWorker implements WorkerExecutor {
   }
 
   async cleanup(): Promise<void> {
+    // Snapshot the post-run session.jsonl to Postgres so the next worker
+    // (possibly on a different pod) can hydrate from it. Hydrate filters
+    // `terminal_status='completed'`, so we ONLY POST on the success path
+    // — writing `failed`/`timeout`/`cancelled` rows is pure network
+    // waste (codex round 2 quality win C on PR #865). Default-on in
+    // Phase 5; LOBU_SESSION_STORE=file opts out for legacy/local-dev.
+    //
+    // The runs queue has already moved this run to a terminal state by
+    // the time cleanup() fires (sse-client.ts:865 finally block runs
+    // after execute() returns). We POST in the worker's own dying
+    // breath; the gateway-side advisory lock held by the spawner is
+    // released when the subprocess exits, so by the next claim's boot
+    // this snapshot is the visible "latest" row.
+    if (
+      process.env.LOBU_SESSION_STORE !== "file" &&
+      this.sessionFilePath &&
+      this.terminalStatus === "completed"
+    ) {
+      const gatewayUrl = process.env.DISPATCHER_URL;
+      const runId = this.config.runId;
+      // Per-run JWT minted by the gateway's MessageConsumer alongside
+      // `runId`. The snapshot route requires `tokenData.runId ===
+      // body.runId`, so the deployment-lifetime WORKER_TOKEN cannot be
+      // used here — it would carry no `runId` and the route would 403.
+      // Codex round 2 finding A.
+      const runJobToken = this.config.runJobToken;
+      if (gatewayUrl && runJobToken && typeof runId === "number") {
+        await writeSnapshot({
+          sessionFile: this.sessionFilePath,
+          gatewayUrl,
+          workerToken: runJobToken,
+          terminalStatus: this.terminalStatus,
+          runId,
+        });
+      } else if (gatewayUrl) {
+        // Missing per-run scope (legacy direct-enqueue path or token
+        // mint failure on the gateway). Skip the snapshot rather than
+        // risk a mis-attributed row; the next run will hydrate from
+        // the previous completed snapshot the next time a normal
+        // runs-queue dispatch comes through.
+        logger.warn(
+          `Skipping transcript snapshot: ${
+            typeof runId !== "number"
+              ? "WorkerConfig.runId is missing"
+              : "WorkerConfig.runJobToken is missing"
+          } (legacy enqueue path)`
+        );
+      }
+    }
     logger.info("Worker cleanup completed");
   }
 
@@ -866,12 +961,56 @@ export class OpenClawWorker implements WorkerExecutor {
     await fs.mkdir(path.join(workspaceDir, ".openclaw"), { recursive: true });
 
     const sessionFile = path.join(workspaceDir, ".openclaw", "session.jsonl");
+    // Capture for cleanup() — it reads the file back to write the snapshot
+    // at terminal time. Set unconditionally so file-mode opt-outs
+    // still get a defined value (snapshot writer no-ops when
+    // LOBU_SESSION_STORE=file).
+    this.sessionFilePath = sessionFile;
     const providerStateFile = path.join(
       workspaceDir,
       ".openclaw",
       "provider.json"
     );
 
+    // Hydrate from the latest completed Postgres snapshot BEFORE the
+    // provider-state check or SessionManager.open(). Phase 5: snapshot
+    // mode is the default; LOBU_SESSION_STORE=file opts out and keeps
+    // the legacy file-only behaviour for local-dev / single-replica
+    // self-hosters.
+    //
+    // Order matters: hydrate → provider check (may unlink) →
+    // SessionManager.open(). The provider-change unlink at line ~925 still
+    // does the right thing after hydrate: it drops the file we just wrote
+    // and SessionManager creates a fresh one, exactly like a first-turn
+    // boot. The next snapshot will have its own run_id, so the historical
+    // PG rows remain readable without poisoning the new conversation
+    // (hydrate would only resurrect them if a subsequent run completes
+    // successfully and overwrites the latest pointer).
+    if (process.env.LOBU_SESSION_STORE !== "file") {
+      const gatewayUrl = process.env.DISPATCHER_URL;
+      const workerToken = process.env.WORKER_TOKEN;
+      if (gatewayUrl && workerToken) {
+        try {
+          await hydrateFromSnapshot({
+            sessionFile,
+            gatewayUrl,
+            workerToken,
+          });
+        } catch (err) {
+          // Hydrate failure is non-fatal — fall back to whatever's on disk.
+          // Worst case the worker boots without history and the user re-
+          // grounds the conversation. Better than refusing to start.
+          logger.warn(
+            `Snapshot hydrate failed; continuing with local session file: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      } else {
+        logger.warn(
+          "Snapshot mode active (LOBU_SESSION_STORE != 'file') but DISPATCHER_URL or WORKER_TOKEN missing; snapshot disabled"
+        );
+      }
+    }
+
     // Detect provider change and reset session if needed
     let sessionSummary: string | undefined;
     try {
@@ -1412,6 +1551,21 @@ Use it when the user references past discussions or you need context.`);
           // File may not exist
         }
 
+        // Also purge the Postgres snapshots for this (org, agent, conv)
+        // — in snapshot mode (the Phase 5 default) the next worker boot
+        // would otherwise rehydrate from the now-flushed conversation
+        // and the user-visible "Starting fresh" would be a lie. Best-
+        // effort: a failure here is logged but doesn't block the reset
+        // since the local unlink already happened and the snapshot
+        // helper is a no-op in file mode.
+        if (process.env.LOBU_SESSION_STORE !== "file") {
+          const gatewayUrl = process.env.DISPATCHER_URL;
+          const workerToken = process.env.WORKER_TOKEN;
+          if (gatewayUrl && workerToken) {
+            await clearSnapshots({ gatewayUrl, workerToken });
+          }
+        }
+
         // Send visible confirmation to user
         await onProgress({
           type: "output",

package/src/server.ts

@@ -3,7 +3,7 @@
  * Lightweight Hono server started before SSE gateway connection.
  */
 
-import { readFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import { createServer } from "node:http";
 import { join } from "node:path";
 import { getRequestListener } from "@hono/node-server";
@@ -20,7 +20,6 @@ const logger = createLogger("worker-http");
 const app = new Hono();
 
 async function findSessionFile(): Promise<string | null> {
-  const { readdir, stat } = await import("node:fs/promises");
   const workspaceDir = getOptionalEnv("WORKSPACE_DIR", "/workspace");
 
   // Direct path: {WORKSPACE_DIR}/.openclaw/session.jsonl
@@ -163,10 +162,8 @@ function entryToMessage(entry: SessionEntry): ParsedMessage | null {
   return null;
 }
 
-// Health check
 app.get("/health", (c) => c.json({ status: "ok" }));
 
-// Full session messages with cursor-based pagination
 app.get("/session/messages", async (c) => {
   const cursor = c.req.query("cursor");
   const limit = Math.min(parseInt(c.req.query("limit") || "50", 10), 200);
@@ -230,7 +227,6 @@ app.get("/session/messages", async (c) => {
   }
 });
 
-// Session stats
 app.get("/session/stats", async (c) => {
   try {
     const sessionPath = await findSessionFile();

package/src/shared/audio-provider-suggestions.ts

@@ -5,11 +5,7 @@ interface AudioProviderSuggestions {
   usedFallback: boolean;
 }
 
-const FALLBACK_PROVIDER_ENTRIES = [
-  { id: "chatgpt" },
-  { id: "gemini" },
-  { id: "elevenlabs" },
-] as const;
+const FALLBACK_PROVIDER_IDS = ["chatgpt", "gemini", "elevenlabs"] as const;
 
 const KNOWN_PROVIDER_LABELS: Record<string, string> = {
   chatgpt: "ChatGPT/OpenAI",
@@ -48,7 +44,7 @@ function getFallbackSuggestions(
   available: boolean | null
 ): AudioProviderSuggestions {
   return {
-    providerIds: FALLBACK_PROVIDER_ENTRIES.map((entry) => entry.id),
+    providerIds: [...FALLBACK_PROVIDER_IDS],
     providerDisplayList: "",
     available,
     usedFallback: true,
@@ -119,6 +115,8 @@ export async function fetchAudioProviderSuggestions(params: {
       `${params.gatewayUrl}/internal/audio/capabilities`,
       {
         headers: { Authorization: `Bearer ${params.workerToken}` },
+        // Capability probing is best-effort; never block the agent turn on it.
+        signal: AbortSignal.timeout(15_000),
       }
     );
     if (!response.ok) {