@desplega.ai/agent-swarm 1.91.0 → 1.92.1

package/src/tests/system-default-skills.test.ts

@@ -37,8 +37,10 @@ describe("system-default skills", () => {
     const names = skills.map((skill) => skill.name);
 
     expect(names).toContain("attio-interaction");
+    expect(names).toContain("script-workflows");
     expect(names).toContain("swarm-scripts");
     expect(skills.find((skill) => skill.name === "attio-interaction")?.systemDefault).toBe(true);
+    expect(skills.find((skill) => skill.name === "script-workflows")?.systemDefault).toBe(true);
     expect(skills.find((skill) => skill.name === "swarm-scripts")?.systemDefault).toBe(true);
     expect(skills.find((skill) => skill.name === "kv-storage")?.systemDefault).toBe(true);
     expect(skills.find((skill) => skill.name === "pages")?.systemDefault).toBe(true);
@@ -48,6 +50,7 @@ describe("system-default skills", () => {
 
     const defaults = getSystemDefaultSkills().map((skill) => skill.name);
     expect(defaults).toContain("attio-interaction");
+    expect(defaults).toContain("script-workflows");
     expect(defaults).toContain("swarm-scripts");
     expect(defaults).toContain("kv-storage");
     expect(defaults).toContain("pages");
@@ -78,6 +81,43 @@ describe("system-default skills", () => {
     expect(skills.find((skill) => skill.id === manualDefault.id)?.isActive).toBe(true);
   });
 
+  test("existing agents see swarm-scope skills without explicit install rows", () => {
+    const existingAgent = createAgent({
+      name: "Existing Swarm Skill Worker",
+      description: "Created before a swarm-scope skill",
+      role: "worker",
+      isLead: false,
+      status: "idle",
+      maxTasks: 1,
+      capabilities: [],
+    });
+
+    const swarmSkill = createSkill({
+      name: "manual-swarm-scope-skill",
+      description: "Manual swarm scope skill",
+      content:
+        "---\nname: manual-swarm-scope-skill\ndescription: Manual swarm scope skill\n---\nBody.",
+      type: "personal",
+      scope: "swarm",
+      systemDefault: false,
+    });
+
+    const installRow = getDb()
+      .prepare<{ count: number }, [string, string]>(
+        `SELECT COUNT(*) AS count
+         FROM agent_skills
+         WHERE agentId = ?
+           AND skillId = ?`,
+      )
+      .get(existingAgent.id, swarmSkill.id);
+
+    expect(installRow?.count ?? 0).toBe(0);
+
+    const skills = getAgentSkills(existingAgent.id);
+    expect(skills.map((skill) => skill.name)).toContain("manual-swarm-scope-skill");
+    expect(skills.find((skill) => skill.id === swarmSkill.id)?.isActive).toBe(true);
+  });
+
   test("new agents get concrete agent_skills rows for system defaults", () => {
     const beforeAgent = createAgent({
       name: "Concrete Install Worker",

package/src/tools/create-page.ts

@@ -82,8 +82,8 @@ export const registerCreatePageTool = (server: McpServer) => {
         contentType: PageContentTypeSchema.describe(
           "'text/html' renders directly at /p/:id; 'application/json' is rendered by the SPA.",
         ),
-        authMode: PageAuthModeSchema.default("public").describe(
-          "'public' — no gate; 'authed' — requires page-session cookie; 'password' — requires key.",
+        authMode: PageAuthModeSchema.default("authed").describe(
+          "'authed' — requires page-session cookie (default); 'public' — no gate and must be explicit; 'password' — requires key.",
         ),
         password: z
           .string()

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/skills/index.ts

@@ -1,6 +1,7 @@
 export { registerSkillCreateTool } from "./skill-create";
 export { registerSkillDeleteTool } from "./skill-delete";
 export { registerSkillGetTool } from "./skill-get";
+export { registerSkillGetFileTool } from "./skill-get-file";
 export { registerSkillInstallTool } from "./skill-install";
 export { registerSkillInstallRemoteTool } from "./skill-install-remote";
 export { registerSkillListTool } from "./skill-list";

package/src/tools/skills/skill-get-file.ts

@@ -0,0 +1,80 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getSkillById, getSkillFile } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerSkillGetFileTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "skill-get-file",
+    {
+      title: "Get Skill File",
+      annotations: { destructiveHint: false },
+      description:
+        "Fetch a bundled reference file from a complex skill by skillId and relative path. Use this when the file is not available on disk.",
+      inputSchema: z.object({
+        skillId: z.string().describe("Skill ID"),
+        path: z.string().describe("Relative path, e.g. references/animations.md"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        file: z.any().optional(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      const skill = getSkillById(args.skillId);
+      if (!skill) {
+        return {
+          content: [{ type: "text", text: "Skill not found." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Skill not found.",
+          },
+        };
+      }
+
+      let file = null;
+      try {
+        file = getSkillFile(args.skillId, args.path);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Invalid file path.";
+        return {
+          content: [{ type: "text", text: message }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message,
+          },
+        };
+      }
+
+      if (!file) {
+        return {
+          content: [{ type: "text", text: "Skill file not found." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Skill file not found.",
+          },
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Skill file "${skill.name}/${file.path}" (${file.mimeType}):\n\n${file.content}`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: `Found skill file "${file.path}".`,
+          file,
+        },
+      };
+    },
+  );
+};

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

@@ -128,11 +128,12 @@ export const DEFERRED_TOOLS = new Set([
   // Approval Requests (1)
   "request-human-input",
 
-  // Skills (11)
+  // Skills (12)
   "skill-create",
   "skill-update",
   "skill-delete",
   "skill-get",
+  "skill-get-file",
   "skill-list",
   "skill-search",
   "skill-install",
@@ -164,12 +165,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,65 @@ 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];
+
+// `workflow` = durable background run launched via /api/script-runs (has a journal).
+// `inline` = synchronous one-off run via /api/scripts/run (no journal).
+export const ScriptRunKindSchema = z.enum(["workflow", "inline"]);
+export type ScriptRunKind = z.infer<typeof ScriptRunKindSchema>;
+
+export const ScriptRunSchema = z.object({
+  id: z.string().uuid(),
+  agentId: z.string(),
+  scriptName: z.string().optional(),
+  source: z.string(),
+  args: z.unknown(),
+  kind: ScriptRunKindSchema,
+  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(),
+  durationMs: z.number().optional(),
+});
+export type ScriptRunJournalEntry = z.infer<typeof ScriptRunJournalEntrySchema>;
+
 // --- Workflow Run Step ---
 
 export const WorkflowRunStepStatusSchema = z.enum([
@@ -1742,6 +1801,19 @@ export const SkillWithInstallInfoSchema = SkillSchema.extend({
 });
 export type SkillWithInstallInfo = z.infer<typeof SkillWithInstallInfoSchema>;
 
+export const SkillFileSchema = z.object({
+  id: z.string(),
+  skillId: z.string(),
+  path: z.string(),
+  content: z.string(),
+  mimeType: z.string(),
+  isBinary: z.boolean(),
+  size: z.number().nullable(),
+  createdAt: z.string(),
+  lastUpdatedAt: z.string(),
+});
+export type SkillFile = z.infer<typeof SkillFileSchema>;
+
 // ── MCP Servers ──────────────────────────────────────────────────────────
 
 export const McpServerTransportSchema = z.enum(["stdio", "http", "sse"]);

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, an absolute path,
+  // or a whitespace-separated command string.
+  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));