@desplega.ai/agent-swarm 1.80.1 → 1.80.3

package/README.md

@@ -34,6 +34,9 @@
   <a href="https://x.com/desplegalabs">
     <img src="https://img.shields.io/badge/𝕏-@desplegalabs-000?style=for-the-badge&logo=x&logoColor=white" alt="Follow on X">
   </a>
+  <a href="https://www.linkedin.com/company/desplega-labs/">
+    <img src="https://img.shields.io/badge/LinkedIn-Desplega%20Labs-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white" alt="Desplega Labs on LinkedIn">
+  </a>
 </p>
 
 > **What if your AI agents remembered everything, learned from every mistake, and got better with every task?**

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.80.1",
+    "version": "1.80.3",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.80.1",
+  "version": "1.80.3",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/src/agentmail/types.ts

@@ -43,6 +43,7 @@ export interface AgentMailWebhookPayload {
 
 export type AgentMailEventType =
   | "message.received"
+  | "message.received.unauthenticated"
   | "message.sent"
   | "message.delivered"
   | "message.bounced"

package/src/be/migrations/066_scripts_args_json_schema.sql

@@ -0,0 +1 @@
+ALTER TABLE scripts ADD COLUMN argsJsonSchema TEXT;

package/src/be/scripts/db.ts

@@ -20,6 +20,7 @@ type ScriptWriteArgs = ScriptIdentity & {
   description: string;
   intent: string;
   signatureJson: string;
+  argsJsonSchema?: string | null;
   isScratch?: boolean;
   typeChecked?: boolean;
   fsMode?: ScriptFsMode;
@@ -115,6 +116,7 @@ export function insertScript(args: ScriptWriteArgs): ScriptRecord {
           string,
           string,
           string,
+          string | null,
           string,
           number,
           number,
@@ -126,9 +128,9 @@ export function insertScript(args: ScriptWriteArgs): ScriptRecord {
       >(
         `INSERT INTO scripts (
           id, name, scope, scopeId, source, description, intent, signatureJson,
-          contentHash, isScratch, typeChecked, fsMode, createdByAgentId, createdAt, updatedAt
+          argsJsonSchema, contentHash, isScratch, typeChecked, fsMode, createdByAgentId, createdAt, updatedAt
         )
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         RETURNING *`,
       )
       .get(
@@ -140,6 +142,7 @@ export function insertScript(args: ScriptWriteArgs): ScriptRecord {
         args.description,
         args.intent,
         args.signatureJson,
+        args.argsJsonSchema ?? null,
         contentHash,
         isScratch,
         typeChecked,
@@ -193,10 +196,13 @@ export async function upsertScriptByName(args: ScriptWriteArgs): Promise<UpsertS
     const fsMode = args.fsMode ?? existing.fsMode;
     const isScratch = args.isScratch ?? existing.isScratch;
     const typeChecked = args.typeChecked ?? existing.typeChecked;
+    const argsJsonSchema =
+      args.argsJsonSchema !== undefined ? args.argsJsonSchema : existing.argsJsonSchema;
     const trackedMetadataChanged =
       args.description !== existing.description ||
       args.intent !== existing.intent ||
-      args.signatureJson !== existing.signatureJson;
+      args.signatureJson !== existing.signatureJson ||
+      argsJsonSchema !== existing.argsJsonSchema;
     const promotedFromScratch = existing.isScratch && !isScratch;
     if (
       fsMode !== existing.fsMode ||
@@ -205,9 +211,12 @@ export async function upsertScriptByName(args: ScriptWriteArgs): Promise<UpsertS
       trackedMetadataChanged
     ) {
       const row = getDb()
-        .prepare<ScriptRow, [string, string, string, number, number, string, string, string]>(
+        .prepare<
+          ScriptRow,
+          [string, string, string, string | null, number, number, string, string, string]
+        >(
           `UPDATE scripts
-          SET description = ?, intent = ?, signatureJson = ?,
+          SET description = ?, intent = ?, signatureJson = ?, argsJsonSchema = ?,
             isScratch = ?, typeChecked = ?, fsMode = ?, updatedAt = ?
           WHERE id = ?
           RETURNING *`,
@@ -216,6 +225,7 @@ export async function upsertScriptByName(args: ScriptWriteArgs): Promise<UpsertS
           args.description,
           args.intent,
           args.signatureJson,
+          argsJsonSchema ?? null,
           isScratch ? 1 : 0,
           typeChecked ? 1 : 0,
           fsMode,
@@ -247,16 +257,31 @@ export async function upsertScriptByName(args: ScriptWriteArgs): Promise<UpsertS
   const fsMode = args.fsMode ?? existing.fsMode;
   const isScratch = args.isScratch ?? existing.isScratch;
   const typeChecked = args.typeChecked ?? existing.typeChecked;
+  const argsJsonSchema =
+    args.argsJsonSchema !== undefined ? args.argsJsonSchema : existing.argsJsonSchema;
 
   const txn = getDb().transaction(() => {
     const row = getDb()
       .prepare<
         ScriptRow,
-        [string, string, string, string, string, number, number, number, string, string, string]
+        [
+          string,
+          string,
+          string,
+          string,
+          string | null,
+          string,
+          number,
+          number,
+          number,
+          string,
+          string,
+          string,
+        ]
       >(
         `UPDATE scripts
-        SET source = ?, description = ?, intent = ?, signatureJson = ?, contentHash = ?,
-          version = ?, isScratch = ?, typeChecked = ?, fsMode = ?, updatedAt = ?
+        SET source = ?, description = ?, intent = ?, signatureJson = ?, argsJsonSchema = ?,
+          contentHash = ?, version = ?, isScratch = ?, typeChecked = ?, fsMode = ?, updatedAt = ?
         WHERE id = ?
         RETURNING *`,
       )
@@ -265,6 +290,7 @@ export async function upsertScriptByName(args: ScriptWriteArgs): Promise<UpsertS
         args.description,
         args.intent,
         args.signatureJson,
+        argsJsonSchema ?? null,
         contentHash,
         newVersion,
         isScratch ? 1 : 0,

package/src/be/scripts/embeddings.ts

@@ -22,6 +22,7 @@ type ScriptEmbeddingCandidateRow = ScriptEmbeddingRow & {
   description: string;
   intent: string;
   signatureJson: string;
+  argsJsonSchema: string | null;
   contentHash: string;
   version: number;
   isScratch: number;
@@ -63,6 +64,7 @@ function rowToScript(row: ScriptEmbeddingCandidateRow): ScriptRecord {
     description: row.description,
     intent: row.intent,
     signatureJson: row.signatureJson,
+    argsJsonSchema: row.argsJsonSchema ?? null,
     contentHash: row.contentHash,
     version: row.version,
     isScratch: row.isScratch === 1,

package/src/be/scripts/extract-schema.ts

@@ -0,0 +1,55 @@
+/**
+ * Server-side helper: spawns a subprocess to extract the argsJsonSchema
+ * from a user script's `argsSchema` Zod export. Returns the JSON Schema
+ * serialized as a string, or null if the script has no argsSchema or
+ * if extraction fails.
+ *
+ * Extraction is best-effort and non-blocking — failures return null.
+ */
+
+const TIMEOUT_MS = 5_000;
+
+function extractorPath(): string {
+  return new URL("../../scripts-runtime/extract-args-schema.ts", import.meta.url).pathname;
+}
+
+export async function extractArgsJsonSchema(source: string): Promise<string | null> {
+  const tmpdir = `${process.env.TMPDIR ?? "/tmp"}/schema-extract-${crypto.randomUUID()}`;
+
+  try {
+    await Bun.$`mkdir -p ${tmpdir}`.quiet();
+
+    const sourceFile = `${tmpdir}/source.ts`;
+    const resultFile = `${tmpdir}/result.json`;
+    await Bun.write(sourceFile, source);
+
+    const proc = Bun.spawn(["bun", "run", extractorPath()], {
+      env: {
+        PATH: process.env.PATH ?? "/usr/bin:/bin",
+        HOME: process.env.HOME ?? "/tmp",
+        TMPDIR: tmpdir,
+        SWARM_SCHEMA_SOURCE_FILE: sourceFile,
+        SWARM_SCHEMA_RESULT_FILE: resultFile,
+        SWARM_SCHEMA_TMPDIR: tmpdir,
+      },
+      cwd: tmpdir,
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+
+    const timeout = setTimeout(() => proc.kill(), TIMEOUT_MS);
+    const exitCode = await proc.exited.catch(() => 1);
+    clearTimeout(timeout);
+
+    if (exitCode !== 0) return null;
+
+    const result = await Bun.file(resultFile).text();
+    const parsed: unknown = JSON.parse(result);
+    if (parsed === null) return null;
+    return JSON.stringify(parsed);
+  } catch {
+    return null;
+  } finally {
+    await Bun.$`rm -rf ${tmpdir}`.quiet().nothrow();
+  }
+}

package/src/be/scripts/typecheck.ts

@@ -120,6 +120,10 @@ function createCompilerHost(
     return files.get(normalized) ?? ts.sys.readFile(fileName);
   };
 
+  // Resolve external packages (e.g. "zod") from the project root rather than
+  // the virtual path "/virtual/..." so TypeScript can find real node_modules.
+  const projectBase = new URL("../../index.ts", import.meta.url).pathname;
+
   host.resolveModuleNames = (moduleNames, containingFile) =>
     moduleNames.map((moduleName) => {
       if (moduleName === "./user-script") {
@@ -131,7 +135,9 @@ function createCompilerHost(
       if (moduleName === "stdlib") {
         return { resolvedFileName: STDLIB_FILE, extension: ts.Extension.Dts };
       }
-      return ts.resolveModuleName(moduleName, containingFile, options, host).resolvedModule;
+      // For external packages, resolve from project root so node_modules is found
+      const base = containingFile.startsWith("/virtual/") ? projectBase : containingFile;
+      return ts.resolveModuleName(moduleName, base, options, host).resolvedModule;
     });
 
   // In compiled binary mode, TypeScript's lib .d.ts files live alongside

package/src/commands/runner.ts

@@ -368,7 +368,17 @@ const SWARM_TOOL_LABELS: Record<string, string | null> = {
   "inject-learning": "🧠 Storing learning",
   "memory-search": "🧠 Searching memory",
   "memory-get": "🧠 Retrieving memory",
+  "memory-delete": "🧠 Deleting memory",
   "update-profile": "🪪 Updating profile",
+  // Users
+  "manage-user": "👤 Managing user",
+  "resolve-user": "👤 Resolving user",
+  // Key-value store
+  "kv-get": "🔑 Reading KV value",
+  "kv-set": "🔑 Setting KV value",
+  "kv-list": "🔑 Listing KV keys",
+  "kv-delete": "🔑 Deleting KV value",
+  "kv-incr": "🔑 Incrementing KV value",
   // Slack
   "slack-post": "💬 Posting to Slack",
   "slack-start-thread": "💬 Starting Slack thread",
@@ -388,20 +398,37 @@ const SWARM_TOOL_LABELS: Record<string, string | null> = {
   "get-workflow": "⚙️ Checking workflow",
   "list-workflows": "⚙️ Listing workflows",
   "create-workflow": "⚙️ Creating workflow",
+  "update-workflow": "⚙️ Updating workflow",
+  "delete-workflow": "⚙️ Deleting workflow",
+  "patch-workflow": "⚙️ Patching workflow",
+  "patch-workflow-node": "⚙️ Patching workflow node",
+  "get-workflow-run": "⚙️ Checking workflow run",
+  "list-workflow-runs": "⚙️ Listing workflow runs",
+  "cancel-workflow-run": "⚙️ Cancelling workflow run",
+  "retry-workflow-run": "⚙️ Retrying workflow run",
   // Skills
   "skill-search": "🔎 Searching skills",
   "skill-install": "📦 Installing skill",
   "skill-install-remote": "📦 Installing remote skill",
   "skill-get": "📦 Getting skill details",
   "skill-list": "📦 Listing skills",
+  "skill-create": "📦 Creating skill",
+  "skill-update": "📦 Updating skill",
+  "skill-delete": "📦 Deleting skill",
+  "skill-publish": "📦 Publishing skill",
+  "skill-uninstall": "📦 Uninstalling skill",
+  "skill-sync-remote": "📦 Syncing remote skills",
   // Config
   "get-config": "⚙️ Reading config",
   "set-config": "⚙️ Setting config",
   "list-config": "⚙️ Listing config",
+  "delete-config": "⚙️ Deleting config",
   // Schedules
   "create-schedule": "📅 Creating schedule",
   "list-schedules": "📅 Listing schedules",
   "run-schedule-now": "📅 Running schedule",
+  "update-schedule": "📅 Updating schedule",
+  "delete-schedule": "📅 Deleting schedule",
   // Context
   "context-diff": "📜 Viewing context diff",
   "context-history": "📜 Viewing context history",
@@ -422,10 +449,34 @@ const SWARM_TOOL_LABELS: Record<string, string | null> = {
   "script-query-types": "📜 Reading script types",
 };
 
-/** Convert kebab-case to sentence case: "get-task-details" → "Get task details" */
+/** Words that keep specific casing when humanizing tool names. */
+const TOOL_NAME_ACRONYMS: Record<string, string> = {
+  mcp: "MCP",
+  kv: "KV",
+  api: "API",
+  url: "URL",
+  id: "ID",
+};
+
+/**
+ * Convert kebab/snake-case to sentence case, preserving known acronyms.
+ * "get-task-details" → "Get task details"; "mcp-server-create" → "MCP server create".
+ */
 export function humanizeToolName(name: string): string {
   if (!name) return name;
-  return name.charAt(0).toUpperCase() + name.slice(1).replaceAll("-", " ");
+  const words = name
+    .replaceAll("_", " ")
+    .replaceAll("-", " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((w) => TOOL_NAME_ACRONYMS[w.toLowerCase()] ?? w);
+  const first = words[0];
+  if (!first) return name;
+  const head = TOOL_NAME_ACRONYMS[first.toLowerCase()]
+    ? first
+    : first.charAt(0).toUpperCase() + first.slice(1);
+  return [head, ...words.slice(1)].join(" ");
 }
 
 /**
@@ -501,7 +552,7 @@ export function toolCallToProgress(toolName: string, args: unknown): string | nu
       if (label === null) return null;
       if (label) return label;
 
-      return `🔧 ${toolName}`;
+      return `🔧 ${humanizeToolName(toolName)}`;
     }
   }
 }
@@ -2681,15 +2732,35 @@ async function checkCompletedProcesses(
           credentialInfo &&
           /rate.?limit|hit your limit|usage[ _-]?limit|too many requests/i.test(failureReason)
         ) {
-          // Try to extract reset time from the error message (e.g. "resets 3pm (UTC)")
-          const parsedResetTime = parseRateLimitResetTime(failureReason);
-          const defaultCooldownMs = 5 * 60 * 1000;
-          const rateLimitedUntil =
-            parsedResetTime ?? new Date(Date.now() + defaultCooldownMs).toISOString();
-          if (parsedResetTime) {
+          // Three-tier reset-time resolver (most to least precise):
+          // Tier 1: structured rate_limit_event from Claude CLI (resetsAt epoch sec)
+          // Tier 2: regex on the error message (e.g. "resets 3pm (UTC)")
+          // Tier 3: 5-min hard fallback — only when both structured and regex fail
+          // Tiers 1 & 2 are clamped to [now+60s, now+6h] at their source.
+          const clampResetTime = (isoString: string): string => {
+            const nowMs = Date.now();
+            const minMs = nowMs + 60_000;
+            const maxMs = nowMs + 6 * 60 * 60 * 1000;
+            const candidateMs = new Date(isoString).getTime();
+            return new Date(Math.min(Math.max(candidateMs, minMs), maxMs)).toISOString();
+          };
+
+          let rateLimitedUntil: string;
+          if (result.rateLimitResetAt) {
+            rateLimitedUntil = clampResetTime(result.rateLimitResetAt);
             console.log(
-              `[credentials] Parsed rate limit reset time from error: ${parsedResetTime}`,
+              `[credentials] Rate limit reset from rate_limit_event: ${rateLimitedUntil}`,
             );
+          } else {
+            const parsedResetTime = parseRateLimitResetTime(failureReason);
+            if (parsedResetTime) {
+              rateLimitedUntil = clampResetTime(parsedResetTime);
+              console.log(
+                `[credentials] Parsed rate limit reset time from error: ${rateLimitedUntil}`,
+              );
+            } else {
+              rateLimitedUntil = new Date(Date.now() + 5 * 60 * 1000).toISOString();
+            }
           }
           reportKeyRateLimit(
             apiConfig.apiUrl,

package/src/http/scripts.ts

@@ -4,6 +4,7 @@ import { getAgentById } from "../be/db";
 import { createEvent } from "../be/events";
 import { deleteScript, getScript, upsertScriptByName } from "../be/scripts/db";
 import { searchScripts } from "../be/scripts/embeddings";
+import { extractArgsJsonSchema } from "../be/scripts/extract-schema";
 import { SCRIPT_SDK_TYPES, SCRIPT_STDLIB_TYPES, typecheckScript } from "../be/scripts/typecheck";
 import { extractScriptSignature } from "../scripts-runtime/extract-signature";
 import { runScript } from "../scripts-runtime/loader";
@@ -217,6 +218,7 @@ export async function handleScripts(
       parsed.body.scope === "global"
         ? getScript({ name: parsed.body.name, scope: "agent", scopeId: agent.id })
         : null;
+    const argsJsonSchema = await extractArgsJsonSchema(parsed.body.source);
     const result = await upsertScriptByName({
       name: parsed.body.name,
       scope: parsed.body.scope,
@@ -225,6 +227,7 @@ export async function handleScripts(
       description: parsed.body.description,
       intent: parsed.body.intent,
       signatureJson: signatureJsonFor(parsed.body.source),
+      argsJsonSchema,
       fsMode: parsed.body.fsMode,
       agentId: agent.id,
       isScratch: false,
@@ -331,6 +334,9 @@ export async function handleScripts(
       results: matches.map(({ script, score }) => ({
         name: script.name,
         signature: JSON.parse(script.signatureJson),
+        argsJsonSchema: script.argsJsonSchema
+          ? (JSON.parse(script.argsJsonSchema) as unknown)
+          : null,
         description: script.description,
         score,
       })),
@@ -351,6 +357,7 @@ export async function handleScripts(
     }
     json(res, {
       signature: JSON.parse(script.signatureJson),
+      argsJsonSchema: script.argsJsonSchema ? (JSON.parse(script.argsJsonSchema) as unknown) : null,
       sdkTypes: SCRIPT_SDK_TYPES,
       stdlibTypes: SCRIPT_STDLIB_TYPES,
     });

package/src/http/webhooks.ts

@@ -412,9 +412,18 @@ export async function handleWebhooks(
 
     try {
       switch (payload.event_type) {
+        case "message.received.unauthenticated":
+          console.warn(
+            `[AgentMail] Received unauthenticated message - treating as received event for inbox ${payload.message?.inbox_id ?? "unknown"}`,
+          );
+
+          await handleMessageReceived(payload);
+          break;
+
         case "message.received":
           await handleMessageReceived(payload);
           break;
+
         default:
           console.log(`[AgentMail] Ignoring event type: ${payload.event_type}`);
       }

package/src/http/workflows.ts

@@ -341,24 +341,11 @@ export async function handleWorkflows(
     }
     const rawBody = Buffer.concat(chunks).toString();
 
-    // Validate JSON before processing (but pass raw string for HMAC)
-    try {
-      if (rawBody) JSON.parse(rawBody);
-    } catch {
-      jsonError(res, "Invalid JSON body", 400);
-      return true;
-    }
-
-    const signature =
-      (req.headers["x-hub-signature-256"] as string | undefined) ??
-      (req.headers["x-signature"] as string | undefined);
-
     try {
       const result = await handleWebhookTrigger(
         workflowId,
-        rawBody, // Raw body string — used for HMAC verification + passed as triggerData
-        signature,
-        signature,
+        rawBody, // Raw body string — HMAC is verified against raw bytes; JSON parsing happens inside
+        req.headers, // Full header bag — signature header resolved per trigger config
         getExecutorRegistry(),
       );
       json(res, result, 201);

package/src/providers/claude-adapter.ts

@@ -458,6 +458,7 @@ class ClaudeSession implements ProviderSession {
       cost: lastCost,
       isError: (exitCode ?? 1) !== 0,
       failureReason,
+      rateLimitResetAt: this.errorTracker.getRateLimitResetAt(),
     };
   }
 

package/src/providers/types.ts

@@ -116,6 +116,14 @@ export interface ProviderResult {
   errorCategory?: string;
   /** Human-readable failure reason built from error tracking. */
   failureReason?: string;
+  /**
+   * ISO timestamp of the rate limit reset time, parsed from a structured
+   * `rate_limit_event` line in the Claude CLI stream. Only set by the Claude
+   * adapter when a `status: "rejected"` event is present. Already clamped to
+   * [now+60s, now+6h] at the source. The runner uses this as tier-1 of the
+   * three-tier cooldown resolver.
+   */
+  rateLimitResetAt?: string;
 }
 
 /** Behavioral traits that govern prompt assembly and feature gating. */

package/src/scripts-runtime/eval-harness.ts

@@ -31,7 +31,31 @@ try {
     throw new Error("Swarm script must export a default function");
   }
 
-  const result = await mod.default(parsedArgs, ctx);
+  let validatedArgs = parsedArgs;
+  if (mod.argsSchema && typeof mod.argsSchema === "object" && "parse" in mod.argsSchema) {
+    try {
+      // biome-ignore lint/suspicious/noExplicitAny: argsSchema is a Zod schema at runtime
+      validatedArgs = (mod.argsSchema as any).parse(parsedArgs);
+    } catch (err) {
+      // Format ZodError issues into a readable message
+      if (
+        err &&
+        typeof err === "object" &&
+        "issues" in err &&
+        Array.isArray((err as { issues: unknown[] }).issues)
+      ) {
+        const issues = (
+          err as { issues: Array<{ path: (string | number)[]; message: string }> }
+        ).issues
+          .map((i) => `  ${i.path.length ? i.path.join(".") : "(root)"}: ${i.message}`)
+          .join("\n");
+        throw new Error(`argsSchema validation failed:\n${issues}`);
+      }
+      throw err;
+    }
+  }
+
+  const result = await mod.default(validatedArgs, ctx);
   await Bun.write(requiredEnv("SWARM_SCRIPT_RESULT_FILE"), JSON.stringify(result ?? null));
 } catch (error) {
   console.error(error instanceof Error ? error.stack || error.message : String(error));

package/src/scripts-runtime/executors/native.ts

@@ -90,6 +90,9 @@ async function writeBareImportShims(tmpdir: string): Promise<void> {
   }
   await writeBareImportShim(tmpdir, "stdlib", new URL("../stdlib/index.ts", import.meta.url));
   await writeBareImportShim(tmpdir, "swarm-sdk", new URL("../swarm-sdk.ts", import.meta.url));
+  // Allow `import { z } from "zod"` in user scripts (for argsSchema definitions).
+  const zodEntry = Bun.resolveSync("zod", import.meta.dir);
+  await writeBareImportShim(tmpdir, "zod", new URL(`file://${zodEntry}`));
 }
 
 function harnessCommand(harnessPath: string, input: ExecutorInput): string[] {

package/src/scripts-runtime/extract-args-schema.ts

@@ -0,0 +1,69 @@
+/**
+ * Subprocess script: extracts the argsJsonSchema from a user script module.
+ * Spawned by src/be/scripts/extract-schema.ts during script_upsert.
+ *
+ * Env vars (all required):
+ *   SWARM_SCHEMA_SOURCE_FILE  path to the script source file
+ *   SWARM_SCHEMA_RESULT_FILE  path where JSON Schema (or "null") is written
+ *   SWARM_SCHEMA_TMPDIR       tmpdir used for shims + the user module
+ */
+import { toJSONSchema } from "zod";
+
+async function createShims(tmpdir: string): Promise<void> {
+  const zodEntry = Bun.resolveSync("zod", import.meta.dir);
+  const shims: [string, URL][] = [
+    ["stdlib", new URL("./stdlib/index.ts", import.meta.url)],
+    ["swarm-sdk", new URL("./swarm-sdk.ts", import.meta.url)],
+    ["zod", new URL(`file://${zodEntry}`)],
+  ];
+  for (const [name, url] of shims) {
+    const dir = `${tmpdir}/node_modules/${name}`;
+    await Bun.$`mkdir -p ${dir}`.quiet();
+    await Bun.write(`${dir}/package.json`, JSON.stringify({ type: "module", main: "index.ts" }));
+    await Bun.write(`${dir}/index.ts`, `export * from ${JSON.stringify(url.href)};\n`);
+  }
+}
+
+const sourceFile = process.env.SWARM_SCHEMA_SOURCE_FILE;
+const resultFile = process.env.SWARM_SCHEMA_RESULT_FILE;
+const tmpdir = process.env.SWARM_SCHEMA_TMPDIR;
+
+if (!sourceFile || !resultFile || !tmpdir) {
+  process.stderr.write("extract-args-schema: missing required env vars\n");
+  process.exit(1);
+}
+
+try {
+  await createShims(tmpdir);
+
+  const source = await Bun.file(sourceFile).text();
+  const userModulePath = `${tmpdir}/user-script.ts`;
+  await Bun.write(userModulePath, source);
+
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(userModulePath)) as Record<string, unknown>;
+  } catch {
+    // Import failed (e.g. unresolvable imports) — not an error, just no schema
+    await Bun.write(resultFile, "null");
+    process.exit(0);
+  }
+
+  if (!mod.argsSchema || typeof mod.argsSchema !== "object") {
+    await Bun.write(resultFile, "null");
+    process.exit(0);
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: argsSchema is a Zod schema at runtime
+  const schema = toJSONSchema(mod.argsSchema as any);
+  await Bun.write(resultFile, JSON.stringify(schema));
+  process.exit(0);
+} catch (err) {
+  process.stderr.write(
+    `extract-args-schema: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+  try {
+    await Bun.write(resultFile, "null");
+  } catch {}
+  process.exit(0);
+}

package/src/scripts-runtime/import-allowlist.ts

@@ -1,6 +1,6 @@
 import ts from "typescript";
 
-const ALLOWED_BARE_IMPORTS = new Set(["swarm-sdk", "stdlib"]);
+const ALLOWED_BARE_IMPORTS = new Set(["swarm-sdk", "stdlib", "zod"]);
 const FORBIDDEN_HINTS = new Set(["node:", "bun:", "fs", "child_process", "crypto", "bun:sqlite"]);
 
 export type ImportAllowlistResult =