@desplega.ai/agent-swarm 1.90.0 → 1.92.0

package/src/tools/create-metric.ts

@@ -5,6 +5,7 @@ import { assertSelectOnlyQuery } from "@/http/db-query";
 import { snapshotMetric } from "@/metrics/version";
 import { createToolRegistrar } from "@/tools/utils";
 import { MetricDefinitionSchema } from "@/types";
+import { getAppUrl } from "@/utils/constants";
 
 function slugify(input: string): string {
   const slug = input
@@ -16,9 +17,7 @@ function slugify(input: string): string {
 }
 
 function getAppBaseUrl(): string {
-  const env = process.env.APP_URL?.trim();
-  if (env) return env.replace(/\/+$/, "");
-  return "http://localhost:5274";
+  return getAppUrl();
 }
 
 function metricEditCounter(metricId: string): number {

package/src/tools/create-page.ts

@@ -23,6 +23,7 @@ import { createPage, getPage, getPageBySlug, getPageVersions, updatePage } from
 import { snapshotPage } from "@/pages/version";
 import { createToolRegistrar } from "@/tools/utils";
 import { PageAuthModeSchema, PageContentTypeSchema } from "@/types";
+import { getAppUrl, getPublicMcpBaseUrl } from "@/utils/constants";
 
 /** Same slugifier used by the HTTP createPage handler. */
 function slugify(input: string): string {
@@ -35,15 +36,11 @@ function slugify(input: string): string {
 }
 
 function getApiBaseUrl(): string {
-  const env = process.env.MCP_BASE_URL?.trim();
-  if (env) return env.replace(/\/+$/, "");
-  return `http://localhost:${process.env.PORT || "3013"}`;
+  return getPublicMcpBaseUrl();
 }
 
 function getAppBaseUrl(): string {
-  const env = process.env.APP_URL?.trim();
-  if (env) return env.replace(/\/+$/, "");
-  return "http://localhost:5274";
+  return getAppUrl();
 }
 
 /**

package/src/tools/db-query.ts

@@ -1,10 +1,21 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
-import { executeReadOnlyQuery } from "@/http/db-query";
+import { DbQueryInputShape, executeReadOnlyQuery, resolveDbQuerySql } from "@/http/db-query";
 import { createToolRegistrar } from "@/tools/utils";
 
 const MCP_MAX_ROWS = 100;
 
+const DbQueryToolInputSchema = z
+  .object({
+    ...DbQueryInputShape,
+    sql: z.string().optional().describe("SQL query (read-only only — writes are rejected)"),
+    query: z.string().optional().describe("Deprecated runtime alias for sql."),
+    params: z.array(z.any()).optional().default([]).describe("Query parameters"),
+  })
+  .refine((body) => body.sql !== undefined || body.query !== undefined, {
+    message: "Either sql or query is required",
+  });
+
 export const registerDbQueryTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "db-query",
@@ -13,10 +24,7 @@ export const registerDbQueryTool = (server: McpServer) => {
       description:
         "Execute a read-only SQL query against the swarm database. Available to all authenticated agents — be aware results may include secrets (oauth_tokens, configs). Results capped at 100 rows.",
       annotations: { readOnlyHint: true },
-      inputSchema: z.object({
-        sql: z.string().describe("SQL query (read-only only — writes are rejected)"),
-        params: z.array(z.any()).optional().default([]).describe("Query parameters"),
-      }),
+      inputSchema: DbQueryToolInputSchema,
       outputSchema: z.object({
         success: z.boolean(),
         columns: z.array(z.string()),
@@ -26,8 +34,10 @@ export const registerDbQueryTool = (server: McpServer) => {
         truncated: z.boolean(),
       }),
     },
-    async ({ sql, params }, _requestInfo, _meta) => {
+    async (input, _requestInfo, _meta) => {
       try {
+        const sql = resolveDbQuerySql(input);
+        const params = input.params ?? [];
         const result = executeReadOnlyQuery(sql, params, MCP_MAX_ROWS);
         const truncated = result.total > MCP_MAX_ROWS;
 

package/src/tools/memory-rate.ts

@@ -3,6 +3,7 @@ import * as z from "zod";
 import { REFERENCES_SOURCE_MAX_LENGTH, sanitizeReferencesSource } from "@/be/memory/raters/types";
 import { createToolRegistrar } from "@/tools/utils";
 import { getApiKey } from "@/utils/api-key";
+import { getMcpBaseUrl } from "@/utils/constants";
 
 /**
  * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-5.md §1
@@ -92,7 +93,7 @@ export const registerMemoryRateTool = (server: McpServer) => {
         cleanedReferencesSource = cleaned;
       }
 
-      const apiUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+      const apiUrl = getMcpBaseUrl();
       const apiKey = getApiKey();
 
       const event = {

package/src/tools/memory-search.ts

@@ -125,6 +125,7 @@ export const registerMemorySearchTool = (server: McpServer) => {
         scope: scope as "agent" | "swarm" | "all",
         limit,
         isLead,
+        source,
       });
 
       const mapped = recent.map((r) => ({

package/src/tools/register-kapso-number.ts

@@ -10,13 +10,11 @@ import {
   putKapsoNumberMapping,
 } from "@/integrations/kapso/config";
 import { createToolRegistrar } from "@/tools/utils";
+import { getPublicMcpBaseUrl } from "@/utils/constants";
 
 /** Build the native inbound webhook URL the swarm exposes for Kapso deliveries. */
 function nativeWebhookUrl(): string {
-  const base = (
-    process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`
-  ).replace(/\/+$/, "");
-  return `${base}/api/integrations/kapso/webhook`;
+  return `${getPublicMcpBaseUrl()}/api/integrations/kapso/webhook`;
 }
 
 export const registerRegisterKapsoNumberTool = (server: McpServer) => {

package/src/tools/request-human-input.ts

@@ -2,6 +2,7 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { createApprovalRequest, getAgentCurrentTask } from "@/be/db";
 import { createToolRegistrar } from "@/tools/utils";
+import { getAppUrl } from "@/utils/constants";
 
 const QuestionSchema = z.object({
   id: z.string().describe("Unique ID for the question (used as key in responses)"),
@@ -94,7 +95,7 @@ export const registerRequestHumanInputTool = (server: McpServer) => {
         timeoutSeconds,
       });
 
-      const appUrl = process.env.APP_URL || "http://localhost:5274";
+      const appUrl = getAppUrl();
       const url = `${appUrl}/approval-requests/${request.id}`;
 
       return {

package/src/tools/script-common.ts

@@ -1,6 +1,7 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import * as z from "zod";
 import { getApiKey } from "@/utils/api-key";
+import { getMcpBaseUrl } from "@/utils/constants";
 import type { RequestInfo } from "./utils";
 
 export const SCRIPT_TRANSPORT_ERROR =
@@ -20,10 +21,7 @@ export const scriptToolOutputSchema = z.object({
 export type ScriptToolStructuredContent = z.infer<typeof scriptToolOutputSchema>;
 
 function apiBaseUrl(): string {
-  return (process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`).replace(
-    /\/+$/,
-    "",
-  );
+  return getMcpBaseUrl();
 }
 
 function toolError(message: string, status = 400): CallToolResult {

package/src/tools/script-run.ts

@@ -28,6 +28,13 @@ export const registerScriptRunTool = (server: McpServer) => {
         fsMode: scriptFsModeSchema
           .default("none")
           .describe("Filesystem mode. v1 supports none only."),
+        idempotencyKey: z
+          .string()
+          .max(200)
+          .optional()
+          .describe(
+            "When set, output is auto-persisted to kv under script:executions/{key}. Re-running with the same key overwrites. Queryable via kv-get.",
+          ),
       }),
       outputSchema: scriptToolOutputSchema,
     },

package/src/tools/script-runs.ts

@@ -0,0 +1,123 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar } from "@/tools/utils";
+import { ScriptRunStatusSchema } from "@/types";
+import { proxyScriptsApi, scriptNameSchema, scriptToolOutputSchema } from "./script-common";
+
+export const LAUNCH_SCRIPT_RUN_DESCRIPTION =
+  "Launch a durable one-off script workflow run. The run executes in the background and can be inspected with get-script-run for terminal status and journal entries.";
+
+export const GET_SCRIPT_RUN_DESCRIPTION =
+  "Get a durable script workflow run by ID, including its journal entries for swarm-script, raw-llm, and agent-task steps.";
+
+export const LIST_SCRIPT_RUNS_DESCRIPTION =
+  "List durable script workflow runs, optionally filtered by status or agent ID.";
+
+export const registerScriptRunsTools = (server: McpServer) => {
+  const register = createToolRegistrar(server);
+
+  register(
+    "launch-script-run",
+    {
+      title: "Launch Script Run",
+      description: LAUNCH_SCRIPT_RUN_DESCRIPTION,
+      annotations: { openWorldHint: true },
+      inputSchema: z.object({
+        source: z.string().min(1).describe("TypeScript script workflow source."),
+        args: z.unknown().optional().describe("JSON-serializable workflow arguments."),
+        idempotencyKey: z
+          .string()
+          .min(1)
+          .max(200)
+          .optional()
+          .describe("Optional key that returns the existing run instead of launching a duplicate."),
+        scriptName: scriptNameSchema
+          .optional()
+          .describe("Optional human-readable script/workflow name for the run."),
+        requestedByUserId: z
+          .string()
+          .optional()
+          .describe("Optional canonical user ID to attribute the run to."),
+      }),
+      outputSchema: scriptToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyScriptsApi({
+        method: "POST",
+        path: "/api/script-runs",
+        body: { ...args, background: true },
+        requestInfo,
+        successMessage: (data) => {
+          const id =
+            typeof data === "object" && data !== null && "id" in data
+              ? String((data as { id: unknown }).id)
+              : "unknown";
+          return `Script run launched: ${id}.`;
+        },
+      }),
+  );
+
+  register(
+    "get-script-run",
+    {
+      title: "Get Script Run",
+      description: GET_SCRIPT_RUN_DESCRIPTION,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      inputSchema: z.object({
+        id: z.string().uuid().describe("Script run ID."),
+      }),
+      outputSchema: scriptToolOutputSchema,
+    },
+    async ({ id }, requestInfo) =>
+      proxyScriptsApi({
+        method: "GET",
+        path: `/api/script-runs/${encodeURIComponent(id)}`,
+        requestInfo,
+        successMessage: (data) => {
+          const status =
+            typeof data === "object" &&
+            data !== null &&
+            "run" in data &&
+            typeof (data as { run?: { status?: unknown } }).run?.status === "string"
+              ? (data as { run: { status: string } }).run.status
+              : "unknown";
+          return `Script run ${id} status: ${status}.`;
+        },
+      }),
+  );
+
+  register(
+    "list-script-runs",
+    {
+      title: "List Script Runs",
+      description: LIST_SCRIPT_RUNS_DESCRIPTION,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      inputSchema: z.object({
+        status: ScriptRunStatusSchema.optional().describe("Optional script run status filter."),
+        agentId: z.string().optional().describe("Optional agent ID filter."),
+        limit: z.number().int().min(1).max(500).default(50).describe("Maximum runs to return."),
+        offset: z.number().int().min(0).default(0).describe("Pagination offset."),
+      }),
+      outputSchema: scriptToolOutputSchema,
+    },
+    async ({ status, agentId, limit, offset }, requestInfo) => {
+      const params = new URLSearchParams();
+      if (status) params.set("status", status);
+      if (agentId) params.set("agentId", agentId);
+      params.set("limit", String(limit));
+      params.set("offset", String(offset));
+      return proxyScriptsApi({
+        method: "GET",
+        path: `/api/script-runs?${params.toString()}`,
+        requestInfo,
+        successMessage: (data) => {
+          const total =
+            typeof data === "object" && data !== null && "total" in data
+              ? Number((data as { total: unknown }).total)
+              : 0;
+          return `Found ${Number.isFinite(total) ? total : 0} script run(s).`;
+        },
+      });
+    },
+  );
+};

package/src/tools/slack-read.ts

@@ -3,6 +3,7 @@ import * as z from "zod";
 import { getAgentById, getInboxMessageById, getTaskById } from "@/be/db";
 import { getSlackApp } from "@/slack/app";
 import { downloadFile } from "@/slack/files";
+import { extractSlackMessageText } from "@/slack/message-text";
 import { createToolRegistrar } from "@/tools/utils";
 
 /**
@@ -203,6 +204,13 @@ export const registerSlackReadTool = (server: McpServer) => {
           text?: string;
           ts: string;
           files?: RawFile[];
+          attachments?: Array<{
+            fallback?: string;
+            text?: string;
+            title?: string;
+            pretext?: string;
+          }>;
+          blocks?: unknown[];
         };
 
         let rawMessages: RawMessage[] = [];
@@ -267,8 +275,9 @@ export const registerSlackReadTool = (server: McpServer) => {
         }> = [];
 
         for (const m of rawMessages) {
-          // Include messages with text OR files
-          if (!m.text && (!m.files || m.files.length === 0)) continue;
+          // Include messages with text, attachments, blocks, or files
+          const extractedText = extractSlackMessageText(m);
+          if (!extractedText && (!m.files || m.files.length === 0)) continue;
 
           const isBot =
             m.user === botUserId || m.bot_id !== undefined || m.subtype === "bot_message";
@@ -330,7 +339,7 @@ export const registerSlackReadTool = (server: McpServer) => {
             user: m.user,
             username,
             isBot,
-            text: m.text || "",
+            text: extractedText,
             ts: m.ts,
             files,
           });

package/src/tools/tool-config.ts

@@ -164,12 +164,15 @@ export const DEFERRED_TOOLS = new Set([
   "kv-incr",
   "kv-list",
 
-  // Reusable scripts (5)
+  // Reusable scripts (8)
   "script-search",
   "script-run",
   "script-upsert",
   "script-delete",
   "script-query-types",
+  "launch-script-run",
+  "get-script-run",
+  "list-script-runs",
 
   // External command routes (1)
   "swarm_x",

package/src/types.ts

@@ -1535,6 +1535,58 @@ export const WorkflowRunSchema = z.object({
 });
 export type WorkflowRun = z.infer<typeof WorkflowRunSchema>;
 
+// --- Script Workflow Runs ---
+
+export const ScriptRunStatusSchema = z.enum([
+  "running",
+  "paused",
+  "completed",
+  "failed",
+  "cancelled",
+  "aborted_limit",
+]);
+export type ScriptRunStatus = z.infer<typeof ScriptRunStatusSchema>;
+
+export const TERMINAL_SCRIPT_RUN_STATUSES = [
+  "completed",
+  "failed",
+  "cancelled",
+  "aborted_limit",
+] as const;
+export type TerminalScriptRunStatus = (typeof TERMINAL_SCRIPT_RUN_STATUSES)[number];
+
+export const ScriptRunSchema = z.object({
+  id: z.string().uuid(),
+  agentId: z.string(),
+  scriptName: z.string().optional(),
+  source: z.string(),
+  args: z.unknown(),
+  status: ScriptRunStatusSchema,
+  pid: z.number().int().optional(),
+  startedAt: z.string(),
+  finishedAt: z.string().optional(),
+  output: z.unknown().optional(),
+  error: z.string().optional(),
+  lastHeartbeatAt: z.string().optional(),
+  idempotencyKey: z.string().optional(),
+  requestedByUserId: z.string().optional(),
+});
+export type ScriptRun = z.infer<typeof ScriptRunSchema>;
+
+export const ScriptRunJournalEntrySchema = z.object({
+  id: z.string().uuid(),
+  runId: z.string().uuid(),
+  stepKey: z.string(),
+  stepType: z.string(),
+  config: z.record(z.string(), z.unknown()),
+  status: z.enum(["completed", "failed"]),
+  result: z.unknown().optional(),
+  error: z.string().optional(),
+  startedAt: z.string(),
+  completedAt: z.string().optional(),
+});
+export type ScriptRunJournalEntry = z.infer<typeof ScriptRunJournalEntrySchema>;
+
 // --- Workflow Run Step ---
 
 export const WorkflowRunStepStatusSchema = z.enum([

package/src/utils/constants.ts

@@ -3,19 +3,69 @@
  */
 
 /**
- * Default dashboard URL used when `APP_URL` is unset. Points at the public
- * production dashboard so links (Slack messages, approval URLs, etc.) are
- * always renderable. Self-hosted operators should set `APP_URL` to override.
+ * Default dashboard URL used when neither `APP_URL` nor the deprecated
+ * `DASHBOARD_URL` is set. Points at the public production dashboard so links
+ * (Slack messages, approval URLs, page share links, post-OAuth redirects)
+ * stay renderable even when an operator forgets to configure it. Local dev
+ * should set `APP_URL` (e.g. in `.env`) to point at the local dashboard.
  */
 export const DEFAULT_APP_URL = "https://app.agent-swarm.dev";
 
 /**
- * Resolve the effective app/dashboard URL from `APP_URL` (with trailing
- * slashes stripped), falling back to {@link DEFAULT_APP_URL}.
+ * Resolve every explicitly configured app/dashboard URL. Each env var may be
+ * a comma-separated origin list; entries are returned in precedence order with
+ * trailing slashes stripped.
+ *
+ * Precedence: `APP_URL` entries → `DASHBOARD_URL` entries (deprecated alias,
+ * kept for back-compat).
+ */
+export function getConfiguredAppUrls(): string[] {
+  return [process.env.APP_URL, process.env.DASHBOARD_URL]
+    .flatMap((value) => (value ?? "").split(","))
+    .map((value) => value.trim().replace(/\/+$/, ""))
+    .filter(Boolean);
+}
+
+/**
+ * Resolve the effective app/dashboard URL — the public origin the user's
+ * browser is sent to (post-login redirects, Slack/approval links, page
+ * `app_url` share links). Trailing slashes are stripped.
+ *
+ * Precedence: first configured `APP_URL` entry → first configured
+ * `DASHBOARD_URL` entry (deprecated alias, kept for back-compat) → fallback.
+ * This is the single source of truth; call sites must not re-read
+ * `APP_URL`/`DASHBOARD_URL` directly.
+ */
+export function getAppUrl(fallback = DEFAULT_APP_URL): string {
+  return (getConfiguredAppUrls()[0] || fallback).replace(/\/+$/, "");
+}
+
+/**
+ * Internal API/MCP base URL — how workers/agents and in-process callers reach
+ * the API server. May be a private/cluster address (e.g. the Helm ClusterIP
+ * `http://<release>-api:3013`). Do NOT use for browser-facing or
+ * externally-registered URLs (OAuth redirect URIs, webhook URLs): those must
+ * resolve to a host the browser / third party can reach — use
+ * {@link getPublicMcpBaseUrl} (no request context) or `deriveApiBaseUrl(req)`
+ * (request-scoped) instead. Trailing slashes are stripped.
+ */
+export function getMcpBaseUrl(): string {
+  const raw = process.env.MCP_BASE_URL?.trim();
+  return (raw || `http://localhost:${process.env.PORT || "3013"}`).replace(/\/+$/, "");
+}
+
+/**
+ * Public, browser-/externally-reachable origin of the API server — where
+ * `/api/mcp-oauth/callback`, OAuth redirect URIs, and registered webhook URLs
+ * resolve. Falls back to {@link getMcpBaseUrl} when the public and internal
+ * hosts are the same (local dev, single-box, or an ngrok/tunnel set as
+ * `MCP_BASE_URL`). In split deployments (Helm), set `PUBLIC_MCP_BASE_URL` to
+ * the public ingress URL while `MCP_BASE_URL` stays the internal service
+ * address. Trailing slashes are stripped.
  */
-export function getAppUrl(): string {
-  const raw = process.env.APP_URL?.trim();
-  return (raw || DEFAULT_APP_URL).replace(/\/+$/, "");
+export function getPublicMcpBaseUrl(): string {
+  const raw = process.env.PUBLIC_MCP_BASE_URL?.trim();
+  return raw ? raw.replace(/\/+$/, "") : getMcpBaseUrl();
 }
 
 /**

package/src/utils/error-tracker.ts

@@ -28,7 +28,46 @@ export const MAX_RATE_LIMIT_RESET_MS = 7 * 24 * 60 * 60 * 1000;
  * "429 Too Many Requests"; does not match "No conversation found with session ID".
  */
 export function isRateLimitMessage(s: string): boolean {
-  return /rate.?limit|hit your[\w\s-]*limit|usage[ _-]?limit|too many requests|\b429\b/i.test(s);
+  return (
+    /rate.?limit|hit your[\w\s-]*limit|usage[ _-]?limit|too many requests|\b429\b/i.test(s) ||
+    isCodexCreditsExhaustedMessage(s)
+  );
+}
+
+/**
+ * Detects Codex's workspace-credit-exhausted error, which surfaces as:
+ * "Your workspace is out of credits. Ask your workspace owner to refill in order to continue."
+ * This wording does not match the standard rate-limit patterns, so it needs its own predicate.
+ * Kept specific to avoid false positives — "refill" alone is intentionally excluded.
+ */
+export function isCodexCreditsExhaustedMessage(s: string): boolean {
+  return /out of credits|refill in order to continue|workspace owner to refill/i.test(s);
+}
+
+/** Default cooldown applied when a Codex OAuth slot returns a credits-exhausted error.
+ *  The workspace credit cap is weekly, so a 2-hour cooldown is conservative but avoids
+ *  the sawtooth of the 5-minute tier-3 fallback re-handing the dead slot every 5 minutes.
+ */
+export const CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS = 2 * 60 * 60 * 1000; // 2h
+
+/** Floor for the operator-tunable Codex credits cooldown — never shorter than the tier-3 fallback. */
+export const MIN_CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS = 5 * 60 * 1000; // 5m
+
+/**
+ * Resolve the effective Codex credits-exhausted cooldown (ms) from a raw config
+ * value (string | number | undefined). Falls back to the default constant on
+ * absent / empty / non-finite / non-positive input, then clamps to
+ * [MIN_CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS, MAX_RATE_LIMIT_RESET_MS].
+ * Pure + side-effect free so it's unit-testable and cheap to call.
+ */
+export function resolveCodexCreditsExhaustedCooldownMs(
+  raw: string | number | undefined | null,
+): number {
+  if (raw === undefined || raw === null || raw === "") return CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS;
+  const n =
+    typeof raw === "number" ? raw : /^\d+$/.test(raw.trim()) ? Number(raw.trim()) : Number.NaN;
+  if (!Number.isFinite(n) || n <= 0) return CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS;
+  return Math.min(Math.max(n, MIN_CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS), MAX_RATE_LIMIT_RESET_MS);
 }
 
 /**

package/src/utils/internal-ai/complete-structured.ts

@@ -84,10 +84,16 @@ async function defaultSpawnClaudeCli(
   signal?: AbortSignal,
   jsonSchema?: object,
 ): Promise<string> {
-  // CLAUDE_BINARY may be a single binary ("claude", "shannon") or a
-  // whitespace-separated command string ("bunx @dexh/shannon"). See
-  // parseClaudeBinary in src/providers/claude-adapter.ts.
-  const claudeBinaryArgv = (process.env.CLAUDE_BINARY ?? "claude").trim().split(/\s+/);
+  // SWARM_USE_CLAUDE_BRIDGE mirrors the main claude adapter's subscription-pool
+  // routing. Otherwise CLAUDE_BINARY may be a single binary ("claude", "shannon")
+  // or a whitespace-separated command string ("bunx @dexh/shannon").
+  const useClaudeBridge = ["true", "1"].includes(
+    (process.env.SWARM_USE_CLAUDE_BRIDGE ?? "").trim().toLowerCase(),
+  );
+  const claudeBinaryRaw = useClaudeBridge
+    ? "claude-bridge"
+    : (process.env.CLAUDE_BINARY ?? "claude").trim();
+  const claudeBinaryArgv = (claudeBinaryRaw || "claude").split(/\s+/);
   const cmd = [...claudeBinaryArgv, "-p", "--model", model, "--output-format", "json"];
   if (jsonSchema) {
     cmd.push("--json-schema", JSON.stringify(jsonSchema));