@desplega.ai/agent-swarm 1.91.0 → 1.92.1

package/src/script-workflows/harness.ts

@@ -0,0 +1,73 @@
+import { buildWorkflowCtx } from "./workflow-ctx";
+
+function requiredEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`Missing required env ${name}`);
+  return value;
+}
+
+async function postStatus(
+  runId: string,
+  baseUrl: string,
+  agentId: string,
+  apiKey: string,
+  body: Record<string, unknown>,
+): Promise<void> {
+  const res = await fetch(`${baseUrl}/api/internal/script-runs/${runId}/status`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "X-Agent-ID": agentId,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    throw new Error(`status callback failed with ${res.status}: ${await res.text()}`);
+  }
+}
+
+const runId = requiredEnv("SCRIPT_RUN_ID");
+const agentId = requiredEnv("SCRIPT_RUN_AGENT_ID");
+const apiKey = requiredEnv("AGENT_SWARM_API_KEY");
+const baseUrl = requiredEnv("MCP_BASE_URL").replace(/\/$/, "");
+const sourceFile = requiredEnv("SCRIPT_RUN_SOURCE_FILE");
+const argsFile = requiredEnv("SCRIPT_RUN_ARGS_FILE");
+const userModulePath = `${requiredEnv("SCRIPT_RUN_TMPDIR")}/user-script.ts`;
+
+const heartbeat = setInterval(() => {
+  fetch(`${baseUrl}/api/internal/script-runs/${runId}/heartbeat`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "X-Agent-ID": agentId,
+    },
+  }).catch(() => {});
+}, 10_000);
+heartbeat.unref?.();
+
+try {
+  const source = await Bun.file(sourceFile).text();
+  const args = JSON.parse(await Bun.file(argsFile).text());
+  await Bun.write(userModulePath, source);
+  const mod = await import(userModulePath);
+  if (typeof mod.default !== "function") {
+    throw new Error("Script workflow must export a default function");
+  }
+  const ctx = buildWorkflowCtx({ runId, agentId, apiKey, baseUrl, args });
+  const output = await mod.default(args, ctx);
+  await postStatus(runId, baseUrl, agentId, apiKey, {
+    status: "completed",
+    output: output ?? null,
+  });
+  process.exit(0);
+} catch (err) {
+  console.error(err instanceof Error ? err.stack || err.message : String(err));
+  await postStatus(runId, baseUrl, agentId, apiKey, {
+    status: "failed",
+    error: err instanceof Error ? err.message : String(err),
+  });
+  process.exit(1);
+} finally {
+  clearInterval(heartbeat);
+}

package/src/script-workflows/label-lint.ts

@@ -0,0 +1,51 @@
+export type LabelLintError = {
+  label: string;
+  lineNumber: number | null;
+  detail: string;
+};
+
+export type LabelLintResult = { ok: true } | { ok: false; errors: LabelLintError[] };
+
+const CTX_STEP_LITERAL_LABEL_PATTERN = /ctx\.step\.\w+\(\s*"([^"]+)"/g;
+const LOOP_PATTERNS = [
+  /\bfor\s*\(/,
+  /\bwhile\s*\(/,
+  /\.map\s*\(/,
+  /\.forEach\s*\(/,
+  /\.reduce\s*\(/,
+  /\.flatMap\s*\(/,
+];
+
+export function lintWorkflowLabels(source: string): LabelLintResult {
+  const errors: LabelLintError[] = [];
+  const lines = source.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    CTX_STEP_LITERAL_LABEL_PATTERN.lastIndex = 0;
+    let match = CTX_STEP_LITERAL_LABEL_PATTERN.exec(line);
+    while (match !== null) {
+      const label = match[1];
+      if (!label) {
+        match = CTX_STEP_LITERAL_LABEL_PATTERN.exec(line);
+        continue;
+      }
+      const windowStart = Math.max(0, i - 10);
+      const context = lines.slice(windowStart, i + 1).join("\n");
+      if (!LOOP_PATTERNS.some((pattern) => pattern.test(context))) {
+        match = CTX_STEP_LITERAL_LABEL_PATTERN.exec(line);
+        continue;
+      }
+      errors.push({
+        label,
+        lineNumber: i + 1,
+        detail:
+          `Literal string label "${label}" at line ${i + 1} appears inside a loop. ` +
+          "Labels must be unique per run; use a template literal that includes the loop variable.",
+      });
+      match = CTX_STEP_LITERAL_LABEL_PATTERN.exec(line);
+    }
+  }
+
+  return errors.length > 0 ? { ok: false, errors } : { ok: true };
+}

package/src/script-workflows/limits.ts

@@ -0,0 +1,22 @@
+const DEFAULT_MAX_STEPS = 1000;
+const DEFAULT_MAX_WALL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_MAX_AGENT_TASKS = 50;
+
+function positiveIntEnv(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
+export function scriptRunMaxSteps(): number {
+  return positiveIntEnv("SCRIPT_RUN_MAX_STEPS", DEFAULT_MAX_STEPS);
+}
+
+export function scriptRunMaxWallMs(): number {
+  return positiveIntEnv("SCRIPT_RUN_MAX_WALL_MS", DEFAULT_MAX_WALL_MS);
+}
+
+export function scriptRunMaxAgentTasks(): number {
+  return positiveIntEnv("SCRIPT_RUN_MAX_AGENT_TASKS", DEFAULT_MAX_AGENT_TASKS);
+}

package/src/script-workflows/supervisor.ts

@@ -0,0 +1,139 @@
+import { getRunningScriptRuns, getScriptRun, updateScriptRun } from "../be/db";
+import type { ScriptRun } from "../types";
+import { getApiKey } from "../utils/api-key";
+import {
+  localProcessScriptExecutor,
+  type ScriptExecutionHandle,
+  type ScriptExecutor,
+} from "./executor";
+import { scriptRunMaxWallMs } from "./limits";
+
+type ManagedRun = {
+  execution: ScriptExecutionHandle;
+};
+
+const managed = new Map<string, ManagedRun>();
+let reconcileTimer: ReturnType<typeof setInterval> | null = null;
+let scriptExecutor: ScriptExecutor = localProcessScriptExecutor;
+
+function supervisorDisabled(): boolean {
+  return process.env.SCRIPT_RUN_SUPERVISOR_DISABLE === "true";
+}
+
+export function setScriptRunExecutor(executor: ScriptExecutor): void {
+  scriptExecutor = executor;
+}
+
+export async function startScriptRunProcess(
+  run: ScriptRun,
+  baseUrl: string,
+  apiKeyOverride?: string,
+): Promise<void> {
+  if (supervisorDisabled()) return;
+  if (managed.has(run.id)) return;
+  const apiKey = apiKeyOverride ?? getApiKey();
+  if (!apiKey) throw new Error("AGENT_SWARM_API_KEY is required to spawn script runs");
+  if (process.env.SCRIPT_WORKFLOW_DEBUG === "true") {
+    console.error(
+      `[script-workflows] spawning ${run.id} auth override=${apiKeyOverride ? "yes" : "no"} len=${apiKey.length}`,
+    );
+  }
+
+  const execution = await scriptExecutor.start({ run, baseUrl, apiKey });
+  managed.set(run.id, { execution });
+  updateScriptRun(run.id, {
+    status: "running",
+    pid: execution.pid,
+    lastHeartbeatAt: new Date().toISOString(),
+  });
+
+  execution.exited
+    .then(async ({ exitCode, stderr }) => {
+      const current = getScriptRun(run.id);
+      if (current && current.status === "running") {
+        if (exitCode !== 0) {
+          console.error(
+            `[script-workflows] run ${run.id} subprocess exited ${exitCode}: ${stderr.trim() || "(no stderr)"}`,
+          );
+        }
+        updateScriptRun(run.id, {
+          status: exitCode === 0 ? "completed" : "failed",
+          pid: null,
+          finishedAt: new Date().toISOString(),
+          error:
+            exitCode === 0
+              ? null
+              : stderr.trim() || `Script workflow subprocess exited ${exitCode}`,
+        });
+      }
+    })
+    .finally(async () => {
+      managed.delete(run.id);
+      await execution.cleanup();
+    });
+}
+
+export function terminateScriptRunProcess(runId: string): boolean {
+  const managedRun = managed.get(runId);
+  const run = getScriptRun(runId);
+  if (managedRun) {
+    managedRun.execution.terminate("SIGTERM");
+    managed.delete(runId);
+    return true;
+  }
+  if (run?.pid && scriptExecutor.isRunning(run.pid)) {
+    scriptExecutor.terminatePid(run.pid, "SIGTERM");
+    return true;
+  }
+  return false;
+}
+
+export function pauseScriptRunProcess(runId: string): void {
+  terminateScriptRunProcess(runId);
+  updateScriptRun(runId, { status: "paused", pid: null });
+}
+
+export function abortScriptRunLimit(runId: string, reason: string): void {
+  terminateScriptRunProcess(runId);
+  updateScriptRun(runId, {
+    status: "aborted_limit",
+    pid: null,
+    finishedAt: new Date().toISOString(),
+    error: reason,
+  });
+}
+
+export function reconcileScriptRuns(baseUrl: string): void {
+  if (supervisorDisabled()) return;
+  for (const run of getRunningScriptRuns()) {
+    if (run.status === "paused") continue;
+    const current = managed.get(run.id);
+    if (current && Date.now() - current.execution.startedAtMs > scriptRunMaxWallMs()) {
+      abortScriptRunLimit(run.id, `SCRIPT_RUN_MAX_WALL_MS exceeded (${scriptRunMaxWallMs()})`);
+      continue;
+    }
+    if (!current && (!run.pid || !scriptExecutor.isRunning(run.pid))) {
+      startScriptRunProcess(run, baseUrl).catch((err) => {
+        updateScriptRun(run.id, {
+          status: "failed",
+          pid: null,
+          finishedAt: new Date().toISOString(),
+          error: err instanceof Error ? err.message : String(err),
+        });
+      });
+    }
+  }
+}
+
+export function startScriptRunSupervisor(baseUrl: string): void {
+  if (supervisorDisabled() || reconcileTimer) return;
+  reconcileScriptRuns(baseUrl);
+  reconcileTimer = setInterval(() => reconcileScriptRuns(baseUrl), 15_000);
+  reconcileTimer.unref?.();
+}
+
+export function stopScriptRunSupervisor(): void {
+  if (reconcileTimer) clearInterval(reconcileTimer);
+  reconcileTimer = null;
+  for (const runId of [...managed.keys()]) terminateScriptRunProcess(runId);
+}

package/src/script-workflows/workflow-ctx.ts

@@ -0,0 +1,209 @@
+import { stdlib } from "../scripts-runtime/stdlib";
+
+type StepStatusResponse =
+  | { stepKey: string; stepType: string; result: unknown }
+  | { error: string };
+
+type StepWriteResponse = { ok: true } | { error: string };
+
+type RawLlmConfig = {
+  prompt: string;
+  model?: string;
+  schema?: Record<string, unknown>;
+};
+
+type AgentTaskConfig = {
+  template?: string;
+  task?: string;
+  agentId?: string;
+  tags?: string[];
+  priority?: number;
+  offerMode?: boolean;
+  dir?: string;
+  vcsRepo?: string;
+  model?: string;
+  parentTaskId?: string;
+  requestedByUserId?: string;
+  outputSchema?: Record<string, unknown>;
+};
+
+type SwarmScriptConfig = {
+  name?: string;
+  scriptName?: string;
+  source?: string;
+  args?: unknown;
+  scope?: "agent" | "global";
+  fsMode?: "none" | "workspace-rw";
+  intent?: string;
+  idempotencyKey?: string;
+};
+
+type WorkflowRunInfo = {
+  id: string;
+  agentId: string;
+  args: unknown;
+};
+
+export type WorkflowCtx = {
+  run: WorkflowRunInfo;
+  step: {
+    rawLlm: (label: string, config: RawLlmConfig) => Promise<unknown>;
+    agentTask: (label: string, config: AgentTaskConfig) => Promise<unknown>;
+    swarmScript: (label: string, config: SwarmScriptConfig) => Promise<unknown>;
+    humanInTheLoop: () => Promise<never>;
+  };
+  swarm: Record<string, (args?: unknown) => Promise<unknown>>;
+  stdlib: typeof stdlib;
+  logger: Console;
+};
+
+function encodeStepKey(label: string): string {
+  return encodeURIComponent(label);
+}
+
+function headers(apiKey: string, agentId: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    "X-Agent-ID": agentId,
+    "Content-Type": "application/json",
+  };
+}
+
+async function readJson(res: Response): Promise<unknown> {
+  const text = await res.text();
+  return text ? JSON.parse(text) : {};
+}
+
+function apiError(prefix: string, status: number, body: unknown): Error {
+  const message =
+    body && typeof body === "object" && "error" in body
+      ? String((body as { error: unknown }).error)
+      : JSON.stringify(body);
+  return new Error(`${prefix} failed with ${status}: ${message}`);
+}
+
+export function buildWorkflowCtx(input: {
+  runId: string;
+  agentId: string;
+  apiKey: string;
+  baseUrl: string;
+  args: unknown;
+}): WorkflowCtx {
+  const baseUrl = input.baseUrl.replace(/\/$/, "");
+  const authHeaders = headers(input.apiKey, input.agentId);
+
+  async function fetchJson(path: string, init: RequestInit = {}): Promise<unknown> {
+    const res = await fetch(`${baseUrl}${path}`, {
+      ...init,
+      headers: { ...authHeaders, ...((init.headers as Record<string, string>) ?? {}) },
+    });
+    const body = await readJson(res);
+    if (!res.ok) throw apiError(path, res.status, body);
+    return body;
+  }
+
+  async function completedStep(
+    label: string,
+  ): Promise<{ found: true; result: unknown } | { found: false }> {
+    const res = await fetch(
+      `${baseUrl}/api/internal/script-runs/${input.runId}/steps/${encodeStepKey(label)}`,
+      {
+        headers: authHeaders,
+      },
+    );
+    if (res.status === 404) return { found: false };
+    const body = (await readJson(res)) as StepStatusResponse;
+    if (!res.ok) throw apiError(`step ${label}`, res.status, body);
+    return { found: true, result: "result" in body ? body.result : undefined };
+  }
+
+  async function writeStep(
+    label: string,
+    stepType: string,
+    config: unknown,
+    status: "completed" | "failed",
+    result?: unknown,
+    error?: string,
+    durationMs?: number,
+  ): Promise<void> {
+    const body = (await fetchJson(`/api/internal/script-runs/${input.runId}/steps`, {
+      method: "POST",
+      body: JSON.stringify({ stepKey: label, stepType, config, status, result, error, durationMs }),
+    })) as StepWriteResponse;
+    if (!("ok" in body)) throw new Error(`Failed to write journal step ${label}`);
+  }
+
+  async function durableStep(
+    label: string,
+    stepType: string,
+    config: unknown,
+    execute: () => Promise<unknown>,
+  ): Promise<unknown> {
+    const replayed = await completedStep(label);
+    if (replayed.found) return replayed.result;
+    const startedAt = Date.now();
+    try {
+      const result = await execute();
+      const durationMs = Date.now() - startedAt;
+      await writeStep(label, stepType, config, "completed", result, undefined, durationMs);
+      return result;
+    } catch (err) {
+      const durationMs = Date.now() - startedAt;
+      const error = err instanceof Error ? err.message : String(err);
+      await writeStep(label, stepType, config, "failed", undefined, error, durationMs);
+      throw err;
+    }
+  }
+
+  const swarm = new Proxy({} as Record<string, (args?: unknown) => Promise<unknown>>, {
+    get(_target, prop) {
+      if (typeof prop !== "string") return undefined;
+      return (args?: unknown) =>
+        fetchJson("/api/mcp-bridge", {
+          method: "POST",
+          body: JSON.stringify({ tool: prop.replaceAll("_", "-"), args: args ?? {} }),
+        });
+    },
+  });
+
+  return {
+    run: { id: input.runId, agentId: input.agentId, args: input.args },
+    step: {
+      rawLlm: (label, config) =>
+        durableStep(label, "raw-llm", config, async () =>
+          fetchJson("/api/internal/raw-llm", {
+            method: "POST",
+            body: JSON.stringify(config),
+          }),
+        ),
+      agentTask: (label, config) =>
+        durableStep(label, "agent-task", config, async () =>
+          fetchJson(`/api/internal/script-runs/${input.runId}/agent-task`, {
+            method: "POST",
+            body: JSON.stringify({ stepKey: label, ...config }),
+          }),
+        ),
+      swarmScript: (label, config) =>
+        durableStep(label, "swarm-script", config, async () =>
+          fetchJson("/api/scripts/run", {
+            method: "POST",
+            body: JSON.stringify({
+              name: config.name ?? config.scriptName,
+              source: config.source,
+              args: config.args,
+              scope: config.scope,
+              fsMode: config.fsMode ?? "none",
+              intent: config.intent ?? `script-run:${input.runId}:${label}`,
+              idempotencyKey: config.idempotencyKey,
+            }),
+          }),
+        ),
+      humanInTheLoop: async () => {
+        throw new Error("ctx.step.humanInTheLoop is stubbed in Script Workflows v1");
+      },
+    },
+    swarm,
+    stdlib,
+    logger: console,
+  };
+}

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

@@ -39,6 +39,9 @@ export const SDK_TOOL_NAME_MAP = {
   script_upsert: "script-upsert",
   script_delete: "script-delete", // destructive
   script_queryTypes: "script-query-types",
+  script_launchRun: "launch-script-run",
+  script_getRun: "get-script-run",
+  script_listRuns: "list-script-runs",
 
   // ── swarm / agent ──
   swarm_get: "get-swarm",
@@ -112,6 +115,7 @@ export const SDK_TOOL_NAME_MAP = {
   // ── skills ──
   skill_list: "skill-list",
   skill_get: "skill-get",
+  skill_getFile: "skill-get-file",
   skill_search: "skill-search",
   skill_create: "skill-create",
   skill_update: "skill-update",

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

@@ -290,6 +290,19 @@ function bridgeRequestFor(name: string, args: unknown): BridgeRequest | null {
       if (!id) throw new Error("skill_get requires string `id`");
       return { method: "GET", path: `/api/skills/${encodeURIComponent(id)}` };
     }
+    case "skill_getFile": {
+      const skillId = typeof body.skillId === "string" ? body.skillId : undefined;
+      const path = typeof body.path === "string" ? body.path : undefined;
+      if (!skillId) throw new Error("skill_getFile requires string `skillId`");
+      if (!path) throw new Error("skill_getFile requires string `path`");
+      return {
+        method: "GET",
+        path: `/api/skills/${encodeURIComponent(skillId)}/files/${path
+          .split("/")
+          .map(encodeURIComponent)
+          .join("/")}`,
+      };
+    }
     case "skill_search":
       return { method: "POST", path: "/api/skills/search", body };
     case "skill_delete": {

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

@@ -262,6 +262,20 @@ declare module "swarm-sdk" {
     }): Promise<unknown>;
     script_delete(args: { name: string; scope?: ScriptScope }): Promise<unknown>;
     script_queryTypes(args: { name: string; scope?: ScriptScope }): Promise<unknown>;
+    script_launchRun(args: {
+      source: string;
+      args?: unknown;
+      idempotencyKey?: string;
+      scriptName?: string;
+      requestedByUserId?: string;
+    }): Promise<unknown>;
+    script_getRun(args: { id: string }): Promise<unknown>;
+    script_listRuns(args?: {
+      status?: "running" | "paused" | "completed" | "failed" | "cancelled" | "aborted_limit";
+      agentId?: string;
+      limit?: number;
+      offset?: number;
+    }): Promise<unknown>;
 
     // --- write: repos ---
     repo_update(args: Record<string, unknown>): Promise<unknown>;
@@ -284,6 +298,7 @@ declare module "swarm-sdk" {
       includeBuiltin?: boolean;
     }): Promise<unknown>;
     skill_get(args: { id: string }): Promise<unknown>;
+    skill_getFile(args: { skillId: string; path: string }): Promise<unknown>;
     skill_search(args: { query: string; limit?: number }): Promise<unknown>;
     skill_create(args: Record<string, unknown>): Promise<unknown>;
     skill_update(args: Record<string, unknown>): Promise<unknown>;
@@ -320,7 +335,53 @@ declare module "swarm-sdk" {
 
   export interface ScriptLogger extends Console {}
 
+  export interface ScriptRunContext {
+    id: string;
+    agentId: string;
+    args: unknown;
+  }
+
+  export interface ScriptWorkflowSteps {
+    rawLlm(
+      label: string,
+      config: { prompt: string; model?: string; schema?: Record<string, unknown> },
+    ): Promise<unknown>;
+    agentTask(
+      label: string,
+      config: {
+        template?: string;
+        task?: string;
+        agentId?: string;
+        tags?: string[];
+        priority?: number;
+        offerMode?: boolean;
+        dir?: string;
+        vcsRepo?: string;
+        model?: string;
+        parentTaskId?: string;
+        requestedByUserId?: string;
+        outputSchema?: Record<string, unknown>;
+      },
+    ): Promise<unknown>;
+    swarmScript(
+      label: string,
+      config: {
+        name?: string;
+        scriptName?: string;
+        source?: string;
+        args?: unknown;
+        scope?: ScriptScope;
+        fsMode?: ScriptFsMode;
+        intent?: string;
+        idempotencyKey?: string;
+      },
+    ): Promise<unknown>;
+    humanInTheLoop(): Promise<never>;
+  }
+
   export interface ScriptContext {
+    run?: ScriptRunContext;
+    step?: ScriptWorkflowSteps;
     swarm: SwarmSdk & { config: SwarmConfig };
     stdlib: ScriptStdlib;
     logger: ScriptLogger;

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

@@ -244,6 +244,20 @@ declare module "swarm-sdk" {
     }): Promise<unknown>;
     script_delete(args: { name: string; scope?: ScriptScope }): Promise<unknown>;
     script_queryTypes(args: { name: string; scope?: ScriptScope }): Promise<unknown>;
+    script_launchRun(args: {
+      source: string;
+      args?: unknown;
+      idempotencyKey?: string;
+      scriptName?: string;
+      requestedByUserId?: string;
+    }): Promise<unknown>;
+    script_getRun(args: { id: string }): Promise<unknown>;
+    script_listRuns(args?: {
+      status?: "running" | "paused" | "completed" | "failed" | "cancelled" | "aborted_limit";
+      agentId?: string;
+      limit?: number;
+      offset?: number;
+    }): Promise<unknown>;
 
     // --- write: repos ---
     repo_update(args: Record<string, unknown>): Promise<unknown>;
@@ -266,6 +280,7 @@ declare module "swarm-sdk" {
       includeBuiltin?: boolean;
     }): Promise<unknown>;
     skill_get(args: { id: string }): Promise<unknown>;
+    skill_getFile(args: { skillId: string; path: string }): Promise<unknown>;
     skill_search(args: { query: string; limit?: number }): Promise<unknown>;
     skill_create(args: Record<string, unknown>): Promise<unknown>;
     skill_update(args: Record<string, unknown>): Promise<unknown>;
@@ -302,7 +317,53 @@ declare module "swarm-sdk" {
 
   export interface ScriptLogger extends Console {}
 
+  export interface ScriptRunContext {
+    id: string;
+    agentId: string;
+    args: unknown;
+  }
+
+  export interface ScriptWorkflowSteps {
+    rawLlm(
+      label: string,
+      config: { prompt: string; model?: string; schema?: Record<string, unknown> },
+    ): Promise<unknown>;
+    agentTask(
+      label: string,
+      config: {
+        template?: string;
+        task?: string;
+        agentId?: string;
+        tags?: string[];
+        priority?: number;
+        offerMode?: boolean;
+        dir?: string;
+        vcsRepo?: string;
+        model?: string;
+        parentTaskId?: string;
+        requestedByUserId?: string;
+        outputSchema?: Record<string, unknown>;
+      },
+    ): Promise<unknown>;
+    swarmScript(
+      label: string,
+      config: {
+        name?: string;
+        scriptName?: string;
+        source?: string;
+        args?: unknown;
+        scope?: ScriptScope;
+        fsMode?: ScriptFsMode;
+        intent?: string;
+        idempotencyKey?: string;
+      },
+    ): Promise<unknown>;
+    humanInTheLoop(): Promise<never>;
+  }
+
   export interface ScriptContext {
+    run?: ScriptRunContext;
+    step?: ScriptWorkflowSteps;
     swarm: SwarmSdk & { config: SwarmConfig };
     stdlib: ScriptStdlib;
     logger: ScriptLogger;