Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

Swarms: choose a model per worker at spawn (#2377)

Joshua Francec6ed022d3e51
diff --git a/docs/swarms.md b/docs/swarms.md
index dd6d1285d..649c98ca6 100644
--- a/docs/swarms.md
+++ b/docs/swarms.md
@@ -53,6 +53,16 @@ human author. Request bodies cannot set identity, authorization, or provenance.
}
```
+Any spawn — initial or later, by the root or by a worker — may choose the
+model for the workers it creates with optional `model`, `effort` (a thinking
+level) and `fastMode`, e.g.
+`{"action":"spawn","requestId":"r1","count":8,"model":"gpt-6.1-sol","effort":"medium","fastMode":false,"text":"..."}`.
+The choice is stored on each new member (visible in inspect), applies to every
+turn that worker takes, and is inherited by workers it spawns unless they choose
+again. Workers do not copy the root's runtime: fields nobody chose resolve like any
+subagent turn, from the org subagent default and then the owner's default. An
+unavailable model fails closed at dispatch.
+
Optional `settings` overrides the defaults below at initial spawn. The backend
can configure defaults with `SWARM_DEFAULTS`, a JSON object such as
`{"agents":16,"turnMs":900000}`. Values must be positive safe integers within the
diff --git a/src/api/agent-api-catalog.ts b/src/api/agent-api-catalog.ts
index e0a1fc977..fd9fe43a4 100644
--- a/src/api/agent-api-catalog.ts
+++ b/src/api/agent-api-catalog.ts
@@ -63,7 +63,7 @@ const FAMILIES: AgentApiFamily[] = [
match: (method, path) => path === "/v1/swarm" && (method === "GET" || method === "POST"),
when: (view) => view.swarmsEnabled,
guidance:
- "Swarm workers are ordinary sessions with private blank computers. Inspect peers and their context, then send to chosen IDs or all; shared history is visible to every member. Notifications queue unattended turns. Each swarm gets one shared board computer (inspect returns board.sandboxId) that the root and every worker reach with execute's sandbox_id; pass forumSandboxId at creation to use an existing shared computer instead. POST action control with memberId and state active, paused or stopped pauses delivery to, resumes, or stops a descendant worker.",
+ "Swarm workers are ordinary sessions with private blank computers. Inspect peers and their context, then send to chosen IDs or all; shared history is visible to every member. Notifications queue unattended turns. Each swarm gets one shared board computer (inspect returns board.sandboxId) that the root and every worker reach with execute's sandbox_id; pass forumSandboxId at creation to use an existing shared computer instead. Spawn accepts model, effort and fastMode to choose the runtime for the workers it creates; children inherit it unless they choose again. POST action control with memberId and state active, paused or stopped pauses delivery to, resumes, or stops a descendant worker.",
routes: [
{
method: "GET",
diff --git a/src/api/routes/swarms.ts b/src/api/routes/swarms.ts
index b6406c5b6..8c88c2e32 100644
--- a/src/api/routes/swarms.ts
+++ b/src/api/routes/swarms.ts
@@ -3,6 +3,7 @@ import { errMessage } from "../../util/errors.ts";
import type { SwarmCaller } from "../../swarms/swarm-service.ts";
import { isObj } from "./shared.ts";
import type { ApiCtx, Route } from "./route.ts";
+import { SPAWN_RUNTIME_FIELDS } from "../../swarms/swarm-runtime.ts";
const ACTION_FIELDS: Record<string, string[]> = { context: ["context"], control: ["memberId", "state"] };
@@ -38,7 +39,7 @@ async function swarmRequest(ctx: ApiCtx): Promise<void> {
"action",
...(caller.kind === "human" ? ["runId"] : []),
...(ACTION_FIELDS[String(body.action)] ?? ["requestId", "text"]),
- ...(body.action === "spawn" ? ["count", "context", "contexts", "forumSandboxId"] : []),
+ ...(body.action === "spawn" ? ["count", "context", "contexts", "forumSandboxId", ...SPAWN_RUNTIME_FIELDS] : []),
...(body.action === "send" ? ["audience", "replyTo", "notify"] : []),
...(body.action === "spawn" ? ["settings", "backend"] : []),
]);
@@ -71,6 +72,9 @@ async function swarmRequest(ctx: ApiCtx): Promise<void> {
...(typeof body.forumSandboxId === "string" ? { forumSandboxId: body.forumSandboxId } : {}),
...(isObj(body.settings) ? { settings: body.settings } : {}),
...(typeof body.backend === "string" ? { backend: body.backend } : {}),
+ ...Object.fromEntries(
+ SPAWN_RUNTIME_FIELDS.filter((field) => field in body).map((field) => [field, body[field]]),
+ ),
});
return sendJson(res, 202, { members });
}
diff --git a/src/core/orchestrator.ts b/src/core/orchestrator.ts
index 8598a56fa..43c3fce70 100644
--- a/src/core/orchestrator.ts
+++ b/src/core/orchestrator.ts
@@ -532,8 +532,6 @@ export function createOrchestrator(deps: OrchestratorDeps): Orchestrator {
)
throw new NonRetryableTurnError("swarm service unavailable");
const swarmBinding = await deps.swarms?.binding(input);
- if (input.swarm && swarmBinding?.member.parentId && (await deps.config?.getPurposeRuntimeDurable("subagent")))
- input = { ...input, model: undefined, harness: undefined, thinkingLevel: undefined, fastMode: undefined };
const swarmEntryProvenance = input.swarm ? { origin: "automation", swarm: input.swarm } : {};
await deps.refreshModels?.();
input = await scopeTeamsToTurn(input, deps, external);
diff --git a/src/swarms/swarm-runtime.ts b/src/swarms/swarm-runtime.ts
new file mode 100644
index 000000000..5f83066ed
--- /dev/null
+++ b/src/swarms/swarm-runtime.ts
@@ -0,0 +1,52 @@
+import type { OrchestratorInput } from "../core/orchestrator.ts";
+import {
+ modelSupportedByHarness,
+ modelUnavailableReason,
+ thinkingLevelsForHarness,
+ THINKING_LEVELS,
+} from "../model/pi-models.ts";
+
+export type SwarmMemberRuntime = Pick<OrchestratorInput, "model" | "thinkingLevel" | "fastMode">;
+export type SwarmTemplate = Omit<OrchestratorInput, keyof SwarmMemberRuntime | "harness">;
+
+const SERVING_HARNESSES = ["pi", "claude"] as const;
+
+export const SPAWN_RUNTIME_FIELDS = ["model", "effort", "fastMode"] as const;
+export type SpawnRuntimeFields = Partial<Record<(typeof SPAWN_RUNTIME_FIELDS)[number], unknown>>;
+
+export function spawnRuntime(input: SpawnRuntimeFields): SwarmMemberRuntime {
+ const runtime: SwarmMemberRuntime = {};
+ if (input.model !== undefined) {
+ if (typeof input.model !== "string" || !input.model.trim() || input.model.length > 128)
+ throw new Error("invalid model");
+ runtime.model = input.model.trim();
+ }
+ if (input.effort !== undefined) {
+ if (typeof input.effort !== "string" || !THINKING_LEVELS.includes(input.effort as never))
+ throw new Error("invalid effort");
+ runtime.thinkingLevel = input.effort;
+ }
+ if (input.fastMode !== undefined) {
+ if (typeof input.fastMode !== "boolean") throw new Error("invalid fastMode");
+ runtime.fastMode = input.fastMode;
+ }
+ return runtime;
+}
+
+export function inheritRuntime(
+ parent: SwarmMemberRuntime | undefined,
+ chosen: SwarmMemberRuntime,
+): SwarmMemberRuntime | undefined {
+ const runtime = { ...parent, ...chosen };
+ if (runtime.model) {
+ const model = runtime.model;
+ const harnesses = SERVING_HARNESSES.filter((harness) => modelSupportedByHarness(model, harness));
+ if (!harnesses.length) throw new Error(`unknown model ${model}`);
+ const unavailable = modelUnavailableReason(model);
+ if (unavailable) throw new Error(`${model}: ${unavailable}`);
+ const effort = runtime.thinkingLevel;
+ if (effort && !harnesses.some((harness) => thinkingLevelsForHarness(harness, model).includes(effort)))
+ throw new Error(`${effort} reasoning is not supported by ${model}`);
+ }
+ return Object.keys(runtime).length ? runtime : undefined;
+}
diff --git a/src/swarms/swarm-service.ts b/src/swarms/swarm-service.ts
index 5b5017c44..91b108d47 100644
--- a/src/swarms/swarm-service.ts
+++ b/src/swarms/swarm-service.ts
@@ -13,6 +13,7 @@ import { sleep, withTimeout } from "../util/async.ts";
import { createSweeper } from "../util/sweeper.ts";
import { canonicalJson } from "../util/objects.ts";
import { resolveSwarmSettings, type SwarmSettings } from "./swarm-settings.ts";
+import { inheritRuntime, spawnRuntime, type SpawnRuntimeFields, type SwarmTemplate } from "./swarm-runtime.ts";
import { errMessage, swallow } from "../util/errors.ts";
import {
assertSwarmOpen,
@@ -32,7 +33,7 @@ export interface SwarmTurn {
recipientId: string;
}
-interface SpawnInput {
+interface SpawnInput extends SpawnRuntimeFields {
requestId: string;
count?: number;
context?: unknown;
@@ -303,7 +304,7 @@ export function createSwarmService(deps: {
const provider = inventory.providers.find((item) => item.name === requested);
if (!provider || !provider.actions.includes("create") || !provider.actions.includes("retire"))
throw new Error("sandbox backend must support creating and retiring workers");
- const template: OrchestratorInput = {
+ const template: SwarmTemplate = {
actor: source.actor,
conversation: {
...source.conversation,
@@ -318,10 +319,6 @@ export function createSwarmService(deps: {
...(source.unattendedGrants ? { unattendedGrants: source.unattendedGrants } : {}),
...(source.readOnly ? { readOnly: true } : {}),
...(source.skipMemory ? { skipMemory: true } : {}),
- ...(source.harness ? { harness: source.harness } : {}),
- ...(source.model ? { model: source.model } : {}),
- thinkingLevel: source.thinkingLevel,
- fastMode: source.fastMode,
turnWallClockMs: settings.turnMs,
};
const createdAt = Date.now();
@@ -358,6 +355,7 @@ export function createSwarmService(deps: {
function dispatchRequest(swarm: Swarm, message: SwarmMessage, recipient: SwarmMember): OrchestratorInput {
return {
...swarm.template,
+ ...recipient.runtime,
conversation: { ...swarm.template.conversation, threadRef: recipient.threadRef },
origin: { kind: "automation", screenData: message.text },
text: `Swarm ${message.author} message ${message.id} from agent ${message.senderId} (session ${message.senderSessionId})${message.replyTo ? ` (reply to ${message.replyTo})` : ""}. This is not a live human instruction.\n${message.text}`,
@@ -607,6 +605,7 @@ export function createSwarmService(deps: {
throw new Error("settings are only allowed on initial swarm creation");
const settings = existing?.settings ?? resolveSwarmSettings(input.settings, defaults);
boundedText(input.text, settings.textBytes, "text");
+ const requestedRuntime = spawnRuntime(input);
const count = input.count ?? input.contexts?.length ?? 1;
if (!Number.isSafeInteger(count) || count < 1 || count >= settings.agents) throw new Error("invalid pool size");
if (input.contexts && input.contexts.length !== count) throw new Error("contexts must match count");
@@ -642,6 +641,7 @@ export function createSwarmService(deps: {
swarm.notificationCount + count > swarm.settings.notifications
)
throw new Error("swarm work budget exhausted");
+ const runtime = inheritRuntime(parent.runtime, requestedRuntime);
const members: SwarmMember[] = contexts.map((context) => {
const id = randomUUID();
return {
@@ -650,6 +650,7 @@ export function createSwarmService(deps: {
threadRef: `swarm:${encodeURIComponent(swarm.id)}:${id}`,
depth: parent.depth + 1,
context,
+ ...(runtime ? { runtime: { ...runtime } } : {}),
sandboxId: id,
...((input.forumSandboxId ?? swarm.board?.sandboxId)
? { forumSandboxId: input.forumSandboxId ?? swarm.board!.sandboxId }
diff --git a/src/swarms/swarm-store.ts b/src/swarms/swarm-store.ts
index 7ed0b3428..3585e7e97 100644
--- a/src/swarms/swarm-store.ts
+++ b/src/swarms/swarm-store.ts
@@ -4,10 +4,10 @@ import type { RunStore, Run } from "../runs/run-store.ts";
import type { SessionStore } from "../sessions/session-store.ts";
import { assertSwarmRun, type SwarmRunFence } from "./swarm-fence.ts";
import { jsonbStringify, type DurableMap } from "../persistence/durable-map.ts";
-import type { OrchestratorInput } from "../core/orchestrator.ts";
import type { SwarmSettings } from "./swarm-settings.ts";
import type { SandboxBackendName } from "../sandbox/sandbox-routing.ts";
+import type { SwarmMemberRuntime, SwarmTemplate } from "./swarm-runtime.ts";
export const SWARM_LIMITS = {
sweepBatch: 16,
@@ -24,6 +24,7 @@ export interface SwarmMember {
parentId?: string;
depth: number;
context: unknown;
+ runtime?: SwarmMemberRuntime;
sandboxId?: string;
forumSandboxId?: string;
state: "reserved" | "ready" | "failed";
@@ -54,7 +55,7 @@ export interface Swarm {
participants: string[];
createdAt: number;
expiresAt: number;
- template: OrchestratorInput;
+ template: SwarmTemplate;
settings: SwarmSettings;
backend: SandboxBackendName;
board?: { sandboxId: string };
diff --git a/test/context-compaction.test.ts b/test/context-compaction.test.ts
index a33812d7f..d4d45be7d 100644
--- a/test/context-compaction.test.ts
+++ b/test/context-compaction.test.ts
@@ -1301,7 +1301,7 @@ test("human child continuations respect non-fast category defaults", async () =>
assert.deepEqual(seen, [category]);
});
-test("verified swarm workers use category defaults instead of copied parent choices, retaining unset behavior and handoffs", async () => {
+test("verified swarm workers resolve their own defaults instead of copying the root runtime, keeping handoffs", async () => {
const inherited = { harnessId: "pi" as const, modelId: "claude-opus-5", effortLevel: "high", fastMode: true };
const category = { harnessId: "pi" as const, modelId: "gpt-6-astra", effortLevel: "low", fastMode: false };
const handoff = { ...category, modelId: "gpt-6-sol" };
@@ -1350,8 +1350,80 @@ test("verified swarm workers use category defaults instead of copied parent choi
if (configured) await built.config.setPurposeRuntime("subagent", category);
const result = await built.orch.handleTurn({ ...run.request, runId: run.id });
assert.equal(result.status, "ok");
- assert.deepEqual(seen, [configured ? category : inherited, handoff]);
- assert.equal(run.request.model, inherited.modelId, "the verified stored dispatch is not mutated");
+ assert.deepEqual(seen, [
+ configured ? category : { harnessId: inherited.harnessId, modelId: inherited.modelId },
+ handoff,
+ ]);
+ assert.equal(run.request.model, undefined, "workers do not copy the root runtime");
+ }
+});
+
+test("swarm workers keep the runtime chosen at spawn over the category and scope defaults", async () => {
+ const inherited = { harnessId: "pi" as const, modelId: "claude-opus-5", effortLevel: "high", fastMode: true };
+ const category = { harnessId: "pi" as const, modelId: "gpt-6-astra", effortLevel: "low", fastMode: false };
+ for (const configured of [false, true]) {
+ const f = await swarmFixture({
+ runtime: {
+ harness: inherited.harnessId,
+ model: inherited.modelId,
+ thinkingLevel: inherited.effortLevel,
+ fastMode: inherited.fastMode,
+ },
+ });
+ const [full] = await f.service.spawn(f.caller, {
+ requestId: "full",
+ text: "work",
+ model: "gpt-6-sol",
+ effort: "medium",
+ fastMode: false,
+ });
+ const [partial] = await f.service.spawn(f.caller, { requestId: "partial", text: "work", effort: "medium" });
+ await f.service.sweep();
+ const seen = new Map<string, unknown>();
+ for (const peer of [full!, partial!]) {
+ const worker = await f.workerCaller(peer.id);
+ if (worker.kind !== "agent") throw new Error("expected worker");
+ const run = (await f.runs.get(worker.claims.runId!))!;
+ const base = createMockHarness();
+ const adapter: Harness = {
+ ...base,
+ turns: {
+ ...base.turns,
+ runTurn: async (input) => {
+ seen.set(peer.id, input.runtime);
+ return { reply: "done" };
+ },
+ },
+ };
+ const router = createHarnessRouter(new Map([["pi", adapter]]), base, (input) =>
+ resolveRuntimeChoiceDurable(
+ built.config,
+ "org:default-org",
+ input.scopeLabel,
+ inherited,
+ input.runtime,
+ undefined,
+ input.runtimePurpose,
+ ),
+ );
+ const built = buildOrchestrator(router, undefined, undefined, f);
+ built.config.setApprovedHarnesses(["pi"]);
+ await built.config.flushScope("org:default-org");
+ if (configured) await built.config.setPurposeRuntime("subagent", category);
+ assert.equal((await built.orch.handleTurn({ ...run.request, runId: run.id })).status, "ok");
+ }
+ assert.deepEqual(seen.get(full!.id), {
+ harnessId: "pi",
+ modelId: "gpt-6-sol",
+ effortLevel: "medium",
+ fastMode: false,
+ });
+ assert.deepEqual(
+ seen.get(partial!.id),
+ configured
+ ? { ...category, effortLevel: "medium" }
+ : { harnessId: inherited.harnessId, modelId: inherited.modelId, effortLevel: "medium" },
+ );
}
});
diff --git a/test/swarm-runtime.test.ts b/test/swarm-runtime.test.ts
new file mode 100644
index 000000000..d3d179cac
--- /dev/null
+++ b/test/swarm-runtime.test.ts
@@ -0,0 +1,88 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { swarmFixture } from "./support/swarm-fixture.ts";
+
+async function runFor(f: Awaited<ReturnType<typeof swarmFixture>>, memberId: string) {
+ const swarm = (await f.store.get(f.root.id))!;
+ const runId = swarm.messages
+ .flatMap((message) => Object.entries(message.notifications))
+ .filter(([id]) => id === memberId)
+ .at(-1)![1].runId!;
+ return (await f.runs.get(runId))!;
+}
+
+test("spawn chooses the model, effort and fast mode for the workers it creates", async () => {
+ const f = await swarmFixture();
+ const peers = await f.service.spawn(f.caller, {
+ requestId: "initial",
+ count: 2,
+ text: "work",
+ model: "gpt-6.1-sol",
+ effort: "medium",
+ fastMode: false,
+ });
+ assert.deepEqual(peers[0]!.runtime, { model: "gpt-6.1-sol", thinkingLevel: "medium", fastMode: false });
+ await f.service.sweep();
+ for (const peer of peers) {
+ const run = await runFor(f, peer.id);
+ assert.equal(run.request.model, "gpt-6.1-sol");
+ assert.equal(run.request.thinkingLevel, "medium");
+ assert.equal(run.request.fastMode, false);
+ }
+});
+
+test("later spawns in the same swarm can pick different models", async () => {
+ const f = await swarmFixture();
+ const [plain] = await f.service.spawn(f.caller, { requestId: "initial", text: "work" });
+ const [sol] = await f.service.spawn(f.caller, { requestId: "sol", text: "work", model: "gpt-6.1-sol" });
+ const [opus] = await f.service.spawn(f.caller, { requestId: "opus", text: "work", model: "claude-opus-5-5" });
+ await f.service.sweep();
+ assert.equal(plain!.runtime, undefined);
+ assert.equal((await runFor(f, plain!.id)).request.model, undefined);
+ assert.equal((await runFor(f, sol!.id)).request.model, "gpt-6.1-sol");
+ assert.equal((await runFor(f, opus!.id)).request.model, "claude-opus-5-5");
+});
+
+test("workers spawned by a worker inherit its runtime and replace only the fields they name", async () => {
+ const f = await swarmFixture();
+ const [parent] = await f.service.spawn(f.caller, {
+ requestId: "initial",
+ text: "work",
+ model: "gpt-6.1-sol",
+ effort: "medium",
+ settings: { depth: 3 },
+ });
+ await f.service.sweep();
+ const worker = await f.workerCaller(parent!.id);
+ const [inherited] = await f.service.spawn(worker, { requestId: "child", text: "sub" });
+ const [chosen] = await f.service.spawn(worker, { requestId: "child2", text: "sub", effort: "high" });
+ assert.deepEqual(inherited!.runtime, { model: "gpt-6.1-sol", thinkingLevel: "medium" });
+ assert.deepEqual(chosen!.runtime, { model: "gpt-6.1-sol", thinkingLevel: "high" });
+});
+
+test("spawn rejects malformed or unknown runtime choices before reserving workers", async () => {
+ for (const bad of [
+ { model: "" },
+ { model: 3 },
+ { model: "no-such-model-qa" },
+ { model: "gpt-6.1-sol", effort: "adaptive" },
+ { effort: "sideways" },
+ { fastMode: "no" },
+ ]) {
+ const f = await swarmFixture();
+ await assert.rejects(f.service.spawn(f.caller, { requestId: "initial", text: "work", ...(bad as object) }));
+ assert.equal(await f.store.get(f.root.id), null);
+ }
+});
+
+test("a child's effort is checked against the model it inherits", async () => {
+ const f = await swarmFixture();
+ const [parent] = await f.service.spawn(f.caller, { requestId: "initial", text: "work", model: "gpt-6.1-sol" });
+ await f.service.sweep();
+ const worker = await f.workerCaller(parent!.id);
+ await assert.rejects(
+ f.service.spawn(worker, { requestId: "child", text: "sub", effort: "adaptive" }),
+ /adaptive reasoning is not supported by gpt-6.1-sol/,
+ );
+ assert.equal((await f.store.get(f.root.id))!.members.length, 2);
+});