@desplega.ai/agent-swarm 1.100.3 → 1.101.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.100.3",
+    "version": "1.101.0",
     "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.100.3",
+  "version": "1.101.0",
   "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/scripts/typecheck.ts

@@ -149,7 +149,7 @@ export interface SwarmSdk {
   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; input?: Record<string, unknown> }): Promise<unknown>;
+  workflow_trigger(args: { id: string; triggerData?: Record<string, unknown> }): Promise<unknown>;
   workflow_retryRun(args: { id: string }): Promise<unknown>;
   workflow_cancelRun(args: { id: string }): Promise<unknown>;
 

package/src/commands/codex-login.ts

@@ -182,7 +182,7 @@ Usage:
 Options:
   --api-url <url>    Swarm API URL (default: MCP_BASE_URL or http://localhost:3013)
   --api-key <key>    Swarm API key (default: API_KEY or 123123)
-  --slot <n>         Credential pool slot (0-9, default: next free slot)
+  --slot <n>         Credential pool slot (0-100, default: next free slot)
   -h, --help         Show this help
 
 Without flags, the command prompts interactively for the target API URL and
@@ -198,7 +198,7 @@ Deployed Codex workers automatically restore these credentials at boot.
 `);
 }
 
-const MAX_SLOT = 9;
+const MAX_SLOT = 100;
 
 export async function runCodexLogin(args: string[], deps: RunCodexLoginDeps = {}): Promise<void> {
   const resolveConfig = deps.resolveConfig ?? resolveCodexLoginConfig;

package/src/http/mcp-bridge.ts

@@ -2,7 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { createServer } from "@/server";
-import { isSdkToolAllowed } from "../scripts-runtime/sdk-allowlist";
+import { isMcpToolAllowedForScripts } from "../scripts-runtime/sdk-allowlist";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
 
@@ -55,7 +55,7 @@ export async function handleMcpBridge(
 
   const { tool: toolName, args } = parsed.body;
 
-  if (!isSdkToolAllowed(toolName)) {
+  if (!isMcpToolAllowedForScripts(toolName)) {
     jsonError(res, `Tool '${toolName}' is not in the SDK allowlist`, 403);
     return true;
   }

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

@@ -1,3 +1,4 @@
+import { mcpToolNameForSdkMethod } from "../scripts-runtime/sdk-allowlist";
 import { stdlib } from "../scripts-runtime/stdlib";
 
 type StepStatusResponse =
@@ -161,7 +162,7 @@ export function buildWorkflowCtx(input: {
       return (args?: unknown) =>
         fetchJson("/api/mcp-bridge", {
           method: "POST",
-          body: JSON.stringify({ tool: prop.replaceAll("_", "-"), args: args ?? {} }),
+          body: JSON.stringify({ tool: mcpToolNameForSdkMethod(prop), args: args ?? {} }),
         });
     },
   });

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

@@ -145,10 +145,18 @@ export const SDK_ALLOWLIST = Object.keys(SDK_TOOL_NAME_MAP) as Array<
   keyof typeof SDK_TOOL_NAME_MAP
 >;
 
+/** Set of MCP tool names (values of SDK_TOOL_NAME_MAP) that scripts may call via the bridge. */
+const MCP_TOOL_NAMES: ReadonlySet<string> = new Set<string>(Object.values(SDK_TOOL_NAME_MAP));
+
 export function isSdkToolAllowed(name: string): boolean {
   return (SDK_ALLOWLIST as readonly string[]).includes(name);
 }
 
+/** True if `mcpToolName` (e.g. "trigger-workflow") corresponds to an allowlisted SDK method. */
+export function isMcpToolAllowedForScripts(mcpToolName: string): boolean {
+  return MCP_TOOL_NAMES.has(mcpToolName);
+}
+
 export function mcpToolNameForSdkMethod(name: string): string {
   return SDK_TOOL_NAME_MAP[name as keyof typeof SDK_TOOL_NAME_MAP] ?? name;
 }

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

@@ -243,7 +243,7 @@ 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; input?: Record<string, unknown> }): Promise<unknown>;
+    workflow_trigger(args: { id: string; triggerData?: Record<string, unknown> }): Promise<unknown>;
     workflow_retryRun(args: { id: string }): Promise<unknown>;
     workflow_cancelRun(args: { id: string }): Promise<unknown>;
 

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

@@ -225,7 +225,7 @@ 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; input?: Record<string, unknown> }): Promise<unknown>;
+    workflow_trigger(args: { id: string; triggerData?: Record<string, unknown> }): Promise<unknown>;
     workflow_retryRun(args: { id: string }): Promise<unknown>;
     workflow_cancelRun(args: { id: string }): Promise<unknown>;
 

package/src/tests/codex-login.test.ts

@@ -246,7 +246,7 @@ describe("runCodexLogin", () => {
       resolveConfig: async () => ({
         apiUrl: "http://localhost:3013",
         apiKey: "test-key",
-        slot: 15,
+        slot: 101,
       }),
       login: mock(async () => {
         throw new Error("should not start oauth");
@@ -259,18 +259,46 @@ describe("runCodexLogin", () => {
     });
 
     expect(error).toHaveBeenCalledWith(
-      expect.stringContaining("--slot must be an integer between 0 and 9"),
+      expect.stringContaining("--slot must be an integer between 0 and 100"),
     );
     expect(exit).toHaveBeenCalledWith(1);
     expect(store).not.toHaveBeenCalled();
   });
 
+  it("accepts slot 10 (previously rejected by the old 0-9 cap)", async () => {
+    let storedSlot: number | undefined;
+    const store = mock(async (_apiUrl: string, _apiKey: string, _creds: unknown, slot?: number) => {
+      storedSlot = slot;
+    });
+
+    await runCodexLogin([], {
+      resolveConfig: async () => ({
+        apiUrl: "http://localhost:3013",
+        apiKey: "test-key",
+        slot: 10,
+      }),
+      login: mock(async () => ({
+        access: "at_test",
+        refresh: "rt_test",
+        expires: Date.now() + 3600000,
+        accountId: "acc-test",
+      })),
+      store,
+      loadAllSlots: mock(async () => []),
+      log: () => {},
+      error: () => {},
+      exit: () => {},
+    });
+
+    expect(storedSlot).toBe(10);
+  });
+
   it("errors when all slots are occupied", async () => {
     const error = mock(() => {});
     const exit = mock(() => {});
 
-    // All 10 slots occupied
-    const allSlots = Array.from({ length: 10 }, (_, i) => ({
+    // All 101 slots occupied (0-100)
+    const allSlots = Array.from({ length: 101 }, (_, i) => ({
       slot: i,
       creds: { access: "", refresh: "", expires: 0, accountId: "" },
     }));

package/src/tests/sdk-allowlist.test.ts

@@ -1,7 +1,14 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { unlink } from "node:fs/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Readable } from "node:stream";
 import { closeDb, initDb } from "../be/db";
-import { mcpToolNameForSdkMethod, SDK_ALLOWLIST } from "../scripts-runtime/sdk-allowlist";
+import { handleMcpBridge } from "../http/mcp-bridge";
+import {
+  isMcpToolAllowedForScripts,
+  mcpToolNameForSdkMethod,
+  SDK_ALLOWLIST,
+} from "../scripts-runtime/sdk-allowlist";
 import type { SwarmConfig } from "../scripts-runtime/swarm-config";
 import { createSwarmSdk } from "../scripts-runtime/swarm-sdk";
 import { createServer } from "../server";
@@ -56,4 +63,119 @@ describe("script SDK allowlist", () => {
     expect(types).not.toContain("join_swarm(");
     expect(types).not.toContain("start_worker(");
   });
+
+  test("isMcpToolAllowedForScripts accepts every MCP name in the allowlist", () => {
+    for (const sdkName of SDK_ALLOWLIST) {
+      const mcpName = mcpToolNameForSdkMethod(sdkName);
+      expect(isMcpToolAllowedForScripts(mcpName)).toBe(true);
+    }
+  });
+
+  test("isMcpToolAllowedForScripts rejects non-mapped MCP names", () => {
+    // SDK method names (underscores) are not MCP names — must be rejected
+    expect(isMcpToolAllowedForScripts("workflow_trigger")).toBe(false);
+    expect(isMcpToolAllowedForScripts("slack_post")).toBe(false);
+    // Completely unknown tool names
+    expect(isMcpToolAllowedForScripts("tool-does-not-exist")).toBe(false);
+    expect(isMcpToolAllowedForScripts("start-worker")).toBe(false);
+  });
+
+  test("bundled swarm-sdk.d.ts uses triggerData (not input) for workflow_trigger", async () => {
+    const types = await Bun.file("src/scripts-runtime/types/swarm-sdk.d.ts").text();
+    expect(types).toContain("workflow_trigger(args: { id: string; triggerData?");
+    expect(types).not.toContain("workflow_trigger(args: { id: string; input?");
+  });
+});
+
+describe("mcp-bridge allowlist gate", () => {
+  const TEST_DB_PATH = "./test-sdk-allowlist-bridge.sqlite";
+  const API_KEY = "test-mcp-bridge-key-1234567890";
+  let prevApiKey: string | undefined;
+
+  async function removeDbFiles(path: string): Promise<void> {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(path + suffix);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+    }
+  }
+
+  beforeAll(async () => {
+    await removeDbFiles(TEST_DB_PATH);
+    initDb(TEST_DB_PATH);
+    prevApiKey = process.env.AGENT_SWARM_API_KEY;
+    process.env.AGENT_SWARM_API_KEY = API_KEY;
+  });
+
+  afterAll(async () => {
+    closeDb();
+    await removeDbFiles(TEST_DB_PATH);
+    if (prevApiKey === undefined) {
+      delete process.env.AGENT_SWARM_API_KEY;
+    } else {
+      process.env.AGENT_SWARM_API_KEY = prevApiKey;
+    }
+  });
+
+  async function postBridge(
+    body: Record<string, unknown>,
+  ): Promise<{ status: number; body: unknown }> {
+    const raw = JSON.stringify(body);
+    const req = Readable.from([Buffer.from(raw)]) as IncomingMessage;
+    req.method = "POST";
+    req.url = "/api/mcp-bridge";
+    req.headers = {
+      authorization: `Bearer ${API_KEY}`,
+      "content-type": "application/json",
+      "x-agent-id": "test-agent-bridge",
+    };
+
+    let status = 200;
+    let text = "";
+    const res = {
+      headersSent: false,
+      writableEnded: false,
+      setHeader() {},
+      writeHead(code: number) {
+        status = code;
+        this.headersSent = true;
+        return this;
+      },
+      end(chunk?: unknown) {
+        if (chunk !== undefined) text += String(chunk);
+        this.writableEnded = true;
+        return this;
+      },
+    } as unknown as ServerResponse;
+
+    await handleMcpBridge(
+      req,
+      res,
+      ["api", "mcp-bridge"],
+      new URLSearchParams(),
+      "test-agent-bridge",
+    );
+    return { status, body: text ? JSON.parse(text) : {} };
+  }
+
+  test("trigger-workflow is NOT rejected with 403 (reaches tool handler)", async () => {
+    const result = await postBridge({
+      tool: "trigger-workflow",
+      args: { id: "00000000-0000-0000-0000-000000000001" },
+    });
+    // Must not be an allowlist 403; may be 404/500 (non-existent workflow) — that's fine.
+    expect(result.status).not.toBe(403);
+  });
+
+  test("genuinely non-mapped MCP names still return 403", async () => {
+    // SDK method names (underscores) are not valid MCP names — must 403
+    const sdkNameResult = await postBridge({ tool: "workflow_trigger", args: { id: "x" } });
+    expect(sdkNameResult.status).toBe(403);
+
+    // Completely unknown tool names
+    const unknownResult = await postBridge({ tool: "start-worker", args: {} });
+    expect(unknownResult.status).toBe(403);
+  });
 });

package/src/tests/workflow-ctx.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { buildWorkflowCtx } from "../script-workflows/workflow-ctx";
+
+describe("workflow-ctx: ctx.swarm proxy tool name resolution", () => {
+  test("non-mechanical SDK→MCP mappings are routed correctly", async () => {
+    const captured: string[] = [];
+    const origFetch = globalThis.fetch;
+
+    globalThis.fetch = async (url: unknown, init?: RequestInit) => {
+      if (typeof url === "string" && url.includes("/api/mcp-bridge")) {
+        const body = JSON.parse((init?.body as string) ?? "{}");
+        captured.push(body.tool);
+        return new Response(JSON.stringify({ ok: true }), { status: 200 });
+      }
+      return origFetch(url as URL, init);
+    };
+
+    try {
+      const ctx = buildWorkflowCtx({
+        runId: "test-run",
+        agentId: "test-agent",
+        apiKey: "test-key",
+        baseUrl: "http://localhost:9999",
+        args: {},
+      });
+
+      // Non-mechanical: SDK method name ≠ kebab-cased MCP name
+      await ctx.swarm.workflow_trigger({ id: "wf-1" }); // → "trigger-workflow" (not "workflow-trigger")
+      await ctx.swarm.page_create({ title: "T" }); // → "create_page"       (not "page-create")
+      await ctx.swarm.memory_rate({ id: "x" }); // → "memory_rate"       (not "memory-rate")
+
+      // Mechanical: verify mechanical mappings still work
+      await ctx.swarm.memory_search({ query: "q" }); // → "memory-search"
+    } finally {
+      globalThis.fetch = origFetch;
+    }
+
+    expect(captured[0]).toBe("trigger-workflow");
+    expect(captured[1]).toBe("create_page");
+    expect(captured[2]).toBe("memory_rate");
+    expect(captured[3]).toBe("memory-search");
+  });
+});

package/src/tests/workflow-swarm-script.test.ts

@@ -255,6 +255,231 @@ describe("SwarmScriptExecutor", () => {
     expect(scriptStep?.output).toMatchObject({ result: { seen: "mapped-value" } });
   });
 
+  test("exact object token outside swarm-script args is still stringified", async () => {
+    const wf = makeWorkflow({
+      nodes: [
+        {
+          id: "echo",
+          type: "echo",
+          config: { value: "{{trigger.payload}}" },
+        },
+      ],
+    });
+
+    const runId = await startWorkflowExecution(wf, { payload: { a: 1 } }, registry);
+    const run = getWorkflowRun(runId);
+    const steps = getWorkflowRunStepsByRunId(runId);
+    const echoStep = steps.find((step) => step.nodeId === "echo");
+
+    expect(run?.status).toBe("completed");
+    expect(echoStep?.status).toBe("completed");
+    expect(echoStep?.output).toEqual({ value: '{"a":1}' });
+  });
+
+  test("{{path}} args: object arg is injected as raw object, not JSON string", async () => {
+    await saveScript(
+      "echo-obj",
+      `export default async (args: { data: Record<string, unknown> }) => ({ isObject: typeof args.data === "object" && !Array.isArray(args.data), keys: Object.keys(args.data ?? {}) });`,
+    );
+    const wf = makeWorkflow({
+      nodes: [
+        {
+          id: "script",
+          type: "swarm-script",
+          config: {
+            scriptName: "echo-obj",
+            args: { data: "{{trigger.payload}}" },
+          },
+        },
+      ],
+    });
+
+    const runId = await startWorkflowExecution(wf, { payload: { a: 1, b: 2 } }, registry);
+    const run = getWorkflowRun(runId);
+    const steps = getWorkflowRunStepsByRunId(runId);
+    const scriptStep = steps.find((step) => step.nodeId === "script");
+
+    expect(run?.status).toBe("completed");
+    expect(scriptStep?.status).toBe("completed");
+    expect(scriptStep?.output).toMatchObject({ result: { isObject: true, keys: ["a", "b"] } });
+  });
+
+  test("{{path}} args: array arg is injected as raw array, not JSON string", async () => {
+    await saveScript(
+      "echo-arr",
+      `export default async (args: { items: string[] }) => ({ isArray: Array.isArray(args.items), length: args.items.length });`,
+    );
+    const wf = makeWorkflow({
+      nodes: [
+        {
+          id: "script",
+          type: "swarm-script",
+          config: {
+            scriptName: "echo-arr",
+            args: { items: "{{trigger.list}}" },
+          },
+        },
+      ],
+    });
+
+    const runId = await startWorkflowExecution(wf, { list: ["x", "y", "z"] }, registry);
+    const run = getWorkflowRun(runId);
+    const steps = getWorkflowRunStepsByRunId(runId);
+    const scriptStep = steps.find((step) => step.nodeId === "script");
+
+    expect(run?.status).toBe("completed");
+    expect(scriptStep?.status).toBe("completed");
+    expect(scriptStep?.output).toMatchObject({ result: { isArray: true, length: 3 } });
+  });
+
+  test("{{path}} args: empty array is injected as raw empty array with length 0, not '[]' string", async () => {
+    await saveScript(
+      "echo-empty-arr",
+      `export default async (args: { items: string[] }) => ({ isArray: Array.isArray(args.items), length: args.items.length });`,
+    );
+    const wf = makeWorkflow({
+      nodes: [
+        {
+          id: "script",
+          type: "swarm-script",
+          config: {
+            scriptName: "echo-empty-arr",
+            args: { items: "{{trigger.empty}}" },
+          },
+        },
+      ],
+    });
+
+    const runId = await startWorkflowExecution(wf, { empty: [] }, registry);
+    const run = getWorkflowRun(runId);
+    const steps = getWorkflowRunStepsByRunId(runId);
+    const scriptStep = steps.find((step) => step.nodeId === "script");
+
+    expect(run?.status).toBe("completed");
+    expect(scriptStep?.status).toBe("completed");
+    expect(scriptStep?.output).toMatchObject({ result: { isArray: true, length: 0 } });
+  });
+
+  test("{{path}} args: string scalar arg is injected as the string value", async () => {
+    await saveScript(
+      "echo-str",
+      `export default async (args: { name: string }) => ({ isString: typeof args.name === "string", value: args.name });`,
+    );
+    const wf = makeWorkflow({
+      nodes: [
+        {
+          id: "script",
+          type: "swarm-script",
+          config: {
+            scriptName: "echo-str",
+            args: { name: "{{trigger.ruleName}}" },
+          },
+        },
+      ],
+    });
+
+    const runId = await startWorkflowExecution(
+      wf,
+      { ruleName: "local-rules/cognitive-complexity" },
+      registry,
+    );
+    const run = getWorkflowRun(runId);
+    const steps = getWorkflowRunStepsByRunId(runId);
+    const scriptStep = steps.find((step) => step.nodeId === "script");
+
+    expect(run?.status).toBe("completed");
+    expect(scriptStep?.status).toBe("completed");
+    expect(scriptStep?.output).toMatchObject({
+      result: { isString: true, value: "local-rules/cognitive-complexity" },
+    });
+  });
+
+  test("{{path}} args: number scalar arg is injected as a number, not a string", async () => {
+    await saveScript(
+      "echo-num",
+      `export default async (args: { count: number }) => ({ isNumber: typeof args.count === "number", value: args.count });`,
+    );
+    const wf = makeWorkflow({
+      nodes: [
+        {
+          id: "script",
+          type: "swarm-script",
+          config: {
+            scriptName: "echo-num",
+            args: { count: "{{trigger.maxFiles}}" },
+          },
+        },
+      ],
+    });
+
+    const runId = await startWorkflowExecution(wf, { maxFiles: 3 }, registry);
+    const run = getWorkflowRun(runId);
+    const steps = getWorkflowRunStepsByRunId(runId);
+    const scriptStep = steps.find((step) => step.nodeId === "script");
+
+    expect(run?.status).toBe("completed");
+    expect(scriptStep?.status).toBe("completed");
+    expect(scriptStep?.output).toMatchObject({ result: { isNumber: true, value: 3 } });
+  });
+
+  test("{{path}} args: boolean scalar arg is injected as a boolean, not a string", async () => {
+    await saveScript(
+      "echo-bool",
+      `export default async (args: { enabled: boolean }) => ({ isBoolean: typeof args.enabled === "boolean", value: args.enabled });`,
+    );
+    const wf = makeWorkflow({
+      nodes: [
+        {
+          id: "script",
+          type: "swarm-script",
+          config: {
+            scriptName: "echo-bool",
+            args: { enabled: "{{trigger.enabled}}" },
+          },
+        },
+      ],
+    });
+
+    const runId = await startWorkflowExecution(wf, { enabled: false }, registry);
+    const run = getWorkflowRun(runId);
+    const steps = getWorkflowRunStepsByRunId(runId);
+    const scriptStep = steps.find((step) => step.nodeId === "script");
+
+    expect(run?.status).toBe("completed");
+    expect(scriptStep?.status).toBe("completed");
+    expect(scriptStep?.output).toMatchObject({ result: { isBoolean: true, value: false } });
+  });
+
+  test("{{path}} args: mixed string template still produces a string via interpolation", async () => {
+    await saveScript(
+      "echo-mixed",
+      `export default async (args: { label: string }) => ({ isString: typeof args.label === "string", value: args.label });`,
+    );
+    const wf = makeWorkflow({
+      nodes: [
+        {
+          id: "script",
+          type: "swarm-script",
+          config: {
+            scriptName: "echo-mixed",
+            args: { label: "rule-{{trigger.ruleName}}" },
+          },
+        },
+      ],
+    });
+
+    const runId = await startWorkflowExecution(wf, { ruleName: "no-explicit-any" }, registry);
+    const run = getWorkflowRun(runId);
+    const steps = getWorkflowRunStepsByRunId(runId);
+    const scriptStep = steps.find((step) => step.nodeId === "script");
+
+    expect(run?.status).toBe("completed");
+    expect(scriptStep?.status).toBe("completed");
+    expect(scriptStep?.output).toMatchObject({
+      result: { isString: true, value: "rule-no-explicit-any" },
+    });
+  });
+
   test("fsMode workspace-rw is rejected at config validation with a clear error message", async () => {
     await saveScript("noop", `export default async () => ({ ok: true });`);
     const executor = new SwarmScriptExecutor(deps);

package/src/tests/workflow-template.test.ts

@@ -205,6 +205,23 @@ describe("deepInterpolate", () => {
     expect(unresolved).toEqual([]);
   });
 
+  test("exact object token is stringified by default", () => {
+    const { value, unresolved } = deepInterpolate("{{body}}", { body: { message: "hello" } });
+    expect(value).toBe('{"message":"hello"}');
+    expect(unresolved).toEqual([]);
+  });
+
+  test("exact object token preserves raw value when requested", () => {
+    const body = { message: "hello" };
+    const { value, unresolved } = deepInterpolate(
+      "{{body}}",
+      { body },
+      { preserveRawTokens: true },
+    );
+    expect(value).toBe(body);
+    expect(unresolved).toEqual([]);
+  });
+
   test("mixed array (string + number + boolean)", () => {
     const { value, unresolved } = deepInterpolate(["{{name}}", 42, true, null], {
       name: "Test",

package/src/workflows/engine.ts

@@ -494,7 +494,7 @@ async function executeStep(
   }
 
   // 4. Deep-interpolate config using local context (not global ctx)
-  const { value: interpolatedValue, unresolved } = deepInterpolate(node.config, interpolationCtx);
+  const { value: interpolatedValue, unresolved } = interpolateNodeConfig(node, interpolationCtx);
   const interpolatedConfig = interpolatedValue as Record<string, unknown>;
   const executionCtx: Record<string, unknown> = { ...ctx, ...interpolationCtx };
 
@@ -709,6 +709,27 @@ export function findReadyNodes(
   });
 }
 
+export function interpolateNodeConfig(
+  node: Pick<WorkflowNode, "type" | "config">,
+  interpolationCtx: Record<string, unknown>,
+): { value: unknown; unresolved: string[] } {
+  if (node.type !== "swarm-script" || !Object.hasOwn(node.config, "args")) {
+    return deepInterpolate(node.config, interpolationCtx);
+  }
+
+  const { args, ...configWithoutArgs } = node.config;
+  const configResult = deepInterpolate(configWithoutArgs, interpolationCtx);
+  const argsResult = deepInterpolate(args, interpolationCtx, { preserveRawTokens: true });
+
+  return {
+    value: {
+      ...(configResult.value as Record<string, unknown>),
+      args: argsResult.value,
+    },
+    unresolved: [...configResult.unresolved, ...argsResult.unresolved],
+  };
+}
+
 // ─── Helpers ───────────────────────────────────────────────
 
 function timeoutPromise(ms: number): Promise<never> {

package/src/workflows/retry-poller.ts

@@ -8,9 +8,8 @@ import {
 import type { RetryPolicy } from "../types";
 import { checkpointStep, checkpointStepFailure } from "./checkpoint";
 import { getSuccessors } from "./definition";
-import { walkGraph } from "./engine";
+import { interpolateNodeConfig, walkGraph } from "./engine";
 import type { ExecutorRegistry } from "./executors/registry";
-import { deepInterpolate } from "./template";
 import { runStepValidation } from "./validation";
 
 let pollerTimeout: ReturnType<typeof setTimeout> | null = null;
@@ -62,7 +61,7 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
           const ctx = (run.context ?? {}) as Record<string, unknown>;
 
           // Deep-interpolate config
-          const { value: interpolatedValue } = deepInterpolate(node.config, ctx);
+          const { value: interpolatedValue } = interpolateNodeConfig(node, ctx);
           const interpolatedConfig = interpolatedValue as Record<string, unknown>;
 
           // Get executor and re-run

package/src/workflows/template.ts

@@ -10,6 +10,10 @@ export interface InterpolateResult {
   unresolved: string[];
 }
 
+export interface DeepInterpolateOptions {
+  preserveRawTokens?: boolean;
+}
+
 export function interpolate(template: string, ctx: Record<string, unknown>): InterpolateResult {
   const unresolved: string[] = [];
   const result = template.replace(/\{\{([^}]+)\}\}/g, (_match, path: string) => {
@@ -43,18 +47,62 @@ function safeStringify(value: unknown): string {
   }
 }
 
+/** Matches a string that is EXACTLY one {{path}} token with no surrounding text. */
+const EXACT_TOKEN_RE = /^\{\{([^}]+)\}\}$/;
+
+/**
+ * Resolve a dot-separated path against a context object.
+ * Returns `{ found: true, value }` on success, `{ found: false }` when any
+ * segment is missing or the traversal hits a non-object.
+ */
+function resolvePath(
+  path: string,
+  ctx: Record<string, unknown>,
+): { found: true; value: unknown } | { found: false } {
+  const keys = path.trim().split(".");
+  let value: unknown = ctx;
+  for (const key of keys) {
+    if (value == null || typeof value !== "object") return { found: false };
+    value = (value as Record<string, unknown>)[key];
+  }
+  if (value === undefined) return { found: false };
+  return { found: true, value };
+}
+
 /**
  * Deep-interpolate an arbitrary value tree (objects, arrays, strings).
+ *
+ * When `preserveRawTokens` is true and a string value is **exactly** one
+ * `{{path}}` token with no surrounding text, the resolved value is returned
+ * as-is (preserving object / array / number / boolean types). This is the
+ * "raw injection" path used by `swarm-script` node `config.args`.
+ *
+ * When a string contains multiple tokens or surrounding text (e.g.
+ * `"prefix-{{x}}"`) the existing string-interpolation path is used so the
+ * result remains a string.
+ *
  * Non-string leaves are passed through unchanged.
  */
 export function deepInterpolate(
   value: unknown,
   ctx: Record<string, unknown>,
+  options: DeepInterpolateOptions = {},
 ): { value: unknown; unresolved: string[] } {
   const allUnresolved: string[] = [];
 
   function walk(v: unknown): unknown {
     if (typeof v === "string") {
+      const exactMatch = options.preserveRawTokens ? EXACT_TOKEN_RE.exec(v) : null;
+      if (exactMatch?.[1]) {
+        const path = exactMatch[1].trim();
+        const resolved = resolvePath(path, ctx);
+        if (!resolved.found) {
+          allUnresolved.push(path);
+          return "";
+        }
+        return resolved.value;
+      }
+      // Multi-token or mixed string - fall back to string interpolation.
       const { result, unresolved } = interpolate(v, ctx);
       allUnresolved.push(...unresolved);
       return result;