@desplega.ai/agent-swarm 1.91.0 → 1.92.0

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/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/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));

package/src/workflows/executors/raw-llm.ts

@@ -16,6 +16,76 @@ export const RawLlmOutputSchema = z.object({
   model: z.string(),
 });
 
+export async function executeRawLlm(
+  config: z.infer<typeof RawLlmConfigSchema>,
+): Promise<
+  | { status: "success"; output: z.infer<typeof RawLlmOutputSchema>; error?: string }
+  | { status: "failed"; error: string }
+> {
+  const modelName = config.model ?? "google/gemini-3-flash-preview";
+
+  try {
+    const { createOpenAI } = await import("@ai-sdk/openai");
+    const openrouter = createOpenAI({
+      baseURL: "https://openrouter.ai/api/v1",
+      apiKey: process.env.OPENROUTER_API_KEY,
+    });
+    const model = openrouter(modelName);
+
+    if (config.schema) {
+      const { generateObject, jsonSchema } = await import("ai");
+      const { object } = await generateObject({
+        model,
+        schema: jsonSchema(config.schema),
+        prompt: config.prompt,
+        providerOptions: {
+          openai: { strictJsonSchema: false },
+        },
+      });
+      return {
+        status: "success",
+        output: { result: object, model: modelName },
+      };
+    }
+
+    const { generateText } = await import("ai");
+    const { text } = await generateText({
+      model,
+      prompt: config.prompt,
+    });
+    return {
+      status: "success",
+      output: { result: text, model: modelName },
+    };
+  } catch (err) {
+    // Re-throw rate-limit errors so executeStep's retry policy handles them
+    // via the retry poller (scheduled backoff). Using the fallbackPort for
+    // rate limits would trigger the semantic loop-back path instead, causing
+    // runaway retries without any backoff.
+    const httpStatus =
+      (err as { status?: number; statusCode?: number })?.status ??
+      (err as { status?: number; statusCode?: number })?.statusCode;
+    const isRateLimited =
+      httpStatus === 429 ||
+      httpStatus === 529 ||
+      (err instanceof Error && /rate.?limit|too many requests|529/i.test(err.message));
+    if (isRateLimited) {
+      throw err;
+    }
+    if (config.fallbackPort) {
+      return {
+        status: "success",
+        output: { result: null, model: modelName },
+        error: `LLM call failed, using fallback port: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+    return {
+      status: "failed",
+      error: `LLM call failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
 // ─── Executor ───────────────────────────────────────────────
 
 export class RawLlmExecutor extends BaseExecutor<
@@ -33,68 +103,15 @@ export class RawLlmExecutor extends BaseExecutor<
     _meta: ExecutorMeta,
   ): Promise<ExecutorResult<z.infer<typeof RawLlmOutputSchema>>> {
     const prompt = this.deps.interpolate(config.prompt, context as Record<string, unknown>);
-    const modelName = config.model ?? "google/gemini-3-flash-preview";
-
-    try {
-      const { createOpenAI } = await import("@ai-sdk/openai");
-      const openrouter = createOpenAI({
-        baseURL: "https://openrouter.ai/api/v1",
-        apiKey: process.env.OPENROUTER_API_KEY,
-      });
-      const model = openrouter(modelName);
-
-      if (config.schema) {
-        const { generateObject, jsonSchema } = await import("ai");
-        const { object } = await generateObject({
-          model,
-          schema: jsonSchema(config.schema),
-          prompt,
-          providerOptions: {
-            openai: { strictJsonSchema: false },
-          },
-        });
-        return {
-          status: "success",
-          output: { result: object, model: modelName },
-        };
-      }
-
-      const { generateText } = await import("ai");
-      const { text } = await generateText({
-        model,
-        prompt,
-      });
+    const result = await executeRawLlm({ ...config, prompt });
+    if (result.status === "success" && result.error) {
       return {
         status: "success",
-        output: { result: text, model: modelName },
-      };
-    } catch (err) {
-      // Re-throw rate-limit errors so executeStep's retry policy handles them
-      // via the retry poller (scheduled backoff). Using the fallbackPort for
-      // rate limits would trigger the semantic loop-back path instead, causing
-      // runaway retries without any backoff.
-      const httpStatus =
-        (err as { status?: number; statusCode?: number })?.status ??
-        (err as { status?: number; statusCode?: number })?.statusCode;
-      const isRateLimited =
-        httpStatus === 429 ||
-        httpStatus === 529 ||
-        (err instanceof Error && /rate.?limit|too many requests|529/i.test(err.message));
-      if (isRateLimited) {
-        throw err;
-      }
-      if (config.fallbackPort) {
-        return {
-          status: "success",
-          output: { result: null, model: modelName },
-          nextPort: config.fallbackPort,
-          error: `LLM call failed, using fallback port: ${err instanceof Error ? err.message : String(err)}`,
-        };
-      }
-      return {
-        status: "failed",
-        error: `LLM call failed: ${err instanceof Error ? err.message : String(err)}`,
+        output: result.output,
+        nextPort: config.fallbackPort,
+        error: result.error,
       };
     }
+    return result;
   }
 }