@desplega.ai/agent-swarm 1.91.0 → 1.92.1

package/src/http/skills.ts

@@ -3,13 +3,18 @@ import { z } from "zod";
 import {
   createSkill,
   deleteSkill,
+  deleteSkillFile,
   getAgentSkills,
   getSkillById,
+  getSkillFile,
   installSkill,
+  listSkillFileManifest,
   listSkills,
   searchSkills,
   uninstallSkill,
   updateSkill,
+  upsertSkillFile,
+  upsertSkillFiles,
 } from "../be/db";
 import { parseSkillContent } from "../be/skill-parser";
 import { computeAgentSkillsSignature, syncSkillsToFilesystem } from "../be/skill-sync";
@@ -19,6 +24,24 @@ import { json, jsonError } from "./utils";
 const SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE =
   "This skill is system-managed and cannot be edited from the UI; it is re-seeded on each start. Fork it under a new name to customize.";
 
+const skillFileBodySchema = z.object({
+  content: z.string(),
+  mimeType: z.string().optional(),
+  isBinary: z.boolean().optional(),
+  size: z.number().int().nonnegative().optional(),
+});
+
+const skillFileWithPathSchema = skillFileBodySchema.extend({
+  path: z.string().min(1),
+});
+
+function decodeSkillFilePath(pathSegments: string[]): string {
+  return pathSegments
+    .slice(4)
+    .map((segment) => decodeURIComponent(segment))
+    .join("/");
+}
+
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
 const listSkillsRoute = route({
@@ -58,6 +81,86 @@ const getSkillRoute = route({
   },
 });
 
+const listSkillFilesRoute = route({
+  method: "get",
+  path: "/api/skills/{id}/files",
+  pattern: ["api", "skills", null, "files"],
+  summary: "List bundled files for a skill",
+  description: "Returns a manifest of bundled skill files without file content.",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string() }),
+  responses: {
+    200: { description: "Skill file manifest" },
+    404: { description: "Skill not found" },
+  },
+});
+
+const bulkUpsertSkillFilesRoute = route({
+  method: "post",
+  path: "/api/skills/{id}/files",
+  pattern: ["api", "skills", null, "files"],
+  summary: "Bulk upsert bundled files for a skill",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string() }),
+  body: z.object({
+    files: z.array(skillFileWithPathSchema).max(100),
+  }),
+  responses: {
+    200: { description: "Skill files upserted" },
+    400: { description: "Validation error" },
+    404: { description: "Skill not found" },
+  },
+});
+
+const getSkillFileRoute = route({
+  method: "get",
+  path: "/api/skills/{id}/files/{path}",
+  pattern: ["api", "skills", null, "files", null],
+  exact: false,
+  summary: "Get a bundled skill file",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string(), path: z.string() }),
+  responses: {
+    200: { description: "Skill file" },
+    404: { description: "Skill or file not found" },
+  },
+});
+
+const upsertSkillFileRoute = route({
+  method: "put",
+  path: "/api/skills/{id}/files/{path}",
+  pattern: ["api", "skills", null, "files", null],
+  exact: false,
+  summary: "Upsert a bundled skill file",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string(), path: z.string() }),
+  body: skillFileBodySchema,
+  responses: {
+    200: { description: "Skill file upserted" },
+    400: { description: "Validation error" },
+    404: { description: "Skill not found" },
+  },
+});
+
+const deleteSkillFileRoute = route({
+  method: "delete",
+  path: "/api/skills/{id}/files/{path}",
+  pattern: ["api", "skills", null, "files", null],
+  exact: false,
+  summary: "Delete a bundled skill file",
+  tags: ["Skills"],
+  auth: { apiKey: true },
+  params: z.object({ id: z.string(), path: z.string() }),
+  responses: {
+    200: { description: "Skill file deleted" },
+    404: { description: "Skill or file not found" },
+  },
+});
+
 const createSkillRoute = route({
   method: "post",
   path: "/api/skills",
@@ -423,6 +526,128 @@ export async function handleSkills(
     return true;
   }
 
+  // GET /api/skills/:id/files
+  if (listSkillFilesRoute.match(req.method, pathSegments)) {
+    const parsed = await listSkillFilesRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const skill = getSkillById(parsed.params.id);
+    if (!skill) {
+      jsonError(res, "Skill not found", 404);
+      return true;
+    }
+
+    const files = listSkillFileManifest(parsed.params.id);
+    json(res, { files, total: files.length });
+    return true;
+  }
+
+  // POST /api/skills/:id/files
+  if (bulkUpsertSkillFilesRoute.match(req.method, pathSegments)) {
+    const parsed = await bulkUpsertSkillFilesRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const skill = getSkillById(parsed.params.id);
+    if (!skill) {
+      jsonError(res, "Skill not found", 404);
+      return true;
+    }
+    if (skill.systemDefault) {
+      jsonError(res, SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE, 403);
+      return true;
+    }
+
+    try {
+      const files = upsertSkillFiles(parsed.params.id, parsed.body.files);
+      const updatedSkill = getSkillById(parsed.params.id);
+      json(res, { files, total: files.length, skill: updatedSkill });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Failed to upsert files", 400);
+    }
+    return true;
+  }
+
+  // GET /api/skills/:id/files/:path
+  if (getSkillFileRoute.match(req.method, pathSegments)) {
+    const parsed = await getSkillFileRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const skill = getSkillById(parsed.params.id);
+    if (!skill) {
+      jsonError(res, "Skill not found", 404);
+      return true;
+    }
+
+    try {
+      const file = getSkillFile(parsed.params.id, decodeSkillFilePath(pathSegments));
+      if (!file) {
+        jsonError(res, "Skill file not found", 404);
+        return true;
+      }
+      json(res, { file });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Invalid file path", 400);
+    }
+    return true;
+  }
+
+  // PUT /api/skills/:id/files/:path
+  if (upsertSkillFileRoute.match(req.method, pathSegments)) {
+    const parsed = await upsertSkillFileRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const skill = getSkillById(parsed.params.id);
+    if (!skill) {
+      jsonError(res, "Skill not found", 404);
+      return true;
+    }
+    if (skill.systemDefault) {
+      jsonError(res, SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE, 403);
+      return true;
+    }
+
+    try {
+      const file = upsertSkillFile(parsed.params.id, {
+        path: decodeSkillFilePath(pathSegments),
+        ...parsed.body,
+      });
+      const updatedSkill = getSkillById(parsed.params.id);
+      json(res, { file, skill: updatedSkill });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Failed to upsert file", 400);
+    }
+    return true;
+  }
+
+  // DELETE /api/skills/:id/files/:path
+  if (deleteSkillFileRoute.match(req.method, pathSegments)) {
+    const parsed = await deleteSkillFileRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const skill = getSkillById(parsed.params.id);
+    if (!skill) {
+      jsonError(res, "Skill not found", 404);
+      return true;
+    }
+    if (skill.systemDefault) {
+      jsonError(res, SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE, 403);
+      return true;
+    }
+
+    try {
+      const deleted = deleteSkillFile(parsed.params.id, decodeSkillFilePath(pathSegments));
+      if (!deleted) {
+        jsonError(res, "Skill file not found", 404);
+        return true;
+      }
+      const updatedSkill = getSkillById(parsed.params.id);
+      json(res, { success: true, skill: updatedSkill });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Invalid file path", 400);
+    }
+    return true;
+  }
+
   // GET /api/skills/:id
   if (getSkillRoute.match(req.method, pathSegments)) {
     const parsed = await getSkillRoute.parse(req, res, pathSegments, queryParams);

package/src/prompts/session-templates.ts

@@ -378,11 +378,9 @@ registerTemplate({
 
 You have access to the \`context-mode\` MCP tools (\`batch_execute\`, \`execute\`, \`execute_file\`, \`search\`, \`fetch_and_index\`, \`index\`) which compress tool output to save context window space. For data-heavy operations (web fetches, large file reads, CLI output processing), prefer these over raw Bash/WebFetch to avoid flooding your context window with raw output.
 
-When a tool returns more than a few dozen lines — JSON payloads, log tails, search results, API responses — route it through \`ctx_execute\` or \`ctx_batch_execute\` so only the derived answer enters your conversation. This is especially important for tasks that make many Bash/Read/MCP calls in sequence; each raw response compounds context pressure.
-
 ### Agent Scripts — for bulk, repetitive, or data-heavy work
 
-Use **scripts** (\`script-upsert\` + \`script-run\`) when a task involves repetitive SDK calls, large data processing, or deterministic multi-step pipelines. Scripts run out-of-process and return only their final result — none of the intermediate output floods your context window.
+Use **scripts** (\`script-upsert\` + \`script-run\`) when a task involves repetitive SDK calls, large data processing, or deterministic multi-step pipelines. Scripts run out-of-process and return only their final result.
 
 **Decision rubric — when to use scripts vs. other approaches:**
 
@@ -394,7 +392,6 @@ Use **scripts** (\`script-upsert\` + \`script-run\`) when a task involves repeti
 | Single expensive web fetch | \`ctx_fetch_and_index\` (context-mode) |
 | Multi-agent fan-out, parallel work, deterministic pipeline | **Workflow** |
 | One-off bash/TS with no reuse needed | \`code-mode run\` (Bash) |
-| Same logic needed across sessions/agents | **Named script** (\`script-upsert\` + reuse) |
 
 The 5 script tools (\`script-search\`, \`script-run\`, \`script-upsert\`, \`script-delete\`, \`script-query-types\`) are deferred tools. Call ToolSearch to load \`script-upsert\`, \`script-run\`, and \`script-query-types\` before using them.
 
@@ -407,6 +404,27 @@ The 5 script tools (\`script-search\`, \`script-run\`, \`script-upsert\`, \`scri
   category: "system",
 });
 
+registerTemplate({
+  eventType: "system.agent.seed_scripts",
+  header: "",
+  defaultBody: `
+### Pre-built Seed Scripts
+
+The swarm ships named scripts at global scope — each replaces a multi-step tool chain.
+See the \`swarm-scripts\` skill for the full catalog, signatures, and usage patterns.
+
+**At every task start (do this FIRST):** Run \`task-context-gathering\` with the task ID and 2-4 queries from the task description. Returns a slimmed task projection + deduped memories in one call — replaces task_get + memory_search loops.
+
+**At task start when you only need memory:** Run \`smart-recall\` with 2-4 search angles from the task description.
+
+**For any other repetitive multi-tool pattern:** Call \`script-search\` with a natural-language description. If a script exists, use it.
+
+Script tools are deferred — load via \`ToolSearch("select:script-search,script-run")\` before first use.
+`,
+  variables: [],
+  category: "system",
+});
+
 // system.agent.guidelines removed — its content (communication etiquette, todos)
 // is covered by worker/lead templates and filesystem template respectively.
 
@@ -602,6 +620,7 @@ registerTemplate({
 {{@template[system.agent.filesystem]}}
 {{@template[system.agent.self_awareness]}}
 {{@template[system.agent.context_mode]}}
+{{@template[system.agent.seed_scripts]}}
 
 {{@template[system.agent.system]}}
 {{@template[system.agent.share_urls]}}
@@ -623,6 +642,7 @@ registerTemplate({
 {{@template[system.agent.filesystem]}}
 {{@template[system.agent.self_awareness]}}
 {{@template[system.agent.context_mode]}}
+{{@template[system.agent.seed_scripts]}}
 
 {{@template[system.agent.system]}}
 {{@template[system.agent.share_urls]}}

package/src/providers/claude-adapter.ts

@@ -72,9 +72,8 @@ async function cleanupTaskFile(pid: number): Promise<void> {
 /**
  * Parse `CLAUDE_BINARY` into argv prefix tokens.
  *
- * Accepts a single binary name (`"claude"`, `"shannon"`), an absolute path,
- * or a whitespace-separated command string (`"bunx @dexh/shannon"`,
- * `"npx -y @dexh/shannon"`). Trim + split on `/\s+/`. No shell parsing, no
+ * Accepts a single binary name (`"claude"`), an absolute path, or a
+ * whitespace-separated command string. Trim + split on `/\s+/`. No shell parsing, no
  * quote handling — keep it tiny and predictable. Empty / missing → `["claude"]`.
  *
  * Exported for unit testing.
@@ -108,14 +107,81 @@ export function resolveClaudeBinary(
   return candidate || "claude";
 }
 
+const CLAUDE_BRIDGE_BINARY = "claude-bridge";
+const CLAUDE_BRIDGE_LOCAL_AUTH_ARG = "--desplega-local-auth";
+const LEGACY_CLAUDE_BRIDGE_COMPAT_BINARY = "shan" + "non";
+const CLAUDE_BRIDGE_LOCAL_AUTH_ENV_VARS = [
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "ANTHROPIC_BASE_URL",
+  "ANTHROPIC_CUSTOM_HEADERS",
+  "ANTHROPIC_MODEL",
+] as const;
+
+/**
+ * Parse a boolean env toggle. Only true/1 enable and false/0 disable; unset
+ * and invalid values are treated as disabled.
+ *
+ * Exported for unit testing.
+ */
+export function parseClaudeBridgeEnabled(raw: string | undefined): boolean {
+  const normalized = raw?.trim().toLowerCase();
+  return normalized === "true" || normalized === "1";
+}
+
+/**
+ * Resolve the reloadable claude-bridge toggle from the same resolved-env
+ * overlay used for `CLAUDE_BINARY`.
+ *
+ * Exported for unit testing.
+ */
+export function resolveClaudeBridgeEnabled(
+  resolvedEnv: Record<string, string | undefined>,
+  fallbackEnv: Record<string, string | undefined> = process.env,
+): boolean {
+  const candidate =
+    resolvedEnv.SWARM_USE_CLAUDE_BRIDGE?.trim() || fallbackEnv.SWARM_USE_CLAUDE_BRIDGE?.trim();
+  return parseClaudeBridgeEnabled(candidate);
+}
+
+function resolveClaudeBinaryArgv(
+  resolvedEnv: Record<string, string | undefined>,
+  fallbackEnv: Record<string, string | undefined> = process.env,
+): { raw: string; argv: string[]; useClaudeBridge: boolean } {
+  const useClaudeBridge = resolveClaudeBridgeEnabled(resolvedEnv, fallbackEnv);
+  const raw = useClaudeBridge
+    ? CLAUDE_BRIDGE_BINARY
+    : resolveClaudeBinary(resolvedEnv, fallbackEnv);
+  return { raw, argv: parseClaudeBinary(raw), useClaudeBridge };
+}
+
+function isLegacyClaudeBridgeCompatBinary(raw: string): boolean {
+  return raw.toLowerCase().includes(LEGACY_CLAUDE_BRIDGE_COMPAT_BINARY);
+}
+
+function withClaudeBridgeAuthArgs(
+  argv: readonly string[],
+  sourceEnv: Record<string, string | undefined>,
+): string[] {
+  if (sourceEnv.CLAUDE_CODE_OAUTH_TOKEN) {
+    return [...argv];
+  }
+
+  if (CLAUDE_BRIDGE_LOCAL_AUTH_ENV_VARS.some((name) => sourceEnv[name])) {
+    return [...argv, CLAUDE_BRIDGE_LOCAL_AUTH_ARG];
+  }
+
+  return [...argv];
+}
+
 /**
  * Pre-seed `~/.claude.json` so the per-project trust-dialog ("Quick safety
  * check: Is this a project you trust?") doesn't block on first run.
  *
  * Mirrors the onboarding-skip hack in `Dockerfile.worker` (which writes
  * `hasCompletedOnboarding` and `bypassPermissionsModeAccepted`). When the
- * resolved binary contains "shannon", claude runs inside tmux and shannon
- * does NOT auto-accept the dialog, so the pane hangs forever. Writing
+ * resolved binary runs interactive claude inside tmux, claude does NOT
+ * reliably auto-accept the dialog, so the pane can hang forever. Writing
  * `projects[cwd].hasTrustDialogAccepted = true` (and `hasCompletedProjectOnboarding`)
  * tells claude-code the cwd is pre-trusted.
  *
@@ -793,46 +859,59 @@ export class ClaudeAdapter implements ProviderAdapter {
 
     const model = config.model || "opus";
 
-    const credType = validateClaudeCredentials(config.env || process.env);
+    const sourceEnv = config.env || process.env;
+    const credType = validateClaudeCredentials(sourceEnv);
     console.log(`\x1b[2m[claude]\x1b[0m Using credential: ${credType}`);
 
     // Resolve the argv prefix. Same flags (`-p`, `--model`, ...) work across
-    // alternates; only argv[0..n] changes. `CLAUDE_BINARY` accepts a single
-    // binary (`"shannon"`, `"/usr/local/bin/shannon"`) or a whitespace-separated
-    // command string (`"bunx @dexh/shannon"`, `"npx -y @dexh/shannon"`).
-    // Setting it to anything containing `shannon` opts into the dexhorthy/shannon
-    // variant, which drives `claude` interactively in tmux to stay on the
-    // subscription credit pool after the 2026-06-15 programmatic-credit split.
+    // alternates; only argv[0..n] changes. Prefer SWARM_USE_CLAUDE_BRIDGE=true
+    // for the Desplega-owned bridge. CLAUDE_BINARY remains as the low-level
+    // override for custom binaries and the legacy third-party bridge path.
     //
     // `config.env` carries the swarm_config overlay (resolved repo > agent > global
     // by `fetchResolvedEnv` in src/commands/runner.ts), so operators can flip
     // a worker's binary via `set-config CLAUDE_BINARY=...` without a restart.
     // Falls back to process.env, then "claude". See `resolveClaudeBinary` above.
     //
-    // See `docs-site/.../shannon-experimental.mdx` for the user-facing guide
+    // See `docs-site/.../claude-bridge-experimental.mdx` for the user-facing guide
     // and `runbooks/harness-providers.md` for engineering notes.
-    const claudeBinaryRaw = resolveClaudeBinary(config.env || process.env);
-    const claudeBinaryArgv = parseClaudeBinary(claudeBinaryRaw);
-    const isShannon = claudeBinaryRaw.toLowerCase().includes("shannon");
+    const {
+      raw: claudeBinaryRaw,
+      argv: claudeBinaryArgv,
+      useClaudeBridge,
+    } = resolveClaudeBinaryArgv(sourceEnv);
+    const isLegacyBridgeCompat = isLegacyClaudeBridgeCompatBinary(claudeBinaryRaw);
+    const effectiveClaudeBinaryArgv = useClaudeBridge
+      ? withClaudeBridgeAuthArgs(claudeBinaryArgv, sourceEnv)
+      : claudeBinaryArgv;
+    const isInteractiveTmuxClaude = isLegacyBridgeCompat || useClaudeBridge;
+    const configuredClaudeBinaryRaw = resolveClaudeBinary(sourceEnv);
+    if (isLegacyClaudeBridgeCompatBinary(configuredClaudeBinaryRaw)) {
+      console.warn(
+        `\x1b[33m[claude]\x1b[0m CLAUDE_BINARY=${LEGACY_CLAUDE_BRIDGE_COMPAT_BINARY} is deprecated; set SWARM_USE_CLAUDE_BRIDGE=true to use @desplega.ai/claude-bridge.`,
+      );
+    }
 
     console.log(
-      `\x1b[2m[${config.role}]\x1b[0m Resolved CLAUDE_BINARY: ${claudeBinaryArgv.join(" ")} (isShannon: ${isShannon})`,
+      `\x1b[2m[${config.role}]\x1b[0m Resolved claude binary: ${effectiveClaudeBinaryArgv.join(" ")} (useClaudeBridge: ${useClaudeBridge}, legacyBridgeCompat: ${isLegacyBridgeCompat})`,
     );
 
-    // Fail fast: shannon shells out to tmux. If it's missing, surface a
-    // clear error here rather than letting the spawn fail opaquely.
-    if (isShannon && !Bun.which("tmux")) {
+    // Fail fast: claude-bridge and its legacy compatibility path both shell
+    // out to tmux. If it's
+    // missing, surface a clear error here rather than letting startup fail
+    // opaquely.
+    if (isInteractiveTmuxClaude && !Bun.which("tmux")) {
+      const label = useClaudeBridge
+        ? "SWARM_USE_CLAUDE_BRIDGE=true"
+        : `CLAUDE_BINARY=${LEGACY_CLAUDE_BRIDGE_COMPAT_BINARY}`;
       throw new Error(
-        "CLAUDE_BINARY=shannon requires 'tmux' on PATH (install via apt/brew). See runbooks/harness-providers.md.",
+        `${label} requires 'tmux' on PATH (install via apt/brew). See runbooks/harness-providers.md.`,
       );
     }
 
-    // Shannon drives `claude` in tmux — claude's per-project trust dialog
-    // (first-run "Is this a project you trust?") hangs the pane because shannon
-    // doesn't auto-accept it. Pre-seed `~/.claude.json` so the dialog never
-    // prompts. Idempotent; no-op when already trusted. Engineering rationale:
-    // `runbooks/harness-providers.md` § "Trust-dialog pre-seed".
-    if (isShannon) {
+    // Claude Bridge and its legacy compatibility path drive interactive
+    // `claude` in tmux, where the first-run trust dialog can block startup.
+    if (isInteractiveTmuxClaude) {
       try {
         await preseedClaudeTrustDialog(config.cwd);
       } catch (err) {
@@ -897,7 +976,7 @@ export class ClaudeAdapter implements ProviderAdapter {
       taskFilePath,
       taskFilePid,
       sessionMcpConfig,
-      claudeBinaryArgv,
+      effectiveClaudeBinaryArgv,
       systemPromptFile,
     );
   }

package/src/script-workflows/executor.ts

@@ -0,0 +1,110 @@
+import { existsSync } from "node:fs";
+import { mkdir, rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { ScriptRun } from "../types";
+
+export type ScriptExecutionResult = {
+  exitCode: number | null;
+  stderr: string;
+};
+
+export type ScriptExecutionHandle = {
+  pid: number | null;
+  tmpdir: string;
+  startedAtMs: number;
+  exited: Promise<ScriptExecutionResult>;
+  terminate(signal?: NodeJS.Signals): void;
+  cleanup(): Promise<void>;
+};
+
+export type StartScriptExecutionInput = {
+  run: ScriptRun;
+  baseUrl: string;
+  apiKey: string;
+};
+
+export interface ScriptExecutor {
+  start(input: StartScriptExecutionInput): Promise<ScriptExecutionHandle>;
+  isRunning(pid: number): boolean;
+  terminatePid(pid: number, signal?: NodeJS.Signals): void;
+}
+
+export function getScriptWorkflowHarnessPath(): string {
+  const runtimeDir = process.env.SCRIPT_WORKFLOW_RUNTIME_DIR;
+  if (!runtimeDir) return new URL("./harness.ts", import.meta.url).pathname;
+
+  const bundledHarness = `${resolve(runtimeDir)}/harness.bundle.js`;
+  if (!existsSync(bundledHarness)) {
+    throw new Error(
+      `Script workflow harness bundle not found at ${bundledHarness}. ` +
+        "Build/copy harness.bundle.js and set SCRIPT_WORKFLOW_RUNTIME_DIR to its directory.",
+    );
+  }
+  return bundledHarness;
+}
+
+export class LocalProcessScriptExecutor implements ScriptExecutor {
+  async start(input: StartScriptExecutionInput): Promise<ScriptExecutionHandle> {
+    const { run, baseUrl, apiKey } = input;
+    const tmpdir = `${process.env.TMPDIR ?? "/tmp"}/script-workflow-${run.id}`;
+    await mkdir(tmpdir, { recursive: true });
+    const sourceFile = `${tmpdir}/source.ts`;
+    const argsFile = `${tmpdir}/args.json`;
+    await Bun.write(sourceFile, run.source);
+    await Bun.write(argsFile, JSON.stringify(run.args ?? null));
+
+    const proc = Bun.spawn(["bun", "run", getScriptWorkflowHarnessPath()], {
+      cwd: tmpdir,
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "pipe",
+      env: {
+        PATH: process.env.PATH ?? "/usr/bin:/bin",
+        HOME: process.env.HOME ?? "/tmp",
+        LANG: process.env.LANG ?? "C.UTF-8",
+        LC_ALL: process.env.LC_ALL ?? "C.UTF-8",
+        TMPDIR: tmpdir,
+        AGENT_SWARM_API_KEY: apiKey,
+        MCP_BASE_URL: baseUrl,
+        SCRIPT_RUN_ID: run.id,
+        SCRIPT_RUN_AGENT_ID: run.agentId,
+        SCRIPT_RUN_TMPDIR: tmpdir,
+        SCRIPT_RUN_SOURCE_FILE: sourceFile,
+        SCRIPT_RUN_ARGS_FILE: argsFile,
+      },
+    });
+
+    const stderrPromise = new Response(proc.stderr).text().catch(() => "");
+
+    return {
+      pid: proc.pid,
+      tmpdir,
+      startedAtMs: Date.now(),
+      exited: proc.exited.then(async (exitCode) => ({
+        exitCode,
+        stderr: await stderrPromise,
+      })),
+      terminate: (signal = "SIGTERM") => {
+        proc.kill(signal);
+      },
+      cleanup: async () => {
+        await rm(tmpdir, { recursive: true, force: true });
+      },
+    };
+  }
+
+  isRunning(pid: number): boolean {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  terminatePid(pid: number, signal: NodeJS.Signals = "SIGTERM"): void {
+    process.kill(pid, signal);
+  }
+}
+
+export const localProcessScriptExecutor = new LocalProcessScriptExecutor();