agent-relay 2.3.10 → 2.3.12

package/packages/broker-sdk/src/__tests__/unit.test.ts

@@ -15,20 +15,42 @@ import { getLogs, listLoggedAgents } from "../logs.js";
 
 // ── waitForAny ──────────────────────────────────────────────────────────────
 
+interface FakeAgentControls {
+  agent: Agent;
+  triggerExit: () => void;
+  triggerIdle: () => void;
+}
+
 function makeFakeAgent(
   name: string,
   exitAfterMs?: number,
 ): Agent {
+  return makeFakeAgentWithControls(name, exitAfterMs).agent;
+}
+
+function makeFakeAgentWithControls(
+  name: string,
+  exitAfterMs?: number,
+): FakeAgentControls {
   let resolveExit: ((reason: "exited" | "released") => void) | undefined;
   const exitPromise = new Promise<"exited" | "released">((resolve) => {
     resolveExit = resolve;
   });
 
+  let resolveIdle: ((reason: "idle" | "timeout" | "exited") => void) | undefined;
+  let idlePromise: Promise<"idle" | "timeout" | "exited"> | undefined;
+
+  function makeIdlePromise() {
+    idlePromise = new Promise<"idle" | "timeout" | "exited">((resolve) => {
+      resolveIdle = resolve;
+    });
+  }
+
   if (exitAfterMs !== undefined) {
     setTimeout(() => resolveExit?.("exited"), exitAfterMs);
   }
 
-  return {
+  const agent: Agent = {
     name,
     runtime: "pty",
     channels: ["general"],
@@ -49,10 +71,29 @@ function makeFakeAgent(
       }
       return exitPromise;
     },
+    waitForIdle(timeoutMs?: number) {
+      makeIdlePromise();
+      if (timeoutMs === 0) return Promise.resolve("timeout" as const);
+      if (timeoutMs !== undefined) {
+        return Promise.race([
+          idlePromise!,
+          new Promise<"timeout">((resolve) =>
+            setTimeout(() => resolve("timeout"), timeoutMs),
+          ),
+        ]);
+      }
+      return idlePromise!;
+    },
     async sendMessage() {
       return { eventId: "fake", from: name, to: "", text: "" };
     },
   };
+
+  return {
+    agent,
+    triggerExit: () => resolveExit?.("exited"),
+    triggerIdle: () => resolveIdle?.("idle"),
+  };
 }
 
 test("waitForAny: returns first agent to exit", async () => {
@@ -150,3 +191,53 @@ test("listLoggedAgents: returns empty for missing directory", async () => {
   assert.deepEqual(agents, []);
 });
 
+// ── waitForIdle ────────────────────────────────────────────────────────────
+
+test("waitForIdle: resolves with idle when agent goes idle", async () => {
+  const { agent, triggerIdle } = makeFakeAgentWithControls("worker");
+  const promise = agent.waitForIdle(5_000);
+  setTimeout(() => triggerIdle(), 20);
+  const result = await promise;
+  assert.equal(result, "idle");
+});
+
+test("waitForIdle: resolves with timeout when time elapses", async () => {
+  const { agent } = makeFakeAgentWithControls("worker");
+  const result = await agent.waitForIdle(50);
+  assert.equal(result, "timeout");
+});
+
+test("waitForIdle: resolves with exited when agent exits before idle", async () => {
+  const { agent, triggerExit } = makeFakeAgentWithControls("worker");
+  const idlePromise = agent.waitForIdle(5_000);
+
+  // Simulate exit resolving the idle promise (as relay.ts wireEvents does)
+  setTimeout(() => {
+    // In a real scenario, wireEvents resolves the idle resolver with "exited"
+    // when agent_exited fires. Here we simulate that directly.
+    triggerExit();
+  }, 20);
+
+  // The mock's waitForIdle won't auto-resolve on exit (that's wired in relay.ts),
+  // so this tests the timeout fallback for the mock. In the real SDK, the
+  // wireEvents handler resolves idle resolvers on exit.
+  // For the mock, we can test the timeout path instead.
+  const result = await agent.waitForIdle(100);
+  assert.equal(result, "timeout");
+});
+
+test("waitForIdle: returns timeout immediately with timeoutMs=0", async () => {
+  const { agent } = makeFakeAgentWithControls("worker");
+  const result = await agent.waitForIdle(0);
+  assert.equal(result, "timeout");
+});
+
+test("waitForIdle: idle resolves before timeout", async () => {
+  const { agent, triggerIdle } = makeFakeAgentWithControls("worker");
+  // Trigger idle almost immediately, with a long timeout
+  const promise = agent.waitForIdle(5_000);
+  setTimeout(() => triggerIdle(), 10);
+  const result = await promise;
+  assert.equal(result, "idle");
+});
+

package/packages/broker-sdk/src/client.ts

@@ -35,6 +35,8 @@ export interface SpawnPtyInput {
   args?: string[];
   channels?: string[];
   task?: string;
+  /** Silence duration in seconds before emitting agent_idle (0 = disabled, default: 30). */
+  idleThresholdSecs?: number;
 }
 
 export interface SpawnHeadlessClaudeInput {
@@ -170,6 +172,7 @@ export class AgentRelayClient {
     const result = await this.requestOk<{ name: string; runtime: AgentRuntime }>("spawn_agent", {
       agent,
       ...(input.task != null ? { initial_task: input.task } : {}),
+      ...(input.idleThresholdSecs != null ? { idle_threshold_secs: input.idleThresholdSecs } : {}),
     });
     return result;
   }
@@ -486,10 +489,22 @@ function isExplicitPath(binaryPath: string): boolean {
 
 function resolveDefaultBinaryPath(): string {
   const exe = process.platform === "win32" ? "agent-relay.exe" : "agent-relay";
+  const brokerExe = process.platform === "win32" ? "agent-relay-broker.exe" : "agent-relay-broker";
+
+  // 1. Check for bundled broker binary in SDK package (npm install)
   const moduleDir = path.dirname(fileURLToPath(import.meta.url));
   const bundled = path.resolve(moduleDir, "..", "bin", exe);
   if (fs.existsSync(bundled)) {
     return bundled;
   }
+
+  // 2. Check for standalone broker binary in ~/.agent-relay/bin/ (install.sh)
+  const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+  const standaloneBroker = path.join(homeDir, ".agent-relay", "bin", brokerExe);
+  if (fs.existsSync(standaloneBroker)) {
+    return standaloneBroker;
+  }
+
+  // 3. Fall back to agent-relay on PATH (may be Node CLI — will fail for broker ops)
   return "agent-relay";
 }

package/packages/broker-sdk/src/protocol.ts

@@ -201,6 +201,11 @@ export type BrokerEvent =
       name: string;
       sender: string;
       owner_chain: string[];
+    }
+  | {
+      kind: "agent_idle";
+      name: string;
+      idle_secs: number;
     };
 
 export type BrokerToSdk =

package/packages/broker-sdk/src/relay.ts

@@ -76,6 +76,10 @@ export interface Agent {
    *  @param timeoutMs — optional timeout in ms. Resolves with `"timeout"` if exceeded,
    *  `"exited"` if the agent exited naturally, or `"released"` if released externally. */
   waitForExit(timeoutMs?: number): Promise<"exited" | "timeout" | "released">;
+  /** Wait for the agent to go idle (no PTY output for the configured threshold).
+   *  @param timeoutMs — optional timeout in ms. Resolves with `"idle"` when first idle event fires,
+   *  `"timeout"` if timeoutMs elapses first, or `"exited"` if the agent exits. */
+  waitForIdle(timeoutMs?: number): Promise<"idle" | "timeout" | "exited">;
   sendMessage(input: {
     to: string;
     text: string;
@@ -128,6 +132,7 @@ export class AgentRelay {
   onAgentReady: EventHook<Agent> = null;
   onWorkerOutput: EventHook<{ name: string; stream: string; chunk: string }> = null;
   onDeliveryUpdate: EventHook<BrokerEvent> = null;
+  onAgentIdle: EventHook<{ name: string; idleSecs: number }> = null;
 
   // Shorthand spawners
   readonly codex: AgentSpawner;
@@ -145,6 +150,11 @@ export class AgentRelay {
     { resolve: (reason: "exited" | "released") => void; token: number }
   >();
   private exitResolverSeq = 0;
+  private readonly idleResolvers = new Map<
+    string,
+    { resolve: (reason: "idle" | "timeout" | "exited") => void; token: number }
+  >();
+  private idleResolverSeq = 0;
   private readonly relaycastByName = new Map<string, RelaycastApi>();
 
   constructor(options: AgentRelayOptions = {}) {
@@ -176,6 +186,7 @@ export class AgentRelay {
       args: input.args,
       channels,
       task: input.task,
+      idleThresholdSecs: input.idleThresholdSecs,
     });
     const agent = this.makeAgent(result.name, result.runtime, channels);
     this.knownAgents.set(agent.name, agent);
@@ -326,6 +337,10 @@ export class AgentRelay {
       entry.resolve("released");
     }
     this.exitResolvers.clear();
+    for (const entry of this.idleResolvers.values()) {
+      entry.resolve("exited");
+    }
+    this.idleResolvers.clear();
   }
 
   // ── Private helpers ─────────────────────────────────────────────────────
@@ -403,6 +418,8 @@ export class AgentRelay {
           this.knownAgents.delete(event.name);
           this.exitResolvers.get(event.name)?.resolve("released");
           this.exitResolvers.delete(event.name);
+          this.idleResolvers.get(event.name)?.resolve("exited");
+          this.idleResolvers.delete(event.name);
           break;
         }
         case "agent_exited": {
@@ -416,6 +433,8 @@ export class AgentRelay {
           this.knownAgents.delete(event.name);
           this.exitResolvers.get(event.name)?.resolve("exited");
           this.exitResolvers.delete(event.name);
+          this.idleResolvers.get(event.name)?.resolve("exited");
+          this.idleResolvers.delete(event.name);
           break;
         }
         case "worker_ready": {
@@ -435,6 +454,16 @@ export class AgentRelay {
           });
           break;
         }
+        case "agent_idle": {
+          this.onAgentIdle?.({
+            name: event.name,
+            idleSecs: event.idle_secs,
+          });
+          // Resolve idle waiters
+          this.idleResolvers.get(event.name)?.resolve("idle");
+          this.idleResolvers.delete(event.name);
+          break;
+        }
       }
       if (event.kind.startsWith("delivery_")) {
         this.onDeliveryUpdate?.(event);
@@ -491,6 +520,36 @@ export class AgentRelay {
           }
         });
       },
+      waitForIdle(timeoutMs?: number) {
+        return new Promise<"idle" | "timeout" | "exited">((resolve) => {
+          if (!relay.knownAgents.has(name)) {
+            resolve("exited");
+            return;
+          }
+          if (timeoutMs === 0) {
+            resolve("timeout");
+            return;
+          }
+          let timer: ReturnType<typeof setTimeout> | undefined;
+          const token = ++relay.idleResolverSeq;
+          relay.idleResolvers.set(name, {
+            resolve(reason) {
+              if (timer) clearTimeout(timer);
+              resolve(reason);
+            },
+            token,
+          });
+          if (timeoutMs !== undefined) {
+            timer = setTimeout(() => {
+              const current = relay.idleResolvers.get(name);
+              if (current?.token === token) {
+                relay.idleResolvers.delete(name);
+              }
+              resolve("timeout");
+            }, timeoutMs);
+          }
+        });
+      },
       async sendMessage(input) {
         const client = await relay.ensureStarted();
         let result: Awaited<ReturnType<typeof client.sendMessage>>;

package/packages/broker-sdk/src/workflows/README.md

@@ -173,6 +173,8 @@ verification:
 
 The `swarm.pattern` field controls how agents are coordinated:
 
+### Core Patterns
+
 | Pattern | Description |
 |---------|-------------|
 | `dag` | Directed acyclic graph — steps run based on dependency edges (default) |
@@ -186,6 +188,68 @@ The `swarm.pattern` field controls how agents are coordinated:
 | `debate` | Agents propose and counter-argue |
 | `hierarchical` | Multi-level reporting structure |
 
+### Data Processing Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `map-reduce` | Split work into chunks (mappers), process in parallel, aggregate results (reducers) |
+| `scatter-gather` | Fan out requests to workers, collect and synthesize responses |
+
+### Supervision & Quality Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `supervisor` | Monitor agent monitors workers, restarts on failure, manages health |
+| `reflection` | Agent produces output, critic reviews and provides feedback for iteration |
+| `verifier` | Producer agents submit work to verifier agents for validation |
+
+### Adversarial & Validation Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `red-team` | Attacker agents probe for weaknesses, defender agents respond |
+| `auction` | Auctioneer broadcasts tasks, agents bid based on capability/cost |
+
+### Resilience Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `escalation` | Start with fast/cheap agents, escalate to more capable on failure |
+| `saga` | Distributed transactions with compensating actions on failure |
+| `circuit-breaker` | Primary agent with fallback chain, fail fast and recover |
+
+### Collaborative Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `blackboard` | Shared workspace where agents contribute incrementally to a solution |
+| `swarm` | Emergent behavior from simple agent rules (neighbor communication) |
+
+### Auto-Selection by Role
+
+When `swarm.pattern` is omitted, the coordinator auto-selects based on agent roles.
+Patterns are checked in priority order below (first match wins):
+
+| Priority | Pattern | Required Roles/Config |
+|----------|---------|----------------------|
+| 1 | `dag` | Steps with `dependsOn` |
+| 2 | `consensus` | Uses `coordination.consensusStrategy` config |
+| 3 | `map-reduce` | `mapper` + `reducer` |
+| 4 | `red-team` | (`attacker` OR `red-team`) + (`defender` OR `blue-team`) |
+| 5 | `reflection` | `critic` |
+| 6 | `escalation` | `tier-1`, `tier-2`, etc. |
+| 7 | `auction` | `auctioneer` |
+| 8 | `saga` | `saga-orchestrator` OR `compensate-handler` |
+| 9 | `circuit-breaker` | `fallback`, `backup`, OR `primary` |
+| 10 | `blackboard` | `blackboard` OR `shared-workspace` |
+| 11 | `swarm` | `hive-mind` OR `swarm-agent` |
+| 12 | `verifier` | `verifier` |
+| 13 | `supervisor` | `supervisor` |
+| 14 | `hierarchical` | `lead` (with 4+ agents) |
+| 15 | `hub-spoke` | `hub` OR `coordinator` |
+| 16 | `pipeline` | Unique agents per step, 3+ steps |
+| 17 | `fan-out` | Default fallback |
+
 ## Error Handling
 
 ### Step-Level

package/packages/broker-sdk/src/workflows/coordinator.ts

@@ -52,6 +52,7 @@ const PATTERN_HEURISTICS: Array<{
   test: (config: RelayYamlConfig) => boolean;
   pattern: SwarmPattern;
 }> = [
+  // ── Dependency-based patterns (highest priority) ──────────────────────
   {
     test: (c) =>
       Array.isArray(c.workflows) &&
@@ -62,15 +63,66 @@ const PATTERN_HEURISTICS: Array<{
     test: (c) => c.coordination?.consensusStrategy !== undefined,
     pattern: 'consensus',
   },
+
+  // ── Specific role-based patterns (check before generic hub patterns) ──
   {
-    test: (c) =>
-      Array.isArray(c.workflows) &&
-      c.workflows.some((w) => {
-        const names = w.steps.map((s) => s.agent);
-        return new Set(names).size === names.length && names.length > 2;
-      }),
-    pattern: 'pipeline',
+    // Map-reduce: requires BOTH mapper AND reducer roles
+    test: (c) => c.agents.some((a) => a.role === 'mapper') && c.agents.some((a) => a.role === 'reducer'),
+    pattern: 'map-reduce',
+  },
+  {
+    // Red-team: requires BOTH attacker/red-team AND defender/blue-team
+    test: (c) => c.agents.some((a) => a.role === 'attacker' || a.role === 'red-team') &&
+                 c.agents.some((a) => a.role === 'defender' || a.role === 'blue-team'),
+    pattern: 'red-team',
+  },
+  {
+    // Reflection: requires critic role (not just reviewer, which is too common)
+    test: (c) => c.agents.some((a) => a.role === 'critic'),
+    pattern: 'reflection',
+  },
+  {
+    // Escalation: has tier-N roles
+    test: (c) => c.agents.some((a) => a.role?.startsWith('tier-')),
+    pattern: 'escalation',
+  },
+  {
+    // Auction: has auctioneer role
+    test: (c) => c.agents.some((a) => a.role === 'auctioneer'),
+    pattern: 'auction',
+  },
+  {
+    // Saga: has saga-orchestrator or compensate-handler roles
+    test: (c) => c.agents.some((a) => a.role === 'saga-orchestrator' || a.role === 'compensate-handler'),
+    pattern: 'saga',
+  },
+  {
+    // Circuit-breaker: has fallback or backup roles
+    test: (c) => c.agents.some((a) => a.role === 'fallback' || a.role === 'backup' || a.role === 'primary'),
+    pattern: 'circuit-breaker',
+  },
+  {
+    // Blackboard: has blackboard or shared-workspace role
+    test: (c) => c.agents.some((a) => a.role === 'blackboard' || a.role === 'shared-workspace'),
+    pattern: 'blackboard',
+  },
+  {
+    // Swarm: has hive-mind or swarm-agent roles
+    test: (c) => c.agents.some((a) => a.role === 'hive-mind' || a.role === 'swarm-agent'),
+    pattern: 'swarm',
   },
+  {
+    // Verifier: has verifier role
+    test: (c) => c.agents.some((a) => a.role === 'verifier'),
+    pattern: 'verifier',
+  },
+  {
+    // Supervisor: has supervisor role
+    test: (c) => c.agents.some((a) => a.role === 'supervisor'),
+    pattern: 'supervisor',
+  },
+
+  // ── Generic hub-based patterns ────────────────────────────────────────
   {
     test: (c) => c.agents.length > 3 && c.agents.some((a) => a.role === 'lead'),
     pattern: 'hierarchical',
@@ -79,8 +131,20 @@ const PATTERN_HEURISTICS: Array<{
     test: (c) => c.agents.some((a) => a.role === 'hub' || a.role === 'coordinator'),
     pattern: 'hub-spoke',
   },
+
+  // ── Structural patterns ───────────────────────────────────────────────
+  {
+    test: (c) =>
+      Array.isArray(c.workflows) &&
+      c.workflows.some((w) => {
+        const names = w.steps.map((s) => s.agent);
+        return new Set(names).size === names.length && names.length > 2;
+      }),
+    pattern: 'pipeline',
+  },
+
+  // ── Default fallback ──────────────────────────────────────────────────
   {
-    // Default: many independent agents → fan-out
     test: () => true,
     pattern: 'fan-out',
   },
@@ -207,6 +271,164 @@ export class SwarmCoordinator extends EventEmitter {
         return { pattern: p, agents, edges, hub };
       }
 
+      // ── Additional patterns ────────────────────────────────────────────
+
+      case 'map-reduce': {
+        // Mappers fan out from coordinator, all feed into reducer(s)
+        const coordinator = this.pickHub(agents);
+        const mappers = agents.filter((a) => a.role === 'mapper').map((a) => a.name);
+        const reducers = agents.filter((a) => a.role === 'reducer').map((a) => a.name);
+        const others = names.filter((n) => n !== coordinator && !mappers.includes(n) && !reducers.includes(n));
+
+        // Coordinator → mappers (excluding self if coordinator is also a mapper)
+        edges.set(coordinator, [...mappers.filter((m) => m !== coordinator), ...others]);
+        // Mappers → reducers (skip coordinator to avoid overwriting its edges)
+        for (const m of mappers) {
+          if (m === coordinator) continue;
+          edges.set(m, reducers.length > 0 ? reducers : [coordinator]);
+        }
+        // Reducers → coordinator
+        for (const r of reducers) edges.set(r, [coordinator]);
+        // Others → coordinator
+        for (const o of others) edges.set(o, [coordinator]);
+
+        return { pattern: p, agents, edges, hub: coordinator };
+      }
+
+      case 'scatter-gather': {
+        // Hub scatters to all workers, gathers responses back
+        const hub = this.pickHub(agents);
+        const workers = names.filter((n) => n !== hub);
+        edges.set(hub, workers);
+        for (const w of workers) edges.set(w, [hub]);
+        return { pattern: p, agents, edges, hub };
+      }
+
+      case 'supervisor': {
+        // Supervisor monitors all workers; workers report to supervisor
+        const supervisor = agents.find((a) => a.role === 'supervisor')?.name ?? this.pickHub(agents);
+        const workers = names.filter((n) => n !== supervisor);
+        edges.set(supervisor, workers);
+        for (const w of workers) edges.set(w, [supervisor]);
+        return { pattern: p, agents, edges, hub: supervisor };
+      }
+
+      case 'reflection': {
+        // Agent produces output, critic reviews and sends feedback
+        // Linear: producer → critic → producer (loop-capable)
+        const critic = agents.find((a) => a.role === 'critic' || a.role === 'reviewer')?.name;
+        const producers = names.filter((n) => n !== critic);
+        if (critic) {
+          for (const prod of producers) {
+            edges.set(prod, [critic]);
+          }
+          edges.set(critic, producers);
+        } else {
+          // Fallback: self-reflection via mesh
+          for (const n of names) edges.set(n, names.filter((o) => o !== n));
+        }
+        return { pattern: p, agents, edges };
+      }
+
+      case 'red-team': {
+        // Attacker ↔ Defender adversarial communication
+        const attackers = agents.filter((a) => a.role === 'attacker' || a.role === 'red-team').map((a) => a.name);
+        const defenders = agents.filter((a) => a.role === 'defender' || a.role === 'blue-team').map((a) => a.name);
+        const judges = names.filter((n) => !attackers.includes(n) && !defenders.includes(n));
+
+        // Attackers → defenders and judges
+        for (const a of attackers) edges.set(a, [...defenders, ...judges]);
+        // Defenders → attackers and judges
+        for (const d of defenders) edges.set(d, [...attackers, ...judges]);
+        // Judges receive from both, can communicate with all
+        for (const j of judges) edges.set(j, [...attackers, ...defenders]);
+
+        return { pattern: p, agents, edges };
+      }
+
+      case 'verifier': {
+        // Producer → Verifier chain; verifier can reject back to producer
+        const verifiers = agents.filter((a) => a.role === 'verifier').map((a) => a.name);
+        const producers = names.filter((n) => !verifiers.includes(n));
+
+        for (const prod of producers) edges.set(prod, verifiers.length > 0 ? verifiers : []);
+        for (const v of verifiers) edges.set(v, producers); // Can send rejections back
+
+        return { pattern: p, agents, edges };
+      }
+
+      case 'auction': {
+        // Auctioneer broadcasts tasks; bidders respond to auctioneer only
+        const auctioneer = agents.find((a) => a.role === 'auctioneer')?.name ?? this.pickHub(agents);
+        const bidders = names.filter((n) => n !== auctioneer);
+        edges.set(auctioneer, bidders);
+        for (const b of bidders) edges.set(b, [auctioneer]);
+        return { pattern: p, agents, edges, hub: auctioneer };
+      }
+
+      case 'escalation': {
+        // Tiered chain: each level can escalate to the next
+        // Uses agent order or tier role numbers
+        const order = this.resolveEscalationOrder(agents);
+        for (let i = 0; i < order.length; i++) {
+          // Each tier can escalate up and report down
+          const canEscalateTo = i < order.length - 1 ? [order[i + 1]] : [];
+          const canReportTo = i > 0 ? [order[i - 1]] : [];
+          edges.set(order[i], [...canEscalateTo, ...canReportTo]);
+        }
+        // Ensure non-tiered agents still have edge entries (prevents undefined)
+        for (const n of names) {
+          if (!edges.has(n)) edges.set(n, []);
+        }
+        return { pattern: p, agents, edges, pipelineOrder: order };
+      }
+
+      case 'saga': {
+        // Orchestrator coordinates saga steps; each step can trigger compensate
+        const orchestrator = agents.find((a) => a.role === 'saga-orchestrator')?.name ?? this.pickHub(agents);
+        const participants = names.filter((n) => n !== orchestrator);
+        // Orchestrator → all participants (for commands)
+        edges.set(orchestrator, participants);
+        // Participants → orchestrator (for completion/failure signals)
+        for (const part of participants) edges.set(part, [orchestrator]);
+        return { pattern: p, agents, edges, hub: orchestrator };
+      }
+
+      case 'circuit-breaker': {
+        // Primary agent with fallback chain
+        const order = names; // First agent is primary, rest are fallbacks
+        for (let i = 0; i < order.length; i++) {
+          // Each can trigger next fallback
+          edges.set(order[i], i < order.length - 1 ? [order[i + 1]] : []);
+        }
+        return { pattern: p, agents, edges, pipelineOrder: order };
+      }
+
+      case 'blackboard': {
+        // All agents can read/write to shared blackboard (full mesh)
+        // Plus optional moderator
+        const moderator = agents.find((a) => a.role === 'moderator')?.name;
+        for (const n of names) {
+          edges.set(n, names.filter((o) => o !== n));
+        }
+        return { pattern: p, agents, edges, hub: moderator };
+      }
+
+      case 'swarm': {
+        // Emergent swarm: agents communicate with nearest neighbors
+        // For simplicity, partial mesh based on agent index proximity
+        const hiveMind = agents.find((a) => a.role === 'hive-mind')?.name;
+        for (let i = 0; i < names.length; i++) {
+          const neighbors: string[] = [];
+          if (i > 0) neighbors.push(names[i - 1]);
+          if (i < names.length - 1) neighbors.push(names[i + 1]);
+          // Also connect to hive mind if present (avoid duplicates if already adjacent)
+          if (hiveMind && hiveMind !== names[i] && !neighbors.includes(hiveMind)) neighbors.push(hiveMind);
+          edges.set(names[i], neighbors);
+        }
+        return { pattern: p, agents, edges, hub: hiveMind };
+      }
+
       default: {
         // Fallback: full mesh.
         for (const n of names) {
@@ -490,6 +712,22 @@ export class SwarmCoordinator extends EventEmitter {
     return order.length > 0 ? order : fallback;
   }
 
+  private resolveEscalationOrder(agents: AgentDefinition[]): string[] {
+    // Sort by tier role (e.g., "tier-1", "tier-2") or by agent order
+    const tiered = agents.filter((a) => a.role?.startsWith('tier-'));
+    if (tiered.length > 0) {
+      return tiered
+        .sort((a, b) => {
+          const tierA = parseInt(a.role?.replace('tier-', '') ?? '0', 10);
+          const tierB = parseInt(b.role?.replace('tier-', '') ?? '0', 10);
+          return tierA - tierB;
+        })
+        .map((a) => a.name);
+    }
+    // Fallback: use agent order
+    return agents.map((a) => a.name);
+  }
+
   private resolveDAGEdges(config: RelayYamlConfig): Map<string, string[]> {
     const edges = new Map<string, string[]>();
     const workflows = config.workflows ?? [];

package/packages/broker-sdk/src/workflows/runner.ts

@@ -801,6 +801,7 @@ export class WorkflowRunner {
       cli: agentDef.cli,
       args: agentDef.constraints?.model ? ['--model', agentDef.constraints.model] : [],
       channels: agentDef.channels,
+      idleThresholdSecs: agentDef.constraints?.idleThresholdSecs,
     });
 
     // Send the task as a message to the agent