@desplega.ai/agent-swarm 2.7.4 → 2.7.5

package/src/tests/extensions-validate.test.ts

@@ -29,6 +29,11 @@ describe("extension bundle validation", () => {
     expect(await validateBundle(bundle)).toEqual({ ok: true, manifest: bundle.manifest });
   });
 
+  test("accepts the steering event and message rewrite types", async () => {
+    const bundle = await loadBundleFixture("steering-policy");
+    expect(await validateBundle(bundle)).toEqual({ ok: true, manifest: bundle.manifest });
+  });
+
   test("accepts zod and stdlib imports", async () => {
     const bundle = await loadBundleFixture("minimal");
     bundle.files["hooks.ts"] = `import { table } from "stdlib";

package/src/tests/fixtures/extensions/steering-policy/hooks.ts

@@ -0,0 +1,39 @@
+import { block, modify, type SwarmExtension } from "swarm-extension";
+import { z } from "zod";
+
+export const config = z.object({
+  action: z.enum(["continue", "modify", "block", "empty", "retarget", "throw"]),
+  prefix: z.string().default("rewritten: "),
+  slackUserId: z.string().optional(),
+});
+const manifest = {
+  name: "steering-policy",
+  description: "Records, rewrites, or blocks steering messages",
+  version: "1.0.0",
+  runtime: "api",
+  assets: { hooks: "hooks.ts" },
+  config,
+} as const;
+
+const extension: SwarmExtension<typeof manifest> = (api) => {
+  api.on("pre.task.steer", async (event, ctx) => {
+    await ctx.state.set("last", event);
+    if (ctx.config.slackUserId && event.slack?.userId !== ctx.config.slackUserId) return;
+    switch (ctx.config.action) {
+      case "continue":
+        return { action: "continue" };
+      case "modify":
+        return modify({ message: ctx.config.prefix + event.message });
+      case "block":
+        return block("Steering denied by policy");
+      case "empty":
+        return modify({ message: " \n " });
+      case "retarget":
+        return modify({ message: "Unauthorized rewrite", mode: "steer" });
+      case "throw":
+        throw new Error("Steering policy failed");
+    }
+  });
+};
+
+export default extension;

package/src/tests/fixtures/extensions/steering-policy/manifest.json

@@ -0,0 +1,7 @@
+{
+  "name": "steering-policy",
+  "description": "Records, rewrites, or blocks steering messages",
+  "version": "1.0.0",
+  "runtime": "api",
+  "assets": { "hooks": "hooks.ts" }
+}

package/src/tests/fixtures/fake-fx.ts

@@ -0,0 +1,167 @@
+/**
+ * A fake `fx acp` for adapter tests. Plain newline-delimited JSON-RPC, not the
+ * ACP SDK's agent app: fx 0.0.15 takes `systemPrompt` as a bare content-block
+ * array, which the SDK's request validation rejects.
+ *
+ * It answers with the recorded fx 0.0.15 responses and replays the recorded
+ * session updates (`fixtures/fx/`). Everything it receives (argv, the fx
+ * env, `~/.fx/settings.json`, every request) goes to `capture.json` in its cwd.
+ *
+ * FAKE_FX_MODE:
+ * - `ok` (default): one turn; a steer received during it is echoed where the
+ *   recording echoed one, and its request answers `steering: "absorbed"`.
+ * - `steer-ignored`: the steer request answers without `_meta.fx.steering`.
+ * - `wait-for-cancel`: starts a `sleep` child, then holds the turn until
+ *   `session/cancel` and answers `cancelled` with usage.
+ * FAKE_FX_MCP_CALL=1: POSTs `tools/list` to the swarm MCP URL it was given.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const fixtureDir = process.env.FAKE_FX_FIXTURE_DIR ?? "";
+const mode = process.env.FAKE_FX_MODE ?? "ok";
+const responses = JSON.parse(readFileSync(join(fixtureDir, "acp-responses-recorded.json"), "utf8"));
+const updates: Array<Record<string, unknown>> = readFileSync(
+  join(fixtureDir, "acp-updates-recorded.jsonl"),
+  "utf8",
+)
+  .trim()
+  .split("\n")
+  .map((line) => JSON.parse(line));
+
+const settingsPath = join(process.env.HOME ?? "", ".fx", "settings.json");
+const capture: Record<string, unknown> = {
+  argv: process.argv.slice(2),
+  env: Object.fromEntries(
+    Object.entries(process.env).filter(([key]) =>
+      /^(FX_|OPENROUTER_|OPENAI_|AI_GATEWAY_|ANTHROPIC_|XAI_|CLAUDE_)/.test(key),
+    ),
+  ),
+  settings: existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, "utf8")) : null,
+  requests: [] as Array<{ method: string; params: unknown }>,
+};
+const save = () => writeFileSync("capture.json", JSON.stringify(capture));
+save();
+
+const send = (message: unknown) => process.stdout.write(`${JSON.stringify(message)}\n`);
+const notify = (sessionId: string, update: unknown) =>
+  send({ jsonrpc: "2.0", method: "session/update", params: { sessionId, update } });
+
+let steerText: string | null = null;
+let steerWaiter: (() => void) | null = null;
+const steerReplies: Array<() => void> = [];
+let cancelTurn: (() => void) | null = null;
+
+async function runTurn(id: number, sessionId: string): Promise<void> {
+  if (process.env.FAKE_FX_MCP_CALL === "1") {
+    const newSession = (capture.requests as Array<{ method: string; params: any }>).find(
+      (request) => request.method === "session/new" || request.method === "session/resume",
+    );
+    const swarm = newSession?.params.mcpServers.find((server: any) => server.name === "swarm");
+    const headers = Object.fromEntries(
+      swarm.headers.map((header: { name: string; value: string }) => [header.name, header.value]),
+    );
+    const response = await fetch(swarm.url, {
+      method: "POST",
+      headers: { ...headers, "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" }),
+    });
+    capture.mcpCall = { url: swarm.url, status: response.status, body: await response.json() };
+    save();
+  }
+  for (const update of updates) {
+    const meta = update._meta as { fx?: { steering?: unknown } } | undefined;
+    if (update.sessionUpdate === "user_message_chunk" && meta?.fx?.steering) {
+      // The recording echoed a steer here. Wait briefly for one to arrive.
+      if (steerText === null && mode !== "wait-for-cancel") {
+        await new Promise<void>((resolve) => {
+          steerWaiter = resolve;
+          setTimeout(resolve, 3_000);
+        });
+      }
+      if (steerText === null || mode === "steer-ignored") continue;
+      notify(sessionId, { ...update, content: { type: "text", text: steerText } });
+      continue;
+    }
+    notify(sessionId, update);
+  }
+  if (mode === "wait-for-cancel") {
+    const child = Bun.spawn(["sleep", "300"], { stdout: "ignore", stderr: "ignore" });
+    capture.childPid = child.pid;
+    save();
+    await new Promise<void>((resolve) => {
+      cancelTurn = resolve;
+    });
+    send({
+      jsonrpc: "2.0",
+      id,
+      result: { stopReason: "cancelled", usage: { inputTokens: 1200, outputTokens: 30 } },
+    });
+    return;
+  }
+  send({ jsonrpc: "2.0", id, result: responses.prompt });
+  for (const reply of steerReplies.splice(0)) reply();
+}
+
+async function handle(message: any): Promise<void> {
+  if (message.method === undefined) return;
+  (capture.requests as Array<{ method: string; params: unknown }>).push({
+    method: message.method,
+    params: message.params,
+  });
+  save();
+  const { id, method, params } = message;
+  switch (method) {
+    case "initialize":
+      send({ jsonrpc: "2.0", id, result: responses.initialize });
+      return;
+    case "session/new":
+      send({ jsonrpc: "2.0", id, result: responses.newSession });
+      return;
+    case "session/resume": {
+      const { sessionId: _, ...rest } = responses.newSession;
+      send({ jsonrpc: "2.0", id, result: rest });
+      return;
+    }
+    case "session/set_config_option":
+    case "session/set_mode":
+      send({ jsonrpc: "2.0", id, result: { configOptions: responses.newSession.configOptions } });
+      return;
+    case "session/prompt": {
+      if (params._meta?.fx?.steer) {
+        steerText = params.prompt[0].text;
+        steerWaiter?.();
+        steerReplies.push(() =>
+          send({
+            jsonrpc: "2.0",
+            id,
+            result: mode === "steer-ignored" ? { stopReason: "end_turn" } : responses.steer,
+          }),
+        );
+        return;
+      }
+      await runTurn(id, params.sessionId);
+      return;
+    }
+    case "session/cancel":
+      cancelTurn?.();
+      return;
+    default:
+      if (id !== undefined) {
+        send({ jsonrpc: "2.0", id, error: { code: -32601, message: `${method} not supported` } });
+      }
+  }
+}
+
+const decoder = new TextDecoder();
+let buffer = "";
+for await (const chunk of Bun.stdin.stream()) {
+  buffer += decoder.decode(chunk, { stream: true });
+  let newline = buffer.indexOf("\n");
+  while (newline >= 0) {
+    const line = buffer.slice(0, newline).trim();
+    buffer = buffer.slice(newline + 1);
+    if (line) void handle(JSON.parse(line));
+    newline = buffer.indexOf("\n");
+  }
+}

package/src/tests/fixtures/fx/acp-responses-recorded.json

@@ -0,0 +1,157 @@
+{
+  "initialize": {
+    "protocolVersion": 1,
+    "agentCapabilities": {
+      "loadSession": true,
+      "promptCapabilities": {
+        "image": true,
+        "audio": false,
+        "embeddedContext": true
+      },
+      "mcpCapabilities": {
+        "http": true,
+        "sse": false,
+        "acp": false
+      },
+      "sessionCapabilities": {
+        "list": {},
+        "resume": {},
+        "close": {},
+        "systemPrompt": {}
+      },
+      "_meta": {
+        "fx": {
+          "steering": true
+        }
+      }
+    },
+    "agentInfo": {
+      "name": "fx",
+      "title": "fx",
+      "version": "0.0.15"
+    },
+    "authMethods": []
+  },
+  "newSession": {
+    "sessionId": "fxSession001",
+    "configOptions": [
+      {
+        "id": "provider",
+        "name": "Provider",
+        "category": "model",
+        "type": "select",
+        "currentValue": "openrouter",
+        "options": [
+          {
+            "value": "gateway",
+            "name": "Vercel AI Gateway"
+          },
+          {
+            "value": "codex",
+            "name": "Codex subscription"
+          },
+          {
+            "value": "grok",
+            "name": "Grok subscription"
+          },
+          {
+            "value": "openrouter",
+            "name": "openrouter"
+          },
+          {
+            "value": "openai",
+            "name": "openai"
+          }
+        ]
+      },
+      {
+        "id": "model",
+        "name": "Model",
+        "category": "model",
+        "type": "select",
+        "currentValue": "openai/gpt-5-mini",
+        "options": [
+          {
+            "value": "openai/gpt-5-mini",
+            "name": "openai/gpt-5-mini"
+          }
+        ]
+      },
+      {
+        "id": "mode",
+        "name": "Session Mode",
+        "description": "Controls how the agent requests permission",
+        "category": "mode",
+        "type": "select",
+        "currentValue": "full-access",
+        "options": [
+          {
+            "value": "auto",
+            "name": "Auto",
+            "description": "Check actions with an automatic safety review instead of asking",
+            "_meta": {
+              "fx": {
+                "permissionMode": "auto"
+              }
+            }
+          },
+          {
+            "value": "ask",
+            "name": "Ask",
+            "description": "Request permission before making any changes",
+            "_meta": {
+              "fx": {
+                "permissionMode": "ask"
+              }
+            }
+          },
+          {
+            "value": "full-access",
+            "name": "Full access",
+            "description": "Run every action without asking, outside the sandbox",
+            "_meta": {
+              "fx": {
+                "permissionMode": "yolo"
+              }
+            }
+          }
+        ]
+      }
+    ],
+    "modes": {
+      "currentModeId": "full-access",
+      "availableModes": [
+        {
+          "id": "auto",
+          "name": "Auto",
+          "description": "Check actions with an automatic safety review instead of asking"
+        },
+        {
+          "id": "ask",
+          "name": "Ask",
+          "description": "Request permission before making any changes"
+        },
+        {
+          "id": "full-access",
+          "name": "Full access",
+          "description": "Run every action without asking, outside the sandbox"
+        }
+      ]
+    }
+  },
+  "prompt": {
+    "stopReason": "end_turn",
+    "usage": {
+      "inputTokens": 58620,
+      "outputTokens": 1183
+    }
+  },
+  "steer": {
+    "stopReason": "end_turn",
+    "_meta": {
+      "fx": {
+        "steering": "absorbed"
+      }
+    }
+  }
+}

package/src/tests/fixtures/fx/acp-updates-recorded.jsonl

@@ -0,0 +1,15 @@
+{"sessionUpdate":"agent_message_chunk","messageId":"b86bad695b6f80234f85a6ae84770a00","content":{"type":"text","text":"[context] 114 always-loaded MCP tools exceeded the mcp_selected_schema_bytes budget and stay available through capability_search"}}
+{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"**Following developer instructions**\n\nI need to ensure I follow the developer's instructions perfectly. First, I’ll send a brief update to the user about the goal and the next step. Then, I’ll call th…"}}
+{"sessionUpdate":"agent_message_chunk","messageId":"e6788e35f07ecb7d4b22767ec6028538","content":{"type":"text","text":"Goal: fetch the swarm agent list with mcp_swarm_get-swarm as the next step, then run the sleep command. I'll call mcp_swarm_get-swarm now."}}
+{"sessionUpdate":"tool_call","toolCallId":"call_kK1rqCaYaXn16uKH9e6fmb7v","name":"mcp_swarm_get-swarm","title":"Get the agent swarm","kind":"other","status":"pending","rawInput":{},"_meta":{"fx":{"toolCall":{"internal":false,"mcp":{"server":"swarm","tool":"get-swarm"}}}}}
+{"sessionUpdate":"tool_call_update","toolCallId":"call_kK1rqCaYaXn16uKH9e6fmb7v","status":"in_progress"}
+{"sessionUpdate":"tool_call_update","toolCallId":"call_kK1rqCaYaXn16uKH9e6fmb7v","status":"completed","content":[{"type":"content","content":{"type":"text","text":"{\"server\":\"swarm\",\"tool\":\"mcp_swarm_get-swarm\",\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"Found 1 agent(s) in the swarm. Requested by session: 00000000-0000-4000-8000-0000000000b2\\n\\n- fx-probe (idle"}}]}
+{"sessionUpdate":"user_message_chunk","messageId":"41657d84ac6ea6200d169f93414327bb","content":{"type":"text","text":"Steering: also include the word STEERED in your final reply."},"_meta":{"fx":{"steering":{"requestId":4}}}}
+{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"**Preparing shell command update**\n\nI’m thinking about how to provide updates during longer tasks. Specifically, I’ll send a brief message before starting a major phase of the work. So, I'll prepare a…"}}
+{"sessionUpdate":"agent_message_chunk","messageId":"bbef5430c871c3e3e256a2d366116413","content":{"type":"text","text":"Now I'll run the shell command `sleep 6 && echo slept > slept.txt` and report its result. I'll run it now."}}
+{"sessionUpdate":"tool_call","toolCallId":"call_61i3wzVhpMAqWhlx7P3ptjxN","name":"shell","title":"Running","kind":"execute","status":"pending","rawInput":{"action":"run","command":"sleep 6 && echo slept > slept.txt","timeout_ms":120000},"_meta":{"fx":{"toolCall":{"internal":false}}}}
+{"sessionUpdate":"tool_call_update","toolCallId":"call_61i3wzVhpMAqWhlx7P3ptjxN","status":"in_progress"}
+{"sessionUpdate":"tool_call_update","toolCallId":"call_61i3wzVhpMAqWhlx7P3ptjxN","status":"completed","content":[{"type":"content","content":{"type":"text","text":""}}],"command_result":{"kind":"command","command":"sleep 6 && echo slept > slept.txt","cwd":"/workspace/task","exit_code":0,"signal":null,"timed_out":false,"duration_ms":6012,"stdout_bytes":0,"stderr_bytes":0,"truncated":false,"output_file":null,"stdout_file":null,"stderr_file":null}}
+{"sessionUpdate":"agent_message_chunk","messageId":"08b3f1a8b8c18d0153eb85eeecf38aab","content":{"type":"text","text":"Results:\n- mcp_swarm_get-swarm returned 1 agent.\n- Shell command `sleep 6 && echo slept > slept.txt` ran and exited with code 0 after ~6012 ms.\n- The command produced no stdout/stderr output; it created (or overwrote) the file `slept.txt` containing the text `slept`.\n\nSTEERED BANANA"}}
+{"sessionUpdate":"session_info_update","title":"Step 1: call the swarm MCP tool `get-swarm`","updatedAt":"2026-10-29T16:12:50Z"}
+{"sessionUpdate":"usage_update","used":20196,"size":400000}