@desplega.ai/agent-swarm 2.6.0 → 2.7.0

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

@@ -173,23 +173,21 @@ export class NativeScriptExecutor implements ScriptExecutor {
     let removeAbortListener: (() => void) | undefined;
     let proc: Bun.Subprocess<"pipe", "pipe", "pipe"> | undefined;
 
-    try {
-      if (killed) {
-        return {
-          result: undefined,
-          stdout: "",
-          stderr: "",
-          truncated: { stdout: false, stderr: false },
-          durationMs: Date.now() - start,
-          exitCode: 1,
-          error: "killed",
-        };
-      }
+    const killedOutput = (): ExecutorOutput => ({
+      result: undefined,
+      stdout: "",
+      stderr: "",
+      truncated: { stdout: false, stderr: false },
+      durationMs: Date.now() - start,
+      exitCode: 1,
+      error: "killed",
+    });
 
-      await Bun.write(argsFile, JSON.stringify(input.args ?? null));
-      await Bun.write(sourceFile, input.source);
-      await writeBareImportShims(tmpdir);
+    try {
+      if (killed) return killedOutput();
 
+      // Listen before the first await: an abort during the file writes below
+      // must stop the spawn, not land between the writes and the listener.
       const onExternalAbort = () => {
         killed = true;
         if (proc) void terminateProcessGroup(proc.pid);
@@ -197,12 +195,19 @@ export class NativeScriptExecutor implements ScriptExecutor {
       input.signal?.addEventListener("abort", onExternalAbort, { once: true });
       removeAbortListener = () => input.signal?.removeEventListener("abort", onExternalAbort);
 
+      await Bun.write(argsFile, JSON.stringify(input.args ?? null));
+      await Bun.write(sourceFile, input.source);
+      await writeBareImportShims(tmpdir);
+
+      // No await between this check and the spawn below.
+      if (killed) return killedOutput();
+
       const timeout = setTimeout(() => {
         timedOut = true;
         if (proc) void terminateProcessGroup(proc.pid);
       }, input.resources.wallClockMs);
 
-      const harnessEnv = {
+      const harnessEnv: Record<string, string> = {
         PATH: process.env.PATH ?? "/usr/bin:/bin",
         HOME: process.env.HOME ?? "/tmp",
         LANG: process.env.LANG ?? "C.UTF-8",
@@ -214,6 +219,7 @@ export class NativeScriptExecutor implements ScriptExecutor {
         SWARM_SCRIPT_RESULT_FILE: resultFile,
         SWARM_SCRIPT_ERROR_FILE: errorFile,
         SWARM_SCRIPT_STARTED_FILE: startedFile,
+        ...(input.hostValidatedArgs ? { SWARM_SCRIPT_HOST_VALIDATED_ARGS: "1" } : {}),
       };
 
       proc = registerProcessGroup(

package/src/scripts-runtime/executors/quickjs-prelude.ts

@@ -308,14 +308,116 @@ define("__swarm_ctx", ctx);
  * zod `argsSchema` check, the same contract as `eval-harness.ts`.
  */
 export const SANDBOX_EPILOGUE = String.raw`(async () => {
+  const isStructuralSchemaNode = (schema) => {
+    if (!schema || typeof schema !== "object") return false;
+    const def = schema._zod && schema._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).every(isStructuralSchemaNode);
+      }
+      default:
+        return false;
+    }
+  };
+  const isHostValidationEquivalent = (schema, value) => {
+    if (!schema || typeof schema !== "object") return false;
+    const def = schema._zod && schema._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":
+        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 (schema._zod && schema._zod.values instanceof Set) {
+          return schema._zod.values.has(value);
+        }
+        const entriesObj = def.entries && typeof def.entries === "object" ? def.entries : 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 shape = typeof def.shape === "function" ? def.shape() : def.shape;
+        if (!shape || typeof shape !== "object") return false;
+        for (const key of Object.keys(value)) {
+          if (!Object.hasOwn(shape, key)) return false;
+        }
+        for (const [key, propSchema] of Object.entries(shape)) {
+          if (!Object.hasOwn(value, key) && key in value) return false;
+          const propValue = value[key];
+          if (!isHostValidationEquivalent(propSchema, propValue)) return false;
+        }
+        return true;
+      }
+      default:
+        return false;
+    }
+  };
   const mod = globalThis.__swarm_module;
   if (!mod || typeof mod.default !== "function") {
     throw new Error(
       "Swarm script must export a default function. Script must export default async function (args, ctx): args FIRST, ctx second.",
     );
   }
+  const hostValidatedArgs = globalThis.__swarm_host_validated_args === true;
   let args = globalThis.__swarm_args;
-  if (mod.argsSchema && typeof mod.argsSchema === "object" && "parse" in mod.argsSchema) {
+  if (
+    mod.argsSchema &&
+    typeof mod.argsSchema === "object" &&
+    "parse" in mod.argsSchema &&
+    !(hostValidatedArgs && isHostValidationEquivalent(mod.argsSchema, args))
+  ) {
     try {
       args = mod.argsSchema.parse(args);
     } catch (error) {

package/src/scripts-runtime/executors/quickjs-runner.ts

@@ -29,6 +29,7 @@ import type {
 export type QuickJSJob = {
   source: string;
   args: unknown;
+  hostValidatedArgs?: boolean;
   configPayload: SwarmConfigPayload;
   resources: ScriptResourcePolicy;
   network: ExecutorInput["network"];
@@ -656,7 +657,7 @@ async function evaluateJob(
 
   let timer: ReturnType<typeof setTimeout> | undefined;
   try {
-    const init = `globalThis.__swarm_shape = ${JSON.stringify(shape)};\nglobalThis.__swarm_args = ${JSON.stringify(args)};`;
+    const init = `globalThis.__swarm_shape = ${JSON.stringify(shape)};\nglobalThis.__swarm_args = ${JSON.stringify(args)};\nglobalThis.__swarm_host_validated_args = ${Boolean(job.hostValidatedArgs)};`;
     const ok =
       evaluate(init, "swarm-init.js") &&
       evaluate(SANDBOX_WEB_SHIMS, "swarm-web-shims.js") &&

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

@@ -146,6 +146,12 @@ export class QuickJSScriptExecutor implements ScriptExecutor {
         `quickjs worker failed to start: ${error instanceof Error ? error.message : String(error)}`,
       );
     }
+    // An abort while the worker booted fired before the listener below
+    // exists. From here to postMessage nothing awaits.
+    if (input.signal?.aborted) {
+      pool.release(slot);
+      return emptyOutput("killed");
+    }
 
     const id = ++requestSeq;
     const start = performance.now();
@@ -196,6 +202,7 @@ export class QuickJSScriptExecutor implements ScriptExecutor {
         job: {
           source: input.source,
           args: input.args,
+          ...(input.hostValidatedArgs ? { hostValidatedArgs: true } : {}),
           configPayload: input.configPayload,
           resources: input.resources,
           network: input.network,

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

@@ -7,6 +7,27 @@ const EXECUTORS: Record<string, () => ScriptExecutor> = {
   quickjs: () => new QuickJSScriptExecutor(),
 };
 
+export function getDeploymentScriptExecutorName(env: NodeJS.ProcessEnv = process.env): string {
+  return (env.SCRIPT_EXECUTOR ?? "native").trim();
+}
+
+/**
+ * Operator sandbox ceiling: when the deployment sets `SCRIPT_EXECUTOR=quickjs`,
+ * individual scripts or agent calls may not escalate to the less-restricted
+ * `native` executor. When the deployment runs `native` (the default), scripts
+ * may opt down into `quickjs`.
+ */
+export function isExecutorAllowedByDeployment(
+  requested: string | null | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  if (!requested) return true;
+  if (getDeploymentScriptExecutorName(env) === "quickjs" && requested.trim() === "native") {
+    return false;
+  }
+  return true;
+}
+
 export function getScriptExecutor(name = process.env.SCRIPT_EXECUTOR ?? "native"): ScriptExecutor {
   const factory = EXECUTORS[name.trim()];
   if (!factory) {
@@ -16,3 +37,14 @@ export function getScriptExecutor(name = process.env.SCRIPT_EXECUTOR ?? "native"
   }
   return factory();
 }
+
+export function resolveScriptExecutor(
+  requested?: string | null,
+  env: NodeJS.ProcessEnv = process.env,
+): ScriptExecutor {
+  if (!isExecutorAllowedByDeployment(requested, env)) {
+    throw new Error('Executor "native" is not permitted when deployment SCRIPT_EXECUTOR="quickjs"');
+  }
+  const effective = requested ?? env.SCRIPT_EXECUTOR ?? "native";
+  return getScriptExecutor(effective);
+}

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

@@ -3,6 +3,7 @@ import type { ScriptApiConnectionDescriptor, ScriptMcpConnectionDescriptor } fro
 import type { FailedCredentialBinding, ResolvedCredentialBinding } from "../credential-broker";
 
 export type ScriptFsMode = "none" | "workspace-rw";
+export type ScriptExecutorName = "native" | "quickjs";
 
 export type EgressSecretEntry = ResolvedCredentialBinding;
 
@@ -49,6 +50,12 @@ export type ScriptResourcePolicy = {
 export type ExecutorInput = {
   source: string;
   args: unknown;
+  /**
+   * Trusted host-only flag indicating `args` already passed host JSON Schema
+   * validation for this run. Executors may skip `argsSchema.parse(args)` only
+   * when this flag is true AND the runtime `argsSchema` is purely structural.
+   */
+  hostValidatedArgs?: boolean;
   configPayload: SwarmConfigPayload;
   resources: ScriptResourcePolicy;
   fsMode: ScriptFsMode;

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>;