@vellumai/assistant 0.8.7 → 0.8.8

package/src/daemon/orphan-reaper.ts

@@ -0,0 +1,240 @@
+/**
+ * Periodic reaper for orphaned subprocesses that reparent to the daemon.
+ *
+ * Tools run commands in their own process group (`detached: true`) and, on
+ * timeout/abort, group-kill with `process.kill(-pgid, SIGKILL)` (the bash and
+ * host_bash tools, the skill sandbox runner, and the debug-bash route). The
+ * immediate child is reaped by Bun/libuv, but its descendants — e.g. git's
+ * transport helpers or a skill runner's `bun` process — were never spawned by
+ * the daemon, so when the group dies they reparent to PID 1. When the daemon
+ * runs as PID 1 in a container, Bun is not an init: it never calls `waitpid()`
+ * on those reparented orphans, so they accumulate as `<defunct>` entries that
+ * consume PID slots until the container is recycled.
+ *
+ * This reaper scans `/proc` for zombie children of the daemon and reaps each
+ * by **specific PID** with `WNOHANG`. It deliberately does NOT use
+ * `waitpid(-1)`: libuv reaps the children it spawned by specific PID on
+ * `SIGCHLD`, and a blanket `waitpid(-1)` would race libuv and could swallow a
+ * tracked child's exit status — libuv's own source handles the lost race by
+ * dropping the exit callback ("someone else stole the waitpid from us. Handle
+ * this by not handling it at all."). To stay clear of that race we only reap a
+ * zombie after it has survived at least one scan interval: libuv reaps its own
+ * within milliseconds of `SIGCHLD`, so anything still defunct a full interval
+ * later is a genuine orphan libuv is not tracking.
+ *
+ * The reaper is a no-op unless the daemon is PID 1 on Linux. Off PID 1 (local
+ * macOS dev, or if an init such as tini is ever placed above the daemon),
+ * orphans reparent to that init and are reaped there, so there is nothing for
+ * this to do. Because the daemon is PID 1, orphans already reparent to it and
+ * `PR_SET_CHILD_SUBREAPER` is unnecessary. It is additionally gated behind the
+ * `daemon.reapOrphanedSubprocesses` config flag (default off) so the behavior
+ * can be enabled per workspace for validation before becoming the default.
+ *
+ * References:
+ * - libuv reaps its own children by pid on SIGCHLD (`uv__wait_children`):
+ *   https://github.com/nodejs/node/blob/main/deps/uv/src/unix/process.c
+ * - Subreaper reaping pattern for runtimes embedding libuv (specific-pid +
+ *   WNOHANG, never `waitpid(-1)`, grace window for libuv co-existence):
+ *   https://github.com/coopergwrenn/prctl-subreaper
+ * - waitpid(2): https://man7.org/linux/man-pages/man2/waitpid.2.html
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { dlopen, FFIType, ptr } from "bun:ffi";
+
+import { getConfigReadOnly } from "../config/loader.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("orphan-reaper");
+
+/** Linux `WNOHANG` — return immediately if no child has changed state. */
+const WNOHANG = 1;
+
+const SCAN_INTERVAL_MS = 60_000;
+
+let scanTimer: ReturnType<typeof setInterval> | null = null;
+
+/** Zombie child PIDs observed on the previous scan (the grace set). */
+let seenLastScan: Set<number> = new Set();
+
+type WaitpidFn = (pid: number, statusPtr: unknown, options: number) => number;
+
+let waitpid: WaitpidFn | null = null;
+// Held at module scope so the backing buffer is not GC'd while `waitStatusPtr`
+// keeps only a raw pointer into it (waitpid writes the exit status here).
+let waitStatusBuf: Int32Array | null = null;
+let waitStatusPtr: unknown = null;
+
+/**
+ * Bind libc `waitpid` via FFI. Returns false (and disables the reaper) if FFI
+ * is unavailable so daemon startup never fails on this subsystem.
+ */
+function initWaitpid(): boolean {
+  if (waitpid) return true;
+  try {
+    const lib = dlopen("libc.so.6", {
+      waitpid: {
+        args: [FFIType.i32, FFIType.ptr, FFIType.i32],
+        returns: FFIType.i32,
+      },
+    });
+    // Reusable out-param buffer for the wstatus we don't inspect.
+    waitStatusBuf = new Int32Array(1);
+    waitStatusPtr = ptr(waitStatusBuf);
+    waitpid = lib.symbols.waitpid as unknown as WaitpidFn;
+    return true;
+  } catch (err) {
+    log.warn(
+      { err },
+      "Orphan reaper unavailable: failed to bind libc waitpid via FFI",
+    );
+    return false;
+  }
+}
+
+export interface ZombieChild {
+  pid: number;
+  comm: string;
+}
+
+/**
+ * Parse a `/proc/<pid>/stat` line into its leading fields. `comm` (the
+ * executable name) may itself contain spaces and parentheses, so the fixed
+ * fields are read relative to the final `)` rather than by naive splitting.
+ * Returns null if the line is malformed.
+ */
+export function parseProcStat(
+  content: string,
+): { comm: string; state: string; ppid: number } | null {
+  const lparen = content.indexOf("(");
+  const rparen = content.lastIndexOf(")");
+  if (lparen === -1 || rparen === -1 || rparen < lparen) return null;
+  const comm = content.slice(lparen + 1, rparen);
+  const rest = content.slice(rparen + 2).split(" ");
+  const state = rest[0];
+  const ppid = Number(rest[1]);
+  if (!state || !Number.isInteger(ppid)) return null;
+  return { comm, state, ppid };
+}
+
+/**
+ * Given the zombie child PIDs seen this scan and those seen on the previous
+ * scan, decide which to reap now. A zombie is only reaped once it has
+ * survived a full interval (present in `seenLast`), leaving newly-defunct
+ * children for libuv to reap first. Returns the PIDs to reap and the set to
+ * carry into the next scan.
+ */
+export function selectReapable(
+  current: number[],
+  seenLast: Set<number>,
+): { reap: number[]; nextSeen: Set<number> } {
+  const reap = current.filter((pid) => seenLast.has(pid));
+  return { reap, nextSeen: new Set(current) };
+}
+
+/**
+ * Scan `/proc` for zombie (`Z`) processes whose parent is this daemon.
+ * Reparented orphans keep their original process group but their parent
+ * becomes PID 1 (the daemon), so they appear here once defunct.
+ */
+function findZombieChildren(): ZombieChild[] {
+  const selfPid = process.pid;
+  const zombies: ZombieChild[] = [];
+  let entries: string[];
+  try {
+    entries = readdirSync("/proc");
+  } catch {
+    return zombies;
+  }
+  for (const entry of entries) {
+    const pid = Number(entry);
+    if (!Number.isInteger(pid) || pid <= 1) continue;
+    let stat: string;
+    try {
+      stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    } catch {
+      // Process exited between readdir and read — skip.
+      continue;
+    }
+    const parsed = parseProcStat(stat);
+    if (parsed && parsed.state === "Z" && parsed.ppid === selfPid) {
+      zombies.push({ pid, comm: parsed.comm });
+    }
+  }
+  return zombies;
+}
+
+/**
+ * Reap zombie children that have persisted for at least one scan interval,
+ * leaving newly-defunct children for libuv to reap first.
+ */
+function reapScan(): void {
+  if (!waitpid) return;
+  const zombies = findZombieChildren();
+  const byPid = new Map(zombies.map((z) => [z.pid, z]));
+  const { reap, nextSeen } = selectReapable([...byPid.keys()], seenLastScan);
+  const reaped: ZombieChild[] = [];
+  for (const pid of reap) {
+    const rc = waitpid(pid, waitStatusPtr, WNOHANG);
+    // rc > 0: reaped. rc <= 0 (0 = not yet, -1 = ECHILD/raced): leave it.
+    if (rc > 0) reaped.push(byPid.get(pid)!);
+  }
+  seenLastScan = nextSeen;
+  if (reaped.length > 0) {
+    log.info(
+      {
+        count: reaped.length,
+        pids: reaped.map((z) => z.pid),
+        comms: reaped.map((z) => z.comm),
+      },
+      "Reaped orphaned subprocesses reparented to the daemon (PID 1)",
+    );
+  }
+}
+
+/**
+ * Read the opt-in gate from workspace config (`daemon.reapOrphanedSubprocesses`),
+ * tolerating a missing or malformed config so startup never fails on it.
+ */
+function isReaperEnabled(): boolean {
+  try {
+    return getConfigReadOnly().daemon.reapOrphanedSubprocesses;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Start the periodic orphan reaper. No-op unless the daemon is PID 1 on Linux
+ * (otherwise reparented orphans are reaped by the real init) and the
+ * `daemon.reapOrphanedSubprocesses` config gate is enabled.
+ */
+export function startOrphanReaper(): void {
+  if (scanTimer) return;
+  if (process.platform !== "linux" || process.pid !== 1) {
+    log.info(
+      { platform: process.platform, pid: process.pid },
+      "Orphan reaper not started: daemon is not PID 1 on Linux",
+    );
+    return;
+  }
+  if (!isReaperEnabled()) {
+    log.info(
+      "Orphan reaper not started: daemon.reapOrphanedSubprocesses is disabled",
+    );
+    return;
+  }
+  if (!initWaitpid()) return;
+  seenLastScan = new Set();
+  scanTimer = setInterval(reapScan, SCAN_INTERVAL_MS);
+  scanTimer.unref?.();
+  log.info({ intervalMs: SCAN_INTERVAL_MS }, "Orphan reaper started");
+}
+
+export function stopOrphanReaper(): void {
+  if (scanTimer) {
+    clearInterval(scanTimer);
+    scanTimer = null;
+  }
+  seenLastScan = new Set();
+}

package/src/daemon/persist-unsendable-image.ts

@@ -0,0 +1,117 @@
+/**
+ * Persistence for the image-too-large recovery path.
+ *
+ * When the provider rejects a turn because an attached image exceeds its
+ * limits, the agent loop downgrades the offending image blocks in memory and
+ * retries. That transformation is transient — the stored message row keeps the
+ * full-size image block, so the rejected image is rehydrated on every later
+ * turn and keeps re-entering the model's context. This module makes the
+ * downgrade durable for images that can *never* be transmitted, so a rejected
+ * upload cannot resurface after the user re-uploads a smaller version.
+ */
+
+import { optimizeImageForTransport } from "../agent/image-optimize.js";
+import { parseImageDimensions } from "../context/image-dimensions.js";
+import {
+  getMessages,
+  updateMessageContent,
+} from "../memory/conversation-crud.js";
+import type { ContentBlock } from "../providers/types.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("persist-unsendable-image");
+
+// Anthropic rejects any image whose longest side exceeds this many pixels,
+// regardless of payload size. Mirrors the user-facing message surfaced by
+// `classifyConversationError` for the IMAGE_TOO_LARGE code.
+// https://docs.anthropic.com/en/docs/build-with-claude/vision#image-size
+const PROVIDER_MAX_IMAGE_DIMENSION = 8000;
+
+// Anthropic rejects any single image whose base64 payload exceeds 5 MB.
+// https://docs.anthropic.com/en/docs/build-with-claude/vision#image-size
+const PROVIDER_MAX_IMAGE_PAYLOAD_BYTES = 5 * 1024 * 1024;
+
+/**
+ * Note left in place of an image that cannot be sent to the provider. Shared
+ * with the in-memory recovery path so the persisted history matches what the
+ * model saw on the turn the image was rejected.
+ */
+export const UNSENDABLE_IMAGE_NOTE =
+  "(An image was attached but could not be sent — its dimensions exceed the provider limit and automatic resize was not available. Please resize the image and try again.)";
+
+/**
+ * True when a stored image block can never be transmitted to the provider: it
+ * violates a provider hard limit (per-side pixel cap or payload size) and
+ * cannot be shrunk to fit (re-optimization is a no-op).
+ *
+ * Stored blocks are already post-optimization, so a block that is still
+ * oversized here only stays oversized because resizing is unavailable on this
+ * host (e.g. `sips` is absent off macOS, or the format is unsupported). A
+ * downscalable image would have been reduced at upload time and would not reach
+ * this predicate, so it is left untouched.
+ */
+function isImagePermanentlyUnsendable(
+  block: Extract<ContentBlock, { type: "image" }>,
+): boolean {
+  const payloadBytes = block.source.data.length;
+  const dims = parseImageDimensions(block.source.data, block.source.media_type);
+  const exceedsDimensionCap =
+    dims != null &&
+    (dims.width > PROVIDER_MAX_IMAGE_DIMENSION ||
+      dims.height > PROVIDER_MAX_IMAGE_DIMENSION);
+  const exceedsPayloadCap = payloadBytes > PROVIDER_MAX_IMAGE_PAYLOAD_BYTES;
+  if (!exceedsDimensionCap && !exceedsPayloadCap) return false;
+
+  const optimized = optimizeImageForTransport(
+    block.source.data,
+    block.source.media_type,
+  );
+  return optimized.data === block.source.data;
+}
+
+/**
+ * Rewrite every stored message in a conversation that holds a permanently
+ * unsendable image, replacing those image blocks with {@link
+ * UNSENDABLE_IMAGE_NOTE}. Reads stored content directly (not the in-memory,
+ * injection-enriched copy) so injected prefixes and hydrated source paths are
+ * never written back.
+ *
+ * Idempotent: once an image is replaced by the note there is no image block
+ * left to match, so re-running is a no-op. Returns the number of rewritten
+ * messages.
+ */
+export function persistUnsendableImageDowngrades(
+  conversationId: string,
+): number {
+  let rewritten = 0;
+  for (const row of getMessages(conversationId)) {
+    // Cheap prefilter — JSON.stringify emits no spaces, so an image block
+    // always serializes with this exact substring.
+    if (!row.content.includes('"type":"image"')) continue;
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(row.content);
+    } catch {
+      continue;
+    }
+    if (!Array.isArray(parsed)) continue;
+
+    let changed = false;
+    const next = (parsed as ContentBlock[]).map((block): ContentBlock => {
+      if (block.type !== "image") return block;
+      if (!isImagePermanentlyUnsendable(block)) return block;
+      changed = true;
+      return { type: "text", text: UNSENDABLE_IMAGE_NOTE };
+    });
+    if (!changed) continue;
+
+    updateMessageContent(row.id, JSON.stringify(next));
+    rewritten++;
+    log.info(
+      { conversationId, messageId: row.id },
+      "Persisted unsendable-image downgrade so it cannot resurface on later turns",
+    );
+  }
+  return rewritten;
+}

package/src/daemon/process-message.ts

@@ -437,9 +437,7 @@ export async function processMessage(
     conversation.getMessages().push(cleanMsg);
 
     conversation.emitActivityState("thinking", "context_compacting");
-    const result = await conversation.forceCompact({
-      targetInputTokensOverride: slashResult.targetInputTokensOverride,
-    });
+    const result = await conversation.forceCompact();
     const responseText = formatCompactResult(result);
     const assistantMsg = createAssistantMessage(responseText);
     const persistedAssistant = await addMessage(

package/src/daemon/trace-emitter.ts

@@ -1,14 +1,16 @@
 import { v4 as uuid } from "uuid";
 
+import type {
+  TraceEvent,
+  TraceEventKind,
+  TraceEventStatus,
+} from "../api/events/trace-event.js";
 import {
   getMaxSequence,
   persistTraceEvent,
 } from "../memory/trace-event-store.js";
 import { getLogger } from "../util/logger.js";
-import type { ServerMessage, TraceEventKind } from "./message-protocol.js";
-import type { TraceEvent } from "./message-types/messages.js";
-
-export type TraceEventStatus = "info" | "success" | "warning" | "error";
+import type { ServerMessage } from "./message-protocol.js";
 
 const log = getLogger("trace-emitter");
 

package/src/daemon/trust-context.ts

@@ -5,6 +5,8 @@
  * imports (memory/conversation-crud → daemon/conversation-runtime-assembly).
  */
 import type { ChannelId } from "../channels/types.js";
+import { isHttpAuthDisabled } from "../config/env.js";
+import type { TrustClass } from "../runtime/actor-trust-resolver.js";
 
 export interface TrustContext {
   /** Channel through which the inbound message arrived. */
@@ -62,3 +64,20 @@ export const FALLBACK_TURN_TRUST: TrustContext = {
   sourceChannel: "vellum",
   trustClass: "unknown",
 };
+
+/**
+ * Resolve the effective trust class for an actor.
+ *
+ * When HTTP auth is disabled (dev bypass), always returns `'guardian'`
+ * so that control-plane gates don't block local development.
+ *
+ * When no trust context is available (e.g. desktop-only conversations that
+ * don't go through channel trust resolution), defaults to `'unknown'`
+ * to fail-closed.
+ */
+export function resolveTrustClass(
+  trustContext: TrustContext | undefined,
+): TrustClass {
+  if (isHttpAuthDisabled()) return "guardian";
+  return trustContext?.trustClass ?? "unknown";
+}

package/src/daemon/wake-target-adapter.ts

@@ -140,6 +140,8 @@ function translateAgentEventToServerMessage(
     case "context_compacting":
     case "compaction_circuit_open":
     case "compaction_circuit_closed":
+    case "compaction_completed":
+    case "history_stripped":
     case "agent_loop_exit":
       return null;
     case "llm_call_started":
@@ -192,7 +194,7 @@ export function conversationToWakeTarget(
     },
     isProcessing: () => conversation.isProcessing(),
     markProcessing: (on) => {
-      conversation.processing = on;
+      conversation.setProcessing(on);
     },
     setTrustContext: (ctx) => conversation.setTrustContext(ctx),
     setWakeAllowedTools: (tools) => {

package/src/home/home-greeting-cache.ts

@@ -10,11 +10,15 @@
  * Storage uses the existing `memory_checkpoints` table (simple key-value store).
  */
 
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+
 import {
   getMemoryCheckpoint,
   setMemoryCheckpoint,
 } from "../memory/checkpoints.js";
-import { computeIdentityContentHash } from "../runtime/routes/identity-intro-cache.js";
+import { resolveGuardianPersona } from "../prompts/persona-resolver.js";
+import { getWorkspacePromptPath } from "../util/platform.js";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -26,6 +30,25 @@ const CHECKPOINT_KEY_TEXT = "home:greeting:text";
 const CHECKPOINT_KEY_HASH = "home:greeting:content_hash";
 const CHECKPOINT_KEY_TIMESTAMP = "home:greeting:cached_at";
 
+const IDENTITY_FILES = ["IDENTITY.md", "SOUL.md"] as const;
+
+function readWorkspaceFile(name: string): string {
+  try {
+    const path = getWorkspacePromptPath(name);
+    if (!existsSync(path)) return "";
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+function computeIdentityContentHash(): string {
+  const staticFiles = IDENTITY_FILES.map(readWorkspaceFile).join("\n---\n");
+  const guardianPersona = resolveGuardianPersona() ?? "";
+  const combined = staticFiles + "\n---\n" + guardianPersona;
+  return createHash("sha256").update(combined).digest("hex");
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------

package/src/ipc/gateway-client.test.ts

@@ -91,7 +91,7 @@ describe("ipcGetFeatureFlags", () => {
     expect(flags).toEqual({ "flag-a": true, "flag-b": false });
   });
 
-  test("filters non-boolean values from response", async () => {
+  test("accepts boolean and string values, filters other types from response", async () => {
     mockGatewayIpc(null, {
       results: {
         get_feature_flags: {
@@ -104,7 +104,7 @@ describe("ipcGetFeatureFlags", () => {
     });
 
     const flags = await ipcGetFeatureFlags();
-    expect(flags).toEqual({ valid: true });
+    expect(flags).toEqual({ valid: true, string: "yes" });
   });
 
   test("returns empty record when IPC returns undefined", async () => {

package/src/ipc/gateway-client.ts

@@ -98,12 +98,12 @@ export function resetPersistentClient(): void {
  */
 export async function ipcGetFeatureFlags(
   timeoutMs?: number,
-): Promise<Record<string, boolean>> {
+): Promise<Record<string, boolean | string>> {
   const result = await ipcCall("get_feature_flags", undefined, timeoutMs);
   if (result && typeof result === "object" && !Array.isArray(result)) {
-    const filtered: Record<string, boolean> = {};
+    const filtered: Record<string, boolean | string> = {};
     for (const [k, v] of Object.entries(result as Record<string, unknown>)) {
-      if (typeof v === "boolean") filtered[k] = v;
+      if (typeof v === "boolean" || typeof v === "string") filtered[k] = v;
     }
     return filtered;
   }

package/src/media/gemini-image-service.ts

@@ -5,6 +5,7 @@ import {
   type ImageGenCredentials,
   type ImageGenerationRequest,
   type ImageGenerationResult,
+  isImageProviderBillingError,
   type ManagedProxyCredentials,
   MAX_VARIANTS,
 } from "./types.js";
@@ -19,9 +20,18 @@ const ALLOWED_MODELS = new Set([
 
 // --- Error mapping ---
 
+const GEMINI_BILLING_MESSAGE =
+  "Image generation is unavailable because the Gemini account or API key is out of credits. " +
+  "Add funds with the provider or update the key in Settings — retrying won't help until credits are added.";
+
 export function mapGeminiError(error: unknown): string {
   if (error instanceof ApiError) {
     const status = error.status;
+    // Billing failures are non-retryable, so check them before the rate-limit
+    // branch to avoid telling the user to "wait and try again".
+    if (isImageProviderBillingError({ status, message: error.message })) {
+      return GEMINI_BILLING_MESSAGE;
+    }
     if (status === 400) {
       return "The image request was invalid. Please check your prompt and try again.";
     }
@@ -37,6 +47,11 @@ export function mapGeminiError(error: unknown): string {
     return `Gemini API error (status ${status}). Please try again.`;
   }
   if (error instanceof Error) {
+    // The managed proxy surfaces failures as plain Errors whose message embeds
+    // the upstream status (e.g. "Managed proxy request failed (402): ...").
+    if (isImageProviderBillingError({ message: error.message })) {
+      return GEMINI_BILLING_MESSAGE;
+    }
     return `Image generation failed: ${error.message}`;
   }
   return "An unexpected error occurred during image generation.";

package/src/media/openai-image-service.ts

@@ -6,6 +6,7 @@ import {
   type ImageGenCredentials,
   type ImageGenerationRequest,
   type ImageGenerationResult,
+  isImageProviderBillingError,
   MAX_VARIANTS,
 } from "./types.js";
 
@@ -16,6 +17,10 @@ const ALLOWED_MODELS = new Set(["gpt-image-2"]);
 
 // --- Error mapping ---
 
+const OPENAI_BILLING_MESSAGE =
+  "Image generation is unavailable because the OpenAI account or API key is out of credits. " +
+  "Add funds with the provider or update the key in Settings — retrying won't help until credits are added.";
+
 /**
  * Map an error raised by the OpenAI Images API to a user-friendly string.
  * Mirrors the status-code branches of `mapGeminiError` in
@@ -24,6 +29,12 @@ const ALLOWED_MODELS = new Set(["gpt-image-2"]);
 export function mapOpenAIError(error: unknown): string {
   if (error instanceof OpenAI.APIError) {
     const status = error.status;
+    // Billing failures are non-retryable and can surface as a 402 or as a 429
+    // with an `insufficient_quota` body, so check them before the rate-limit
+    // branch to avoid telling the user to "wait and try again".
+    if (isImageProviderBillingError({ status, message: error.message })) {
+      return OPENAI_BILLING_MESSAGE;
+    }
     if (status === 400) {
       return "The image request was invalid. Please check your prompt and try again.";
     }
@@ -39,6 +50,9 @@ export function mapOpenAIError(error: unknown): string {
     return `OpenAI API error (status ${status}). Please try again.`;
   }
   if (error instanceof Error) {
+    if (isImageProviderBillingError({ message: error.message })) {
+      return OPENAI_BILLING_MESSAGE;
+    }
     return `Image generation failed: ${error.message}`;
   }
   return "An unexpected error occurred during image generation.";

package/src/media/types.ts

@@ -44,3 +44,37 @@ export function providerForImageModelPrefix(model: string): ImageGenProvider {
   }
   return "gemini";
 }
+
+/**
+ * Message fragments that indicate a provider billing / insufficient-credits
+ * failure. Used by the per-provider error mappers to detect a non-retryable
+ * out-of-credits condition that no number of retries will resolve.
+ */
+const BILLING_MESSAGE_PATTERNS: readonly RegExp[] = [
+  /credit balance is too low/i,
+  /insufficient[\s_-]*credits?/i,
+  /insufficient_quota/i,
+  /exceeded your current quota/i,
+  /out of credits/i,
+  /requires more credits/i,
+  /billing/i,
+  /request failed \(402\)/i,
+];
+
+/**
+ * Detect a provider billing / insufficient-credits failure from an HTTP status
+ * and/or error message. A 402 status is billing by definition; otherwise the
+ * message is matched against known billing phrasings (OpenAI's
+ * `insufficient_quota` is reported as a 429, so status alone is insufficient).
+ *
+ * Billing failures are non-retryable: the user must add funds or update the API
+ * key. Callers surface a distinct message instead of a generic "try again".
+ */
+export function isImageProviderBillingError(args: {
+  status?: number;
+  message?: string;
+}): boolean {
+  if (args.status === 402) return true;
+  const message = args.message ?? "";
+  return BILLING_MESSAGE_PATTERNS.some((pattern) => pattern.test(message));
+}