@desplega.ai/agent-swarm 1.80.1 → 1.80.2

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.80.1",
+    "version": "1.80.2",
     "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.2",
   "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/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/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 =

package/src/tests/error-tracker.test.ts

@@ -6,6 +6,38 @@ import {
   trackErrorFromJson,
 } from "../utils/error-tracker";
 
+describe("SessionErrorTracker — getRateLimitResetAt", () => {
+  test("returns undefined when no rate_limit_event was processed", () => {
+    const tracker = new SessionErrorTracker();
+    expect(tracker.getRateLimitResetAt()).toBeUndefined();
+  });
+
+  test("returns ISO string after a rejected rate_limit_event", () => {
+    const tracker = new SessionErrorTracker();
+    const futureResetsAtSec = Math.floor(Date.now() / 1000) + 3600;
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "rejected", resetsAt: futureResetsAtSec },
+    });
+    const result = tracker.getRateLimitResetAt();
+    expect(result).toBeDefined();
+    expect(() => new Date(result!).toISOString()).not.toThrow();
+  });
+
+  test("returns undefined after only allowed/allowed_warning events", () => {
+    const tracker = new SessionErrorTracker();
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "allowed", resetsAt: 1779202200 },
+    });
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "allowed_warning", resetsAt: 1779202200 },
+    });
+    expect(tracker.getRateLimitResetAt()).toBeUndefined();
+  });
+});
+
 describe("SessionErrorTracker", () => {
   test("hasErrors returns false when no errors tracked", () => {
     const tracker = new SessionErrorTracker();
@@ -263,6 +295,18 @@ describe("trackErrorFromJson", () => {
     trackErrorFromJson({ type: "content_block_delta", delta: {} }, tracker);
     expect(tracker.hasErrors()).toBe(false);
   });
+
+  test("rate_limit_event is not treated as an error signal", () => {
+    const tracker = new SessionErrorTracker();
+    trackErrorFromJson(
+      {
+        type: "rate_limit_event",
+        rate_limit_info: { status: "rejected", resetsAt: 1779202200 },
+      },
+      tracker,
+    );
+    expect(tracker.hasErrors()).toBe(false);
+  });
 });
 
 describe("parseStderrForErrors", () => {

package/src/tests/rate-limit-event.test.ts

@@ -0,0 +1,292 @@
+import { describe, expect, test } from "bun:test";
+import { SessionErrorTracker, trackErrorFromJson } from "../utils/error-tracker";
+
+// Verbatim fixture from Linear CAI-1279 (session logs for task b7fbbdb9-4922-41d9-88ec-21febd6c4fec)
+const FIXTURE_REJECTED = {
+  type: "rate_limit_event",
+  rate_limit_info: {
+    status: "rejected",
+    resetsAt: 1779202200, // seconds since epoch — 2026-05-19T14:50:00Z
+    rateLimitType: "five_hour",
+    overageStatus: "rejected",
+    overageDisabledReason: "group_zero_credit_limit",
+    isUsingOverage: false,
+  },
+  uuid: "ff6e5299-429c-4fcb-ab34-0ce4e8fa6202",
+  session_id: "69dbe5a1-1130-45eb-983f-58a7a13c9c3c",
+};
+
+describe("SessionErrorTracker — rate_limit_event processing", () => {
+  test("stashes resetsAt (seconds) correctly as ms — verbatim CAI-1279 fixture", () => {
+    const tracker = new SessionErrorTracker();
+    tracker.processRateLimitEvent(FIXTURE_REJECTED);
+
+    const result = tracker.getRateLimitResetAt();
+    expect(result).toBeDefined();
+
+    // resetsAt: 1779202200 sec → 2026-05-19T14:50:00.000Z
+    // But since we clamp to [now+60s, now+6h] and this is a past timestamp,
+    // the value will be clamped to now+60s. What matters is the sec→ms conversion works.
+    // We verify the unit is correct by checking that 1779202200 * 1000 = ms,
+    // which is NOT the same as treating it as ms (would be 1970-01-21).
+    const parsedMs = new Date(result!).getTime();
+    const nowMs = Date.now();
+    expect(parsedMs).toBeGreaterThanOrEqual(nowMs + 59_000); // clamped to at least now+60s
+    expect(parsedMs).toBeLessThanOrEqual(nowMs + 7 * 60 * 60 * 1000); // not absurdly far
+  });
+
+  test("resetsAt treated as seconds, not milliseconds (unit conversion boundary)", () => {
+    const tracker = new SessionErrorTracker();
+    // A future resetsAt value (in seconds) — 1 hour from now
+    const oneHourFromNowSec = Math.floor(Date.now() / 1000) + 3600;
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: {
+        status: "rejected",
+        resetsAt: oneHourFromNowSec,
+      },
+    });
+
+    const result = tracker.getRateLimitResetAt();
+    expect(result).toBeDefined();
+
+    const parsedMs = new Date(result!).getTime();
+    const nowMs = Date.now();
+    // Should be ~1h from now (not 1970 if treated as ms, not year 57,000 if multiplied wrong)
+    expect(parsedMs).toBeGreaterThanOrEqual(nowMs + 50 * 60_000); // at least 50 min from now
+    expect(parsedMs).toBeLessThanOrEqual(nowMs + 70 * 60_000); // at most 70 min from now
+  });
+
+  test("status: rejected → stashes resetsAt", () => {
+    const tracker = new SessionErrorTracker();
+    const futureResetsAtSec = Math.floor(Date.now() / 1000) + 3600;
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "rejected", resetsAt: futureResetsAtSec },
+    });
+    expect(tracker.getRateLimitResetAt()).toBeDefined();
+  });
+
+  test("status: allowed → does NOT stash (no cooldown needed)", () => {
+    const tracker = new SessionErrorTracker();
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "allowed", resetsAt: 1779202200 },
+    });
+    expect(tracker.getRateLimitResetAt()).toBeUndefined();
+  });
+
+  test("status: allowed_warning → does NOT stash", () => {
+    const tracker = new SessionErrorTracker();
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "allowed_warning", resetsAt: 1779202200 },
+    });
+    expect(tracker.getRateLimitResetAt()).toBeUndefined();
+  });
+
+  test("malformed event (missing rate_limit_info) → does NOT stash, no throw", () => {
+    const tracker = new SessionErrorTracker();
+    tracker.processRateLimitEvent({ type: "rate_limit_event" });
+    expect(tracker.getRateLimitResetAt()).toBeUndefined();
+  });
+
+  test("malformed event (resetsAt is string) → does NOT stash, no throw", () => {
+    const tracker = new SessionErrorTracker();
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "rejected", resetsAt: "not-a-number" },
+    });
+    expect(tracker.getRateLimitResetAt()).toBeUndefined();
+  });
+
+  test("malformed event (resetsAt is negative) → does NOT stash", () => {
+    const tracker = new SessionErrorTracker();
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "rejected", resetsAt: -1 },
+    });
+    expect(tracker.getRateLimitResetAt()).toBeUndefined();
+  });
+
+  test("resetsAt already in the past → clamped to now+60s (clock skew defense)", () => {
+    const tracker = new SessionErrorTracker();
+    // Use a known-past timestamp (year 2020)
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "rejected", resetsAt: 1577836800 }, // 2020-01-01T00:00:00Z
+    });
+
+    const result = tracker.getRateLimitResetAt();
+    expect(result).toBeDefined();
+    const parsedMs = new Date(result!).getTime();
+    const nowMs = Date.now();
+    expect(parsedMs).toBeGreaterThanOrEqual(nowMs + 59_000);
+    expect(parsedMs).toBeLessThanOrEqual(nowMs + 65_000);
+  });
+
+  test("resetsAt absurdly far in future → clamped to now+6h (malformed defense)", () => {
+    const tracker = new SessionErrorTracker();
+    // Year 2099 in seconds
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "rejected", resetsAt: 4102444800 }, // 2100-01-01 in seconds
+    });
+
+    const result = tracker.getRateLimitResetAt();
+    expect(result).toBeDefined();
+    const parsedMs = new Date(result!).getTime();
+    const nowMs = Date.now();
+    const sixHoursMs = 6 * 60 * 60 * 1000;
+    expect(parsedMs).toBeLessThanOrEqual(nowMs + sixHoursMs + 1000); // within 6h (+1s tolerance)
+  });
+
+  test("multiple rate_limit_event lines → last rejected one wins", () => {
+    const tracker = new SessionErrorTracker();
+    const firstResetsAtSec = Math.floor(Date.now() / 1000) + 1800; // 30 min from now
+    const secondResetsAtSec = Math.floor(Date.now() / 1000) + 3600; // 60 min from now
+
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "rejected", resetsAt: firstResetsAtSec },
+    });
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "rejected", resetsAt: secondResetsAtSec },
+    });
+
+    const result = tracker.getRateLimitResetAt();
+    expect(result).toBeDefined();
+    const parsedMs = new Date(result!).getTime();
+    const nowMs = Date.now();
+    // Should reflect the SECOND event (~60 min), not the first (~30 min)
+    expect(parsedMs).toBeGreaterThanOrEqual(nowMs + 55 * 60_000);
+    expect(parsedMs).toBeLessThanOrEqual(nowMs + 65 * 60_000);
+  });
+
+  test("allowed event between two rejected events → last rejected wins", () => {
+    const tracker = new SessionErrorTracker();
+    const firstSec = Math.floor(Date.now() / 1000) + 1800;
+    const secondSec = Math.floor(Date.now() / 1000) + 3600;
+
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "rejected", resetsAt: firstSec },
+    });
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "allowed", resetsAt: 9999999999 }, // should be ignored
+    });
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "rejected", resetsAt: secondSec },
+    });
+
+    const result = tracker.getRateLimitResetAt();
+    expect(result).toBeDefined();
+    const parsedMs = new Date(result!).getTime();
+    const nowMs = Date.now();
+    // Should reflect the third (second rejected) event (~60 min)
+    expect(parsedMs).toBeGreaterThanOrEqual(nowMs + 55 * 60_000);
+    expect(parsedMs).toBeLessThanOrEqual(nowMs + 65 * 60_000);
+  });
+
+  test("no rate_limit_event at all → getRateLimitResetAt returns undefined", () => {
+    const tracker = new SessionErrorTracker();
+    expect(tracker.getRateLimitResetAt()).toBeUndefined();
+  });
+});
+
+describe("trackErrorFromJson — rate_limit_event routing", () => {
+  test("routes rate_limit_event to processRateLimitEvent, stashes reset time", () => {
+    const tracker = new SessionErrorTracker();
+    const futureResetsAtSec = Math.floor(Date.now() / 1000) + 3600;
+
+    trackErrorFromJson(
+      {
+        type: "rate_limit_event",
+        rate_limit_info: { status: "rejected", resetsAt: futureResetsAtSec },
+      },
+      tracker,
+    );
+
+    expect(tracker.getRateLimitResetAt()).toBeDefined();
+    // rate_limit_event itself is NOT an error signal — it's informational
+    expect(tracker.hasErrors()).toBe(false);
+  });
+
+  test("rate_limit_event with allowed status → no reset stashed, no errors", () => {
+    const tracker = new SessionErrorTracker();
+    trackErrorFromJson(
+      {
+        type: "rate_limit_event",
+        rate_limit_info: { status: "allowed", resetsAt: 1779202200 },
+      },
+      tracker,
+    );
+
+    expect(tracker.getRateLimitResetAt()).toBeUndefined();
+    expect(tracker.hasErrors()).toBe(false);
+  });
+
+  test("rate_limit_event does not block subsequent event processing", () => {
+    const tracker = new SessionErrorTracker();
+    const futureResetsAtSec = Math.floor(Date.now() / 1000) + 3600;
+
+    trackErrorFromJson(
+      {
+        type: "rate_limit_event",
+        rate_limit_info: { status: "rejected", resetsAt: futureResetsAtSec },
+      },
+      tracker,
+    );
+    trackErrorFromJson(
+      { type: "result", is_error: true, result: "Your group's usage limit is set to $0" },
+      tracker,
+    );
+
+    expect(tracker.getRateLimitResetAt()).toBeDefined();
+    expect(tracker.hasErrors()).toBe(true);
+  });
+});
+
+describe("three-tier resolver logic (unit test via clamp helper)", () => {
+  // Mirrors the clampResetTime inline helper in runner.ts
+  function 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();
+  }
+
+  test("tier 1: rateLimitResetAt from structured event → used directly (after clamp)", () => {
+    const futureResetsAtSec = Math.floor(Date.now() / 1000) + 3600;
+    const tracker = new SessionErrorTracker();
+    tracker.processRateLimitEvent({
+      type: "rate_limit_event",
+      rate_limit_info: { status: "rejected", resetsAt: futureResetsAtSec },
+    });
+
+    const rateLimitResetAt = tracker.getRateLimitResetAt();
+    expect(rateLimitResetAt).toBeDefined();
+
+    // Simulate tier-1 branch: result.rateLimitResetAt is set
+    const rateLimitedUntil = clampResetTime(rateLimitResetAt!);
+    expect(rateLimitedUntil).toBeDefined();
+    const resolvedMs = new Date(rateLimitedUntil).getTime();
+    const nowMs = Date.now();
+    expect(resolvedMs).toBeGreaterThanOrEqual(nowMs + 59_000);
+  });
+
+  test("tier 3 fallback: no structured event, no parseable message → 5-min default", () => {
+    // Simulate: rateLimitResetAt is undefined, parseRateLimitResetTime returns undefined
+    const defaultCooldownMs = 5 * 60 * 1000;
+    const rateLimitedUntil = new Date(Date.now() + defaultCooldownMs).toISOString();
+
+    const resolvedMs = new Date(rateLimitedUntil).getTime();
+    const nowMs = Date.now();
+    expect(resolvedMs).toBeGreaterThanOrEqual(nowMs + 4 * 60_000);
+    expect(resolvedMs).toBeLessThanOrEqual(nowMs + 6 * 60_000);
+  });
+});

package/src/tests/scripts-http.test.ts

@@ -347,4 +347,57 @@ describe("/api/scripts HTTP", () => {
     expect(await del.json()).toEqual({ deleted: true });
     expect(getScript({ name: "lookup-helper", scope: "agent", scopeId: workerId })).toBeNull();
   });
+
+  test("script_query_types returns argsJsonSchema for a script with argsSchema export", async () => {
+    const source = `
+      import { z } from "zod";
+      export const argsSchema = z.object({
+        repo: z.string(),
+        limit: z.number().default(10),
+      });
+      export default async (args: z.infer<typeof argsSchema>) => ({ repo: args.repo });
+    `;
+    await upsert({ name: "schema-script", source });
+
+    const types = await dispatch("/api/scripts/schema-script/types", { agentId: workerId });
+    expect(types.status).toBe(200);
+    const body = (await types.json()) as { argsJsonSchema: unknown };
+    expect(body.argsJsonSchema).not.toBeNull();
+    expect(typeof body.argsJsonSchema).toBe("object");
+    // JSON Schema should describe the repo and limit properties
+    const schema = body.argsJsonSchema as { properties?: Record<string, unknown> };
+    expect(schema.properties).toHaveProperty("repo");
+    expect(schema.properties).toHaveProperty("limit");
+  });
+
+  test("script_query_types returns argsJsonSchema: null for a script without argsSchema", async () => {
+    await upsert({ name: "no-schema-script", source: validSource(3) });
+
+    const types = await dispatch("/api/scripts/no-schema-script/types", { agentId: workerId });
+    expect(types.status).toBe(200);
+    const body = (await types.json()) as { argsJsonSchema: unknown };
+    expect(body.argsJsonSchema).toBeNull();
+  });
+
+  test("script_search includes argsJsonSchema in results", async () => {
+    const source = `
+      import { z } from "zod";
+      export const argsSchema = z.object({ query: z.string() });
+      export default async (args: z.infer<typeof argsSchema>) => ({ result: args.query });
+    `;
+    await upsert({ name: "search-with-schema", source, description: "search result helper" });
+
+    const search = await dispatch("/api/scripts/search", {
+      method: "POST",
+      agentId: workerId,
+      body: JSON.stringify({ query: "search result helper", limit: 5 }),
+    });
+    expect(search.status).toBe(200);
+    const body = (await search.json()) as {
+      results: Array<{ name: string; argsJsonSchema: unknown }>;
+    };
+    const result = body.results.find((r) => r.name === "search-with-schema");
+    expect(result).toBeDefined();
+    expect(result?.argsJsonSchema).not.toBeNull();
+  });
 });

package/src/tests/scripts-runtime.test.ts

@@ -286,4 +286,59 @@ describe("runScript", () => {
       await Bun.$`rm -rf ${tmpdir}`;
     }
   });
+
+  test("argsSchema rejects invalid args with a formatted Zod error", async () => {
+    const output = await runScript({
+      agentId: "agent-1",
+      args: {},
+      resources,
+      source: `
+        import { z } from "zod";
+        export const argsSchema = z.object({
+          repo: z.string(),
+        });
+        export default async (args: z.infer<typeof argsSchema>) => ({ repo: args.repo });
+      `,
+    });
+
+    expect(output.error).toBeDefined();
+    expect(output.exitCode).not.toBe(0);
+    expect(output.stderr).toContain("argsSchema validation failed");
+    expect(output.stderr).toContain("repo");
+  });
+
+  test("argsSchema applies .default() values when fields are omitted", async () => {
+    const output = await runScript({
+      agentId: "agent-1",
+      args: { repo: "owner/name" },
+      resources,
+      source: `
+        import { z } from "zod";
+        export const argsSchema = z.object({
+          repo: z.string(),
+          limit: z.number().default(10),
+        });
+        export default async (args: z.infer<typeof argsSchema>) => ({ repo: args.repo, limit: args.limit });
+      `,
+    });
+
+    expect(output.error).toBeUndefined();
+    expect(output.result).toEqual({ repo: "owner/name", limit: 10 });
+    expect(output.exitCode).toBe(0);
+  });
+
+  test("script without argsSchema still works (backward-compat)", async () => {
+    const output = await runScript({
+      agentId: "agent-1",
+      args: { value: 42 },
+      resources,
+      source: `
+        export default async (args: { value: number }) => ({ doubled: args.value * 2 });
+      `,
+    });
+
+    expect(output.error).toBeUndefined();
+    expect(output.result).toEqual({ doubled: 84 });
+    expect(output.exitCode).toBe(0);
+  });
 });

package/src/types.ts

@@ -1320,6 +1320,7 @@ export const ScriptRecordSchema = z.object({
   description: z.string(),
   intent: z.string(),
   signatureJson: z.string(),
+  argsJsonSchema: z.string().nullable(),
   contentHash: z.string(),
   version: z.number(),
   isScratch: z.boolean(),

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;