@desplega.ai/agent-swarm 1.80.0 → 1.80.2

package/src/tools/script-run.ts

@@ -0,0 +1,43 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar } from "@/tools/utils";
+import {
+  proxyScriptsApi,
+  scriptFsModeSchema,
+  scriptNameSchema,
+  scriptScopeSchema,
+  scriptToolOutputSchema,
+} from "./script-common";
+
+export const SCRIPT_RUN_DESCRIPTION =
+  "Run a named swarm-shared script (callable across agents and from workflow `swarm-script` nodes), OR inline source (auto-saved as scratch to the catalog). Use for swarm-visible, durable scripts. For local-only throwaway TS, use code-mode `run`.";
+
+export const registerScriptRunTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "script-run",
+    {
+      title: "Script Run",
+      description: SCRIPT_RUN_DESCRIPTION,
+      annotations: { openWorldHint: true },
+      inputSchema: z.object({
+        name: scriptNameSchema.optional().describe("Name of a reusable script to run."),
+        source: z.string().min(1).optional().describe("Inline TypeScript source to run."),
+        args: z.unknown().optional().describe("JSON-serializable script arguments."),
+        intent: z.string().default("").describe("Why this script is being run."),
+        scope: scriptScopeSchema.optional().describe("Optional scope for named script resolution."),
+        fsMode: scriptFsModeSchema
+          .default("none")
+          .describe("Filesystem mode. v1 supports none only."),
+      }),
+      outputSchema: scriptToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyScriptsApi({
+        method: "POST",
+        path: "/api/scripts/run",
+        body: args,
+        requestInfo,
+        successMessage: () => "Script run completed.",
+      }),
+  );
+};

package/src/tools/script-search.ts

@@ -0,0 +1,32 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar } from "@/tools/utils";
+import { proxyScriptsApi, scriptScopeSchema, scriptToolOutputSchema } from "./script-common";
+
+export const SCRIPT_SEARCH_DESCRIPTION =
+  "Semantic search over swarm-shared TypeScript scripts (catalog persisted in the agent-swarm DB; callable from agents and workflows). For ephemeral throwaway TS on your local machine, use code-mode instead.";
+
+export const registerScriptSearchTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "script-search",
+    {
+      title: "Script Search",
+      description: SCRIPT_SEARCH_DESCRIPTION,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      inputSchema: z.object({
+        query: z.string().default("").describe("Search query for reusable scripts."),
+        scope: scriptScopeSchema.optional().describe("Optional script scope filter."),
+        limit: z.number().int().min(1).max(100).default(10).describe("Maximum results."),
+      }),
+      outputSchema: scriptToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyScriptsApi({
+        method: "POST",
+        path: "/api/scripts/search",
+        body: args,
+        requestInfo,
+        successMessage: () => "Script search completed.",
+      }),
+  );
+};

package/src/tools/script-upsert.ts

@@ -0,0 +1,43 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar } from "@/tools/utils";
+import {
+  proxyScriptsApi,
+  scriptFsModeSchema,
+  scriptNameSchema,
+  scriptScopeSchema,
+  scriptToolOutputSchema,
+} from "./script-common";
+
+export const SCRIPT_UPSERT_DESCRIPTION =
+  "Persist a TypeScript script to the swarm catalog under your agent scope (or global if you're a lead). Other agents and workflow nodes will be able to find and run it. For local-only scripts, use code-mode `save`.";
+
+export const registerScriptUpsertTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "script-upsert",
+    {
+      title: "Script Upsert",
+      description: SCRIPT_UPSERT_DESCRIPTION,
+      annotations: { openWorldHint: false },
+      inputSchema: z.object({
+        name: scriptNameSchema.describe("Stable script name within the selected scope."),
+        source: z.string().min(1).describe("TypeScript source with a default export function."),
+        description: z.string().default("").describe("Human-readable script description."),
+        intent: z.string().default("").describe("Why this script exists."),
+        scope: scriptScopeSchema.default("agent").describe("Persist under agent or global scope."),
+        fsMode: scriptFsModeSchema
+          .default("none")
+          .describe("Filesystem mode. v1 supports none only."),
+      }),
+      outputSchema: scriptToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyScriptsApi({
+        method: "POST",
+        path: "/api/scripts/upsert",
+        body: args,
+        requestInfo,
+        successMessage: () => "Script upsert completed.",
+      }),
+  );
+};

package/src/tools/tool-config.ts

@@ -154,6 +154,13 @@ export const DEFERRED_TOOLS = new Set([
   "kv-incr",
   "kv-list",
 
+  // Reusable scripts (5)
+  "script-search",
+  "script-run",
+  "script-upsert",
+  "script-delete",
+  "script-query-types",
+
   // Other (3)
   "cancel-task",
   "inject-learning",

package/src/types.ts

@@ -660,6 +660,8 @@ export const EventNameSchema = z.enum([
   "system.boot",
   "system.migration",
   "system.error",
+  // Script catalog events
+  "script.global_upsert",
 ]);
 
 export const SwarmEventSchema = z.object({
@@ -876,18 +878,30 @@ export const StepValidationConfigSchema = z.object({
 });
 export type StepValidationConfig = z.infer<typeof StepValidationConfigSchema>;
 
+export const SwarmScriptNodeConfigSchema = z.object({
+  scriptName: z.string().min(1),
+  scope: z.enum(["global", "agent"]).optional(),
+  pinHash: z.string().min(1).optional(),
+  args: z.record(z.string(), z.unknown()).optional(),
+  fsMode: z.enum(["none", "workspace-rw"]).optional(),
+});
+export type SwarmScriptNodeConfig = z.infer<typeof SwarmScriptNodeConfigSchema>;
+
 // --- Workflow Node (nodes-with-next) ---
 
 export const WorkflowNodeSchema = z.object({
   id: z.string().describe("Unique node identifier, used in 'next' and 'inputs' mappings"),
   type: z
     .string()
-    .describe("Executor type: 'agent-task', 'script', 'raw-llm', 'validate', 'property-match'"),
+    .describe(
+      "Executor type: 'agent-task', 'script', 'swarm-script', 'raw-llm', 'validate', 'property-match'",
+    ),
   label: z.string().optional().describe("Human-readable label for UI display"),
   config: z
     .record(z.string(), z.unknown())
     .describe(
       "Executor-specific config. For agent-task: { template, outputSchema?, agentId?, tags?, priority?, dir?, vcsRepo?, model? }. " +
+        "For swarm-script: { scriptName, scope?, pinHash?, args?, fsMode? }. " +
         "Values support {{interpolation}} from the node's inputs context. " +
         "NOTE: config.outputSchema on agent-task nodes validates the AGENT's raw JSON output, " +
         "while node-level outputSchema validates the EXECUTOR's return value ({taskId, taskOutput}).",
@@ -1287,6 +1301,52 @@ export const PromptTemplateHistorySchema = z.object({
 });
 export type PromptTemplateHistory = z.infer<typeof PromptTemplateHistorySchema>;
 
+// ============================================================================
+// Script Types
+// ============================================================================
+
+export const ScriptScopeSchema = z.enum(["global", "agent"]);
+export type ScriptScope = z.infer<typeof ScriptScopeSchema>;
+
+export const ScriptFsModeSchema = z.enum(["none", "workspace-rw"]);
+export type ScriptFsMode = z.infer<typeof ScriptFsModeSchema>;
+
+export const ScriptRecordSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  scope: ScriptScopeSchema,
+  scopeId: z.string().nullable(),
+  source: z.string(),
+  description: z.string(),
+  intent: z.string(),
+  signatureJson: z.string(),
+  argsJsonSchema: z.string().nullable(),
+  contentHash: z.string(),
+  version: z.number(),
+  isScratch: z.boolean(),
+  typeChecked: z.boolean(),
+  fsMode: ScriptFsModeSchema,
+  createdByAgentId: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type ScriptRecord = z.infer<typeof ScriptRecordSchema>;
+
+export const ScriptVersionRecordSchema = z.object({
+  id: z.string(),
+  scriptId: z.string(),
+  version: z.number(),
+  source: z.string(),
+  description: z.string(),
+  intent: z.string(),
+  signatureJson: z.string(),
+  contentHash: z.string(),
+  changedByAgentId: z.string().nullable(),
+  changedAt: z.string(),
+  changeReason: z.string().nullable(),
+});
+export type ScriptVersionRecord = z.infer<typeof ScriptVersionRecordSchema>;
+
 // ============================================================================
 // Skill Types
 // ============================================================================

package/src/utils/api-key.ts

@@ -0,0 +1,28 @@
+/**
+ * Centralized resolution of the swarm API key from the environment.
+ *
+ * Precedence:
+ *   1. AGENT_SWARM_API_KEY  (preferred — namespaced, safe to set globally)
+ *   2. API_KEY              (legacy — kept for back-compat with existing setups)
+ *
+ * All swarm code (CLI, server, hooks, worker, scripts) must read the key via
+ * `getApiKey()` so a user can configure either env var and have it work end
+ * to end. Direct access to `process.env.API_KEY` / `process.env.AGENT_SWARM_API_KEY`
+ * outside this module is enforced against by `scripts/check-api-key-boundary.sh`.
+ */
+
+type EnvLike = Record<string, string | undefined>;
+
+export function getApiKey(env: EnvLike = process.env): string {
+  return env.AGENT_SWARM_API_KEY ?? env.API_KEY ?? "";
+}
+
+/**
+ * Mirror a resolved key onto both env var names so any downstream code that
+ * still reads the raw env (third-party libraries, spawned subprocesses that
+ * inherit env, etc.) sees a consistent value.
+ */
+export function setApiKey(key: string, env: EnvLike = process.env): void {
+  env.AGENT_SWARM_API_KEY = key;
+  env.API_KEY = key;
+}

package/src/utils/error-tracker.ts

@@ -10,8 +10,21 @@ export interface ErrorSignal {
   timestamp: string;
 }
 
+/**
+ * Clamps a candidate reset timestamp (ms) to [now+60s, now+6h].
+ * Protects against past timestamps (clock skew) and absurdly far future values (malformed).
+ */
+function clampRateLimitResetMs(candidateMs: number): number {
+  const nowMs = Date.now();
+  const minMs = nowMs + 60_000;
+  const maxMs = nowMs + 6 * 60 * 60 * 1000;
+  return Math.min(Math.max(candidateMs, minMs), maxMs);
+}
+
 export class SessionErrorTracker {
   private errors: ErrorSignal[] = [];
+  /** Stashed reset time (ms) from the last rejected rate_limit_event in this session. */
+  private rateLimitResetAtMs: number | undefined;
 
   /** Record an error from an assistant message with message.error field */
   addApiError(errorCategory: string, message: string): void {
@@ -53,6 +66,45 @@ export class SessionErrorTracker {
     });
   }
 
+  /**
+   * Process a parsed rate_limit_event JSON object from the Claude CLI stream.
+   * Only stashes the reset time when status === "rejected"; ignores all others.
+   * Last call wins — if the CLI emits multiple events, the final rejected one is used.
+   *
+   * `resetsAt` is **seconds** since epoch (empirically verified; Linear description is wrong).
+   * Conversion to ms happens here at this single well-named boundary.
+   */
+  processRateLimitEvent(json: Record<string, unknown>): void {
+    try {
+      const info = json.rate_limit_info as Record<string, unknown> | undefined;
+      if (!info) return;
+
+      if (info.status !== "rejected") return;
+
+      const resetsAtSec = info.resetsAt;
+      if (typeof resetsAtSec !== "number" || !Number.isFinite(resetsAtSec) || resetsAtSec <= 0) {
+        console.warn(
+          `[rate_limit_event] Malformed resetsAt value: ${JSON.stringify(resetsAtSec)} — ignoring`,
+        );
+        return;
+      }
+
+      const resetsAtMs = resetsAtSec * 1000;
+      this.rateLimitResetAtMs = clampRateLimitResetMs(resetsAtMs);
+    } catch (err) {
+      console.warn(`[rate_limit_event] Failed to process event: ${err}`);
+    }
+  }
+
+  /**
+   * Returns the stashed rate limit reset time as an ISO string, or undefined
+   * if no rejected rate_limit_event was seen in this session.
+   */
+  getRateLimitResetAt(): string | undefined {
+    if (this.rateLimitResetAtMs === undefined) return undefined;
+    return new Date(this.rateLimitResetAtMs).toISOString();
+  }
+
   hasErrors(): boolean {
     return this.errors.length > 0;
   }
@@ -137,6 +189,12 @@ export function trackErrorFromJson(
   json: Record<string, unknown>,
   tracker: SessionErrorTracker,
 ): void {
+  // 0. Structured rate limit event — stash resetsAt for the three-tier resolver in runner.ts
+  if (json.type === "rate_limit_event") {
+    tracker.processRateLimitEvent(json);
+    return;
+  }
+
   // 1. Assistant messages with API errors (rate_limit, auth, billing, etc.)
   if (json.type === "assistant") {
     const message = json.message as Record<string, unknown> | undefined;

package/src/utils/page-session.ts

@@ -6,14 +6,16 @@
  *
  * Cookie payload: `{pageId, exp}` where `exp` is a unix seconds timestamp.
  * Wire shape: `${base64url(JSON.stringify(payload))}.${base64url(HMAC-SHA256(payload, secret))}`.
- * Secret resolution: `process.env.PAGE_SESSION_SECRET || process.env.API_KEY`
- * — the API_KEY fallback keeps existing dev setups working without forcing a
- * new env var. Verification is constant-time via `crypto.timingSafeEqual` so
- * we don't leak bits via signature-comparison timing.
+ * Secret resolution: `process.env.PAGE_SESSION_SECRET || getApiKey()`
+ * — the swarm API-key fallback keeps existing dev setups working without
+ * forcing a new env var. Verification is constant-time via
+ * `crypto.timingSafeEqual` so we don't leak bits via signature-comparison
+ * timing.
  *
  * Both functions are async because `crypto.subtle.sign` is async.
  */
 import { timingSafeEqual } from "node:crypto";
+import { getApiKey } from "./api-key";
 
 export interface PageSessionPayload {
   pageId: string;
@@ -43,12 +45,12 @@ function base64urlDecode(input: string): Uint8Array {
 
 /** Resolve the HMAC secret. */
 function getSecret(): string {
-  const secret = process.env.PAGE_SESSION_SECRET || process.env.API_KEY;
+  const secret = process.env.PAGE_SESSION_SECRET || getApiKey();
   if (!secret) {
     // Fail-closed: better to refuse to issue cookies than to mint with an
     // empty key (any attacker who learns the implementation can forge).
     throw new Error(
-      "page-session: neither PAGE_SESSION_SECRET nor API_KEY is set; refusing to sign/verify",
+      "page-session: neither PAGE_SESSION_SECRET nor swarm API key is set; refusing to sign/verify",
     );
   }
   return secret;

package/src/utils/secret-scrubber.ts

@@ -150,7 +150,7 @@ function snapshotEnv(): string {
   return parts.join("|");
 }
 
-function isSensitiveKey(key: string): boolean {
+export function isSensitiveKey(key: string): boolean {
   if (NON_SECRET_EXCEPTIONS.has(key)) return false;
   if (SENSITIVE_KEY_EXACT.has(key)) return true;
   for (const suffix of SENSITIVE_KEY_SUFFIXES) {
@@ -227,6 +227,27 @@ export function scrubSecrets(text: string | null | undefined): string {
   return out;
 }
 
+export function scrubObject<T>(value: T, seen = new WeakSet<object>()): T {
+  if (value === null || value === undefined) return value;
+  if (typeof value === "string") return scrubSecrets(value) as T;
+  if (typeof value !== "object") return value;
+
+  if (seen.has(value)) {
+    return "[Circular]" as T;
+  }
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    return value.map((item) => scrubObject(item, seen)) as T;
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    out[key] = scrubObject(child, seen);
+  }
+  return out as T;
+}
+
 /**
  * Force the env-value cache to rebuild on the next scrub call. Callers should
  * invoke this whenever the swarm_config is reloaded (`/internal/reload-config`

package/src/workflows/engine.ts

@@ -16,7 +16,7 @@ import { shouldSkipCooldown } from "./cooldown";
 import { findEntryNodes, getNextTargets, getSuccessors } from "./definition";
 import type { AsyncExecutorResult } from "./executors/base";
 import type { ExecutorRegistry } from "./executors/registry";
-import { resolveInputs } from "./input";
+import { getSecretInputKeys, redactSecretsForStorage, resolveInputs } from "./input";
 import { validateJsonSchema } from "./json-schema-validator";
 import { deepInterpolate } from "./template";
 import { runStepValidation, type ValidationRunResult } from "./validation";
@@ -97,7 +97,8 @@ export async function startWorkflowExecution(
   }
 
   const entryNodes = findEntryNodes(workflow.definition);
-  await walkGraph(workflow.definition, runId, ctx, entryNodes, registry, workflow.id);
+  const secretKeys = getSecretInputKeys(workflow.input);
+  await walkGraph(workflow.definition, runId, ctx, entryNodes, registry, workflow.id, secretKeys);
   return runId;
 }
 
@@ -125,6 +126,7 @@ export async function walkGraph(
   startNodes: WorkflowNode[],
   registry: ExecutorRegistry,
   workflowId?: string,
+  secretKeys: Set<string> = new Set(),
 ): Promise<void> {
   let nodeExecutionCount = 0;
   const completedNodeIds = new Set(getCompletedStepNodeIds(runId));
@@ -232,7 +234,7 @@ export async function walkGraph(
     // Execute all pending nodes in parallel
     const results = await Promise.all(
       pendingNodes.map((node) =>
-        executeStep(def, runId, ctx, node, registry, workflowId).catch(
+        executeStep(def, runId, ctx, node, registry, workflowId, secretKeys).catch(
           (_err): StepResult => ({
             outcome: "failed",
             successors: [],
@@ -382,6 +384,7 @@ async function executeStep(
   node: WorkflowNode,
   registry: ExecutorRegistry,
   workflowId?: string,
+  secretKeys: Set<string> = new Set(),
 ): Promise<StepResult> {
   // Use iteration-aware idempotency key to support loops.
   // Count existing steps for this node to determine the current iteration.
@@ -407,13 +410,18 @@ async function executeStep(
   }
 
   // 2. Create step
+  // Redact resolved secret values from the persisted input so credentials
+  // stored in `ctx.input` (resolved via `secret.*` or sensitive `${ENV}`
+  // references) don't leak through `get-workflow-run` or any other reader of
+  // the `workflow_run_steps` table. The live `ctx` is untouched — executors
+  // still see real values.
   const stepId = crypto.randomUUID();
   createWorkflowRunStep({
     id: stepId,
     runId,
     nodeId: node.id,
     nodeType: node.type,
-    input: ctx,
+    input: redactSecretsForStorage(ctx, secretKeys),
   });
 
   // Set idempotency key

package/src/workflows/executors/index.ts

@@ -12,6 +12,7 @@ export { PropertyMatchExecutor } from "./property-match";
 export { RawLlmExecutor } from "./raw-llm";
 export { createExecutorRegistry, ExecutorRegistry } from "./registry";
 export { ScriptExecutor } from "./script";
+export { SwarmScriptExecutor } from "./swarm-script";
 export { ValidateExecutor } from "./validate";
 export { VcsExecutor } from "./vcs";
 export { WaitExecutor } from "./wait";

package/src/workflows/executors/registry.ts

@@ -7,6 +7,7 @@ import { NotifyExecutor } from "./notify";
 import { PropertyMatchExecutor } from "./property-match";
 import { RawLlmExecutor } from "./raw-llm";
 import { ScriptExecutor } from "./script";
+import { SwarmScriptExecutor } from "./swarm-script";
 import { ValidateExecutor } from "./validate";
 import { VcsExecutor } from "./vcs";
 import { WaitExecutor } from "./wait";
@@ -68,6 +69,7 @@ export function createExecutorRegistry(deps: ExecutorDependencies): ExecutorRegi
   registry.register(new NotifyExecutor(deps));
   registry.register(new RawLlmExecutor(deps));
   registry.register(new ScriptExecutor(deps));
+  registry.register(new SwarmScriptExecutor(deps));
   registry.register(new VcsExecutor(deps));
   registry.register(new ValidateExecutor(deps));
 

package/src/workflows/executors/script.ts

@@ -72,9 +72,20 @@ export class ScriptExecutor extends BaseExecutor<
         nextPort: "success",
       };
     } catch (err) {
+      // Populate a structured output payload so the failure surfaces in
+      // get-workflow-run instead of leaving `output: null` and forcing operators
+      // to dig through logs. Mirrors the non-zero-exit path above and the
+      // litmus-gate `mustPass: false` mirror-into-output convention.
+      const message = err instanceof Error ? err.message : String(err);
+      const isTimeout = message.startsWith("Script timed out after");
       return {
         status: "failed",
-        error: `Script execution error: ${err instanceof Error ? err.message : String(err)}`,
+        error: `Script execution error: ${message}`,
+        output: {
+          exitCode: -1,
+          stdout: "",
+          stderr: isTimeout ? message : `Script execution error: ${message}`,
+        } as z.infer<typeof ScriptOutputSchema>,
       };
     }
   }