@desplega.ai/agent-swarm 2.6.0 → 2.7.1

package/src/scripts-runtime/host-validated-args.ts

@@ -0,0 +1,133 @@
+/**
+ * Unforgeable host-only capability symbol set on `RunScriptInput` strictly at
+ * the host boundary (`POST /api/x/script/{endpointId}`) after `validateJsonSchema`
+ * succeeds. Because `Symbol` keys cannot be produced by JSON deserialization,
+ * callers that forward request-shaped JSON fields into `RunScriptInput` can
+ * never opt out of `argsSchema` validation.
+ */
+export const HOST_VALIDATED_ARGS = Symbol("swarm.hostValidatedArgs");
+
+/**
+ * Checks whether a runtime `argsSchema` (Zod v4 / `zod/mini` schema) and its
+ * candidate `value` are semantically equivalent to the host-side JSON Schema
+ * validation performed by `validateJsonSchema` in `src/http/x.ts`.
+ *
+ * Returns `true` only when `schema.parse(value)` is guaranteed to succeed and
+ * return a value deeply identical to `value` without running any defaults,
+ * coercions, transforms, refinements, or unknown-key stripping.
+ */
+export function isHostValidationEquivalent(schema: unknown, value: unknown): boolean {
+  if (!schema || typeof schema !== "object") return false;
+  const zodInternal = (schema as { _zod?: { def?: Record<string, unknown>; values?: unknown } })
+    ._zod;
+  const def = zodInternal?.def;
+  if (!def || typeof def !== "object") return false;
+
+  if (def.coerce) return false;
+  if (Array.isArray(def.checks) && def.checks.length > 0) return false;
+
+  switch (def.type) {
+    case "string":
+      return typeof value === "string" && !def.format;
+    case "number":
+      return typeof value === "number" && Number.isFinite(value) && !def.format;
+    case "boolean":
+      return typeof value === "boolean";
+    case "literal": {
+      const rawValues = def.values;
+      const values = Array.isArray(rawValues)
+        ? rawValues
+        : rawValues instanceof Set
+          ? Array.from(rawValues)
+          : [];
+      return (
+        values.length > 0 &&
+        values.some((v) => v === value && typeof v !== "bigint" && typeof v !== "symbol")
+      );
+    }
+    case "enum": {
+      if (zodInternal?.values instanceof Set) {
+        return zodInternal.values.has(value);
+      }
+      const entriesObj =
+        def.entries && typeof def.entries === "object"
+          ? (def.entries as Record<string, unknown>)
+          : null;
+      if (!entriesObj) return false;
+      const entries = Object.values(entriesObj).filter(
+        (v) => !(typeof v === "string" && typeof entriesObj[v] === "number"),
+      );
+      return entries.length > 0 && entries.includes(value);
+    }
+    case "optional":
+      return value === undefined
+        ? isStructuralSchemaNode(def.innerType)
+        : isHostValidationEquivalent(def.innerType, value);
+    case "nullable":
+      return value === null
+        ? isStructuralSchemaNode(def.innerType)
+        : isHostValidationEquivalent(def.innerType, value);
+    case "array":
+      return (
+        Array.isArray(value) &&
+        isStructuralSchemaNode(def.element) &&
+        value.every((item) => isHostValidationEquivalent(def.element, item))
+      );
+    case "object": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+      const rawShape = typeof def.shape === "function" ? def.shape() : def.shape;
+      if (!rawShape || typeof rawShape !== "object") return false;
+      const shape = rawShape as Record<string, unknown>;
+      const obj = value as Record<string, unknown>;
+
+      // If `value` carries extra keys not declared in `shape`, let `.parse()`
+      // handle key stripping (`z.object`), passthrough (`z.looseObject`), or
+      // rejection (`z.strictObject`).
+      for (const key of Object.keys(obj)) {
+        if (!Object.hasOwn(shape, key)) return false;
+      }
+
+      for (const [key, propSchema] of Object.entries(shape)) {
+        // Retain Zod's property lookup semantics: if `key` is absent as an own
+        // property on `obj` but resolves via `Object.prototype` (e.g. `constructor`,
+        // `toString`), fall back to `.parse()` so Zod validates/rejects the
+        // inherited prototype value identically to `main`.
+        if (!Object.hasOwn(obj, key) && key in obj) return false;
+        const propValue = obj[key];
+        if (!isHostValidationEquivalent(propSchema, propValue)) return false;
+      }
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+
+function isStructuralSchemaNode(schema: unknown): boolean {
+  if (!schema || typeof schema !== "object") return false;
+  const def = (schema as { _zod?: { def?: Record<string, unknown> } })._zod?.def;
+  if (!def || typeof def !== "object") return false;
+  if (def.coerce) return false;
+  if (Array.isArray(def.checks) && def.checks.length > 0) return false;
+  switch (def.type) {
+    case "string":
+    case "number":
+      return !def.format;
+    case "boolean":
+    case "literal":
+    case "enum":
+      return true;
+    case "optional":
+    case "nullable":
+      return isStructuralSchemaNode(def.innerType);
+    case "array":
+      return isStructuralSchemaNode(def.element);
+    case "object": {
+      const rawShape = typeof def.shape === "function" ? def.shape() : def.shape;
+      if (!rawShape || typeof rawShape !== "object") return false;
+      return Object.values(rawShape as Record<string, unknown>).every(isStructuralSchemaNode);
+    }
+    default:
+      return false;
+  }
+}

package/src/scripts-runtime/loader.ts

@@ -6,16 +6,18 @@ import { createValueScrubber, scrubObject, scrubSecrets } from "../utils/secret-
 import type { ScriptApiConnectionDescriptor, ScriptMcpConnectionDescriptor } from "./api-types";
 import type { FailedCredentialBinding } from "./credential-broker";
 import { buildEgressSecrets } from "./egress-secrets";
-import { getScriptExecutor } from "./executors/registry";
+import { isExecutorAllowedByDeployment, resolveScriptExecutor } from "./executors/registry";
 import {
   DEFAULT_SCRIPT_RESOURCES,
   type EgressSecretEntry,
   type ExecutorOutput,
   type ScriptAgentFsDescriptor,
+  type ScriptExecutorName,
   type ScriptFsMode,
   type ScriptResourcePolicy,
   type SwarmConfigPayload,
 } from "./executors/types";
+import { HOST_VALIDATED_ARGS } from "./host-validated-args";
 import { validateScriptImports } from "./import-allowlist";
 
 /**
@@ -38,7 +40,19 @@ const CAPACITY_EXCEEDED_RETRY_DELAYS_MS = [200, 750];
 export type RunScriptInput = {
   source: string;
   args?: unknown;
+  /**
+   * Unforgeable host-only capability symbol set only when the host has already
+   * validated `args` against the script's `argsJsonSchema` (e.g. `POST /api/x/script/{endpointId}`).
+   * Keyed by a `Symbol` so request-shaped JSON inputs forwarded into `RunScriptInput`
+   * can never opt out of `argsSchema` validation.
+   */
+  [HOST_VALIDATED_ARGS]?: boolean;
   fsMode?: ScriptFsMode;
+  /**
+   * Optional per-script executor override ("native" | "quickjs"). When null or
+   * undefined, `getScriptExecutor` falls back to `SCRIPT_EXECUTOR ?? "native"`.
+   */
+  executor?: ScriptExecutorName | null;
   agentId: string;
   /**
    * Bearer for the run's `ctx.swarm` SDK calls. Api-side callers pass a
@@ -118,6 +132,18 @@ export async function runScript(input: RunScriptInput): Promise<RunScriptOutput>
     };
   }
 
+  if (!isExecutorAllowedByDeployment(input.executor)) {
+    return {
+      result: undefined,
+      stdout: "",
+      stderr: 'Executor "native" is not permitted when deployment SCRIPT_EXECUTOR="quickjs"',
+      truncated: { stdout: false, stderr: false },
+      durationMs: 0,
+      exitCode: 1,
+      error: "executor_error",
+    };
+  }
+
   // The global scrubber skips values under its length floor, so this run's own
   // secret config is redacted here at any length before the global pass. Built
   // before the import check: its diagnostic quotes source, which can hold a value.
@@ -150,6 +176,7 @@ export async function runScript(input: RunScriptInput): Promise<RunScriptOutput>
   const executorInput = {
     source: input.source,
     args: input.args ?? null,
+    ...(input[HOST_VALIDATED_ARGS] === true ? { hostValidatedArgs: true } : {}),
     configPayload,
     resources,
     fsMode: input.fsMode ?? "none",
@@ -157,11 +184,11 @@ export async function runScript(input: RunScriptInput): Promise<RunScriptOutput>
     signal: input.signal,
   };
 
-  let output = await getScriptExecutor().run(executorInput);
+  let output = await resolveScriptExecutor(input.executor).run(executorInput);
   for (const delayMs of CAPACITY_EXCEEDED_RETRY_DELAYS_MS) {
     if (output.error !== "capacity_exceeded" || input.signal?.aborted) break;
     await Bun.sleep(delayMs);
-    output = await getScriptExecutor().run(executorInput);
+    output = await resolveScriptExecutor(input.executor).run(executorInput);
   }
 
   return {

package/src/scripts-runtime/swarm-sdk.ts

@@ -8,6 +8,7 @@ type BridgeRequest = {
   method: string;
   path: string;
   body?: unknown;
+  headers?: Record<string, string>;
 };
 
 function headers(config: SwarmConfig): Record<string, string> {
@@ -362,10 +363,16 @@ function bridgeRequestFor(name: string, args: unknown): BridgeRequest | null {
     case "workflow_trigger": {
       const id = typeof body.id === "string" ? body.id : undefined;
       if (!id) throw new Error("workflow_trigger requires string `id`");
+      const path = `/api/workflows/${encodeURIComponent(id)}/trigger`;
       return {
         method: "POST",
-        path: `/api/workflows/${encodeURIComponent(id)}/trigger`,
+        path: body.wait === false ? `${path}?wait=false` : path,
         body: body.triggerData ?? {},
+        // The route's own Idempotency-Key: recorded in the run's transaction,
+        // so a retry after a kill replays the run instead of starting another.
+        ...(typeof body.idempotencyKey === "string"
+          ? { headers: { "Idempotency-Key": body.idempotencyKey } }
+          : {}),
       };
     }
     case "workflow_retryRun": {
@@ -491,7 +498,7 @@ async function callBridgeApi(
 
   const res = await fetch(`${baseUrl}${request.path}`, {
     method: request.method,
-    headers: headers(config),
+    headers: { ...headers(config), ...request.headers },
     body: request.body === undefined ? undefined : JSON.stringify(request.body),
   });
   const data = await readScriptSdkJsonResponse(res, `ctx.swarm.${name}`);

package/src/scripts-runtime/types/stdlib.d.ts

@@ -26,6 +26,7 @@ declare module "swarm-sdk" {
     | { [key: string]: JsonValue };
   export type ScriptScope = "agent" | "global";
   export type ScriptFsMode = "none" | "workspace-rw";
+  export type ScriptExecutorName = "native" | "quickjs";
   export type ScriptApiRawOptions = { raw: true };
   export type ScriptApiDefaultOptions = { raw?: false };
   export type RoutingReason =
@@ -304,6 +305,7 @@ declare module "swarm-sdk" {
       intent?: string;
       scope?: ScriptScope;
       fsMode?: ScriptFsMode;
+      executor?: ScriptExecutorName | null;
       idempotencyKey?: string;
     }): Promise<unknown>;
     // --- swarm / agent ---
@@ -535,7 +537,12 @@ declare module "swarm-sdk" {
     workflow_patch(args: Record<string, unknown>): Promise<unknown>;
     workflow_patchNode(args: Record<string, unknown>): Promise<unknown>;
     workflow_delete(args: { id: string }): Promise<unknown>;
-    workflow_trigger(args: { id: string; triggerData?: Record<string, unknown> }): Promise<unknown>;
+    workflow_trigger(args: {
+      id: string;
+      triggerData?: Record<string, unknown>;
+      wait?: boolean;
+      idempotencyKey?: string;
+    }): Promise<unknown>;
     workflow_retryRun(args: { id: string }): Promise<unknown>;
     workflow_cancelRun(args: { id: string }): Promise<unknown>;
 
@@ -552,6 +559,7 @@ declare module "swarm-sdk" {
       intent?: string;
       scope?: ScriptScope;
       fsMode?: ScriptFsMode;
+      executor?: ScriptExecutorName | null;
     }): Promise<unknown>;
     script_delete(args: { name: string; scope?: ScriptScope }): Promise<unknown>;
     script_queryTypes(args: { name: string; scope?: ScriptScope }): Promise<unknown>;

package/src/scripts-runtime/types/swarm-sdk.d.ts

@@ -8,6 +8,7 @@ declare module "swarm-sdk" {
     | { [key: string]: JsonValue };
   export type ScriptScope = "agent" | "global";
   export type ScriptFsMode = "none" | "workspace-rw";
+  export type ScriptExecutorName = "native" | "quickjs";
   export type ScriptApiRawOptions = { raw: true };
   export type ScriptApiDefaultOptions = { raw?: false };
   export type RoutingReason =
@@ -286,6 +287,7 @@ declare module "swarm-sdk" {
       intent?: string;
       scope?: ScriptScope;
       fsMode?: ScriptFsMode;
+      executor?: ScriptExecutorName | null;
       idempotencyKey?: string;
     }): Promise<unknown>;
     // --- swarm / agent ---
@@ -517,7 +519,12 @@ declare module "swarm-sdk" {
     workflow_patch(args: Record<string, unknown>): Promise<unknown>;
     workflow_patchNode(args: Record<string, unknown>): Promise<unknown>;
     workflow_delete(args: { id: string }): Promise<unknown>;
-    workflow_trigger(args: { id: string; triggerData?: Record<string, unknown> }): Promise<unknown>;
+    workflow_trigger(args: {
+      id: string;
+      triggerData?: Record<string, unknown>;
+      wait?: boolean;
+      idempotencyKey?: string;
+    }): Promise<unknown>;
     workflow_retryRun(args: { id: string }): Promise<unknown>;
     workflow_cancelRun(args: { id: string }): Promise<unknown>;
 
@@ -534,6 +541,7 @@ declare module "swarm-sdk" {
       intent?: string;
       scope?: ScriptScope;
       fsMode?: ScriptFsMode;
+      executor?: ScriptExecutorName | null;
     }): Promise<unknown>;
     script_delete(args: { name: string; scope?: ScriptScope }): Promise<unknown>;
     script_queryTypes(args: { name: string; scope?: ScriptScope }): Promise<unknown>;