agent-relay 2.0.28 → 2.0.32

package/packages/sdk/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,cAAc;AACd,OAAO,EACL,WAAW,GAIZ,MAAM,aAAa,CAAC;AAErB,4DAA4D;AAC5D,OAAO,EACL,WAAW,EACX,UAAU,GAGX,MAAM,iBAAiB,CAAC;AAEzB,6CAA6C;AAC7C,OAAO,EACL,gBAAgB,GAwCjB,MAAM,qBAAqB,CAAC;AAE7B,oBAAoB;AACpB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAE7B,yDAAyD;AACzD,OAAO,EACL,OAAO,EACP,gBAAgB,GAGjB,MAAM,WAAW,CAAC"}

package/packages/sdk/dist/logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../src/logs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAuBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,OAAO,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,UAAU,CAAC,CAwBrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAW1E"}

package/packages/sdk/dist/logs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.js","sourceRoot":"","sources":["../src/logs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA0BjC;;GAEG;AACH,SAAS,iBAAiB;IACxB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,aAAa,CAAC,CAAC;AAC5D,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,QAAQ,CAAC,QAAgB,EAAE,KAAa;IACrD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAClD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;QACzC,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,KAAa,EACb,UAA0B,EAAE;IAE5B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,iBAAiB,EAAE,CAAC;IACvD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;IAClC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,KAAK,MAAM,CAAC,CAAC;IAE9C,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC/C,MAAM,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAE3D,OAAO;YACL,KAAK;YACL,OAAO;YACP,KAAK,EAAE,IAAI;YACX,SAAS;SACV,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,KAAK;YACL,OAAO,EAAE,EAAE;YACX,KAAK,EAAE,KAAK;YACZ,SAAS,EAAE,CAAC;SACb,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAgB;IACrD,MAAM,GAAG,GAAG,OAAO,IAAI,iBAAiB,EAAE,CAAC;IAE3C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,OAAO,KAAK;aACT,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;aACjC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/packages/sdk/dist/protocol/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,uBAAuB,CAAC"}

package/packages/sdk/dist/protocol/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,uBAAuB,CAAC"}

package/packages/sdk/dist/standalone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone.d.ts","sourceRoot":"","sources":["../src/standalone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAS7D,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,KAAK;IACpB,6CAA6C;IAC7C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3E,gDAAgD;IAChD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,iCAAiC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,WAAW,CAAC,MAAM,GAAE,WAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CA2D1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,WAAgB,GACvB,OAAO,CAAC;KACR,CAAC,IAAI,OAAO,KAAK,GAAG,WAAW;CACjC,GAAG;KACD,CAAC,IAAI,OAAO,KAAK,GAAG,WAAW;CACjC,GAAG;IACF,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B,CAAC,CAWD;AAGD,OAAO,EAAE,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/packages/sdk/dist/standalone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone.js","sourceRoot":"","sources":["../src/standalone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAC;AA2B7D,MAAM,mBAAmB,GAAG,kCAAkC,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,SAAsB,EAAE;IACxD,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,mBAAmB,CAAC;IAC5D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC;IAEnC,iEAAiE;IACjE,IAAI,MAA2D,CAAC;IAChE,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;QACzD,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,yDAAyD;YACzD,uCAAuC;YACvC,sEAAsE,CACvE,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;QACxB,UAAU;QACV,SAAS,EAAE,KAAK,EAAE,gCAAgC;QAClD,SAAS,EAAE,KAAK,EAAE,oBAAoB;KACvC,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IAErB,MAAM,OAAO,GAAkB,EAAE,CAAC;IAElC,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,eAAsC,EAAE;YACjE,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC;gBAC7B,SAAS,EAAE,IAAI;gBACf,UAAU;gBACV,KAAK;gBACL,SAAS,EAAE,IAAI;gBACf,GAAG,YAAY;aAChB,CAAC,CAAC;YACH,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;YACvB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,KAAK,CAAC,IAAI;YACR,+BAA+B;YAC/B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,CAAC;YACD,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;YACnB,kBAAkB;YAClB,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACtB,CAAC;QAED,IAAI,SAAS;YACX,OAAO,MAAM,CAAC,SAAS,CAAC;QAC1B,CAAC;QAED,IAAI,UAAU;YACZ,OAAO,UAAU,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAa,EACb,KAAa,EACb,SAAsB,EAAE;IASxB,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAE1C,OAAO;QACL,CAAC,KAAK,CAAC,EAAE,OAAO;QAChB,CAAC,KAAK,CAAC,EAAE,OAAO;QAChB,KAAK;QACL,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE;KAClB,CAAC;AACX,CAAC;AAED,mCAAmC;AACnC,OAAO,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAC"}

package/packages/sdk/examples/SWARM_CAPABILITIES.md

@@ -0,0 +1,498 @@
+# Agent Relay: Swarm Capabilities
+
+Agent Relay provides the **primitives** that enable any swarm orchestration pattern. This document maps our capabilities to the key features swarm frameworks need.
+
+## Capability Comparison
+
+| Capability | OpenAI Agents | Swarms.ai | Strands | **Agent Relay** |
+|------------|---------------|-----------|---------|-----------------|
+| **Handoffs** | Built-in | Config-based | Tool-based | `sendMessage()` + routing |
+| **Continuity** | Session memory | State sync | Shared context | **Session resume** + inbox |
+| **Consensus** | None | None | None | **Native consensus** |
+| **Memory** | SQLite/Redis | Custom | Shared memory | **Inbox** + state payloads |
+| **Discovery** | Manual | Registry | Auto | `listAgents()` |
+| **Monitoring** | Tracing integrations | Telemetry | Events | `getMetrics()` + shadows |
+| **Spawning** | External | External | External | **Native** `spawn()`/`release()` |
+
+---
+
+## 1. Handoffs (Task Transfer)
+
+Transfer work between agents seamlessly.
+
+### The Primitive
+
+```typescript
+// Direct handoff
+sourceAgent.sendMessage(targetAgent, task, 'action', {
+  handoff: true,
+  context: { /* state to transfer */ },
+  originalRequester: 'User',
+});
+
+// Target receives and continues
+targetAgent.onMessage = (from, { body, data }) => {
+  if (data?.handoff) {
+    // Continue the task with transferred context
+    processTask(body, data.context);
+  }
+};
+```
+
+### Handoff Patterns
+
+```typescript
+// Pattern 1: Explicit routing
+function routeToSpecialist(task: string, context: any) {
+  const specialist = determineSpecialist(task);
+  coordinator.sendMessage(specialist, task, 'action', { context });
+}
+
+// Pattern 2: Chain handoff (A → B → C)
+agentA.sendMessage('AgentB', result, 'action', {
+  chain: ['AgentC', 'AgentD'], // remaining chain
+  accumulated: { stepA: result },
+});
+
+// Pattern 3: Conditional handoff
+if (needsEscalation(result)) {
+  worker.sendMessage('Supervisor', task, 'action', {
+    escalation: true,
+    reason: 'Complexity exceeded threshold',
+  });
+}
+```
+
+---
+
+## 2. Continuity (Session Persistence)
+
+Maintain state across disconnections and handoffs.
+
+### The Primitives
+
+```typescript
+// Session resume - automatic on reconnect
+const client = new RelayClient({
+  agentName: 'Worker',
+  reconnect: true, // Resumes session automatically
+});
+
+// Inbox - messages stored when offline
+const missed = await client.getInbox({ unreadOnly: true });
+
+// State payloads - share state in messages
+client.sendMessage(target, summary, 'state', {
+  currentStep: 3,
+  completedTasks: ['a', 'b'],
+  sharedContext: { key: 'value' },
+});
+```
+
+### Continuity Patterns
+
+```typescript
+// Pattern 1: Checkpoint-based continuity
+async function processWithCheckpoints(task: string) {
+  const checkpoints: any[] = [];
+
+  for (const step of steps) {
+    const result = await executeStep(step);
+    checkpoints.push({ step, result, timestamp: Date.now() });
+
+    // Save checkpoint as state message
+    client.sendMessage('StateStore', JSON.stringify(checkpoints), 'state');
+  }
+}
+
+// Pattern 2: Handoff with full context
+function handoffWithContinuity(target: string, task: string, myState: any) {
+  client.sendMessage(target, task, 'action', {
+    continuity: {
+      previousAgent: client.agentName,
+      sessionId: client.currentSessionId,
+      state: myState,
+      timestamp: Date.now(),
+    },
+  });
+}
+
+// Pattern 3: Recovery from inbox
+async function recoverState() {
+  const stateMessages = await client.getInbox({ from: 'StateStore' });
+  if (stateMessages.length > 0) {
+    const latest = stateMessages[stateMessages.length - 1];
+    return JSON.parse(latest.body);
+  }
+  return null; // Fresh start
+}
+```
+
+---
+
+## 3. Consensus (Group Decisions)
+
+Native distributed decision-making.
+
+### The Primitives
+
+```typescript
+// Create a proposal
+client.createProposal({
+  title: 'Architecture Decision',
+  description: 'Should we use microservices or monolith?',
+  participants: ['Architect', 'DevLead', 'DevOps'],
+  consensusType: 'supermajority', // majority | supermajority | unanimous | weighted | quorum
+  threshold: 0.67,
+  timeoutMs: 300000,
+});
+
+// Vote
+client.vote({
+  proposalId: 'prop_123',
+  value: 'approve', // approve | reject | abstain
+  reason: 'Microservices align with our scaling needs',
+});
+```
+
+### Consensus Patterns
+
+```typescript
+// Pattern 1: Code review approval
+async function requestReview(prId: string, reviewers: string[]) {
+  client.createProposal({
+    title: `Approve PR #${prId}`,
+    description: await getPRDiff(prId),
+    participants: reviewers,
+    consensusType: 'quorum',
+    quorum: 2, // Need at least 2 approvals
+  });
+}
+
+// Pattern 2: Deployment gate
+async function deploymentGate(environment: string) {
+  const stakeholders = getStakeholders(environment);
+
+  client.createProposal({
+    title: `Deploy to ${environment}`,
+    description: 'All tests passed. Ready to deploy?',
+    participants: stakeholders,
+    consensusType: environment === 'production' ? 'unanimous' : 'majority',
+  });
+}
+
+// Pattern 3: Weighted voting by expertise
+client.createProposal({
+  title: 'API Design Choice',
+  participants: ['Junior', 'Senior', 'Architect'],
+  consensusType: 'weighted',
+  // Weights would be configured in the daemon
+});
+```
+
+---
+
+## 4. Memory (Shared State)
+
+Multiple approaches to shared memory.
+
+### The Primitives
+
+```typescript
+// Inbox as message store
+await client.getInbox({ limit: 100 });
+
+// State payloads in messages
+client.sendMessage(target, data, 'state', { key: 'value' });
+
+// Channels for shared context
+client.joinChannel('#project-state');
+client.sendChannelMessage('#project-state', JSON.stringify(state));
+```
+
+### Memory Patterns
+
+```typescript
+// Pattern 1: Dedicated state agent
+class StateAgent {
+  private state: Map<string, any> = new Map();
+
+  constructor() {
+    this.client = new RelayClient({ agentName: 'StateStore' });
+  }
+
+  async start() {
+    await this.client.connect();
+
+    this.client.onMessage = (from, { body, data }) => {
+      if (data?.action === 'get') {
+        const value = this.state.get(data.key);
+        this.client.sendMessage(from, JSON.stringify(value), 'state');
+      } else if (data?.action === 'set') {
+        this.state.set(data.key, JSON.parse(body));
+        this.client.sendMessage(from, 'OK', 'state');
+      }
+    };
+  }
+}
+
+// Pattern 2: Channel-based shared memory
+class SharedMemory {
+  private cache: Map<string, any> = new Map();
+
+  async init(client: RelayClient) {
+    client.joinChannel('#memory');
+
+    client.onChannelMessage = (from, channel, body) => {
+      if (channel === '#memory') {
+        const { key, value } = JSON.parse(body);
+        this.cache.set(key, value);
+      }
+    };
+  }
+
+  set(client: RelayClient, key: string, value: any) {
+    this.cache.set(key, value);
+    client.sendChannelMessage('#memory', JSON.stringify({ key, value }));
+  }
+
+  get(key: string) {
+    return this.cache.get(key);
+  }
+}
+
+// Pattern 3: Accumulator pattern
+async function mapReduceWithMemory(tasks: string[]) {
+  const results: any[] = [];
+
+  for (const task of tasks) {
+    const result = await client.sendAndWait('Worker', task);
+    results.push(result);
+
+    // Share accumulated results
+    client.sendChannelMessage('#results', JSON.stringify({
+      completed: results.length,
+      total: tasks.length,
+      latest: result,
+    }));
+  }
+
+  return results;
+}
+```
+
+---
+
+## 5. Discovery (Agent Registry)
+
+Find and monitor available agents.
+
+### The Primitives
+
+```typescript
+// List all agents
+const agents = await client.listAgents();
+
+// Filter options
+const active = await client.listAgents({ includeIdle: false });
+const projectAgents = await client.listAgents({ project: 'myproject' });
+
+// Agent info returned
+interface AgentInfo {
+  name: string;
+  cli?: string;      // claude, codex, gemini
+  idle?: boolean;
+  parent?: string;   // spawner
+  task?: string;
+  connectedAt?: number;
+}
+```
+
+### Discovery Patterns
+
+```typescript
+// Pattern 1: Find specialist
+async function findSpecialist(specialty: string): Promise<string | null> {
+  const agents = await client.listAgents({ includeIdle: false });
+
+  for (const agent of agents) {
+    if (agent.task?.toLowerCase().includes(specialty)) {
+      return agent.name;
+    }
+  }
+  return null;
+}
+
+// Pattern 2: Load balancing
+async function leastBusyWorker(): Promise<string> {
+  const metrics = await client.getMetrics();
+  const workers = metrics.agents.filter(a => a.name.startsWith('Worker'));
+
+  // Sort by CPU usage
+  workers.sort((a, b) => (a.cpuPercent || 0) - (b.cpuPercent || 0));
+
+  return workers[0]?.name || 'Worker-0';
+}
+
+// Pattern 3: Health-based routing
+async function healthyAgents(): Promise<string[]> {
+  const health = await client.getHealth();
+  const agents = await client.listAgents();
+
+  // Exclude agents with alerts
+  const alertedAgents = new Set(health.alerts.map(a => a.agentName));
+  return agents
+    .filter(a => !alertedAgents.has(a.name))
+    .map(a => a.name);
+}
+```
+
+---
+
+## 6. Monitoring (Observability)
+
+Built-in monitoring without external integrations.
+
+### The Primitives
+
+```typescript
+// System health
+const health = await client.getHealth();
+// { healthScore, issues, recommendations, crashes, alerts }
+
+// Resource metrics
+const metrics = await client.getMetrics();
+// { agents: [...], system: { heapUsed, freeMemory } }
+
+// Shadow monitoring (invisible observation)
+client.bindAsShadow('TargetAgent', {
+  receiveIncoming: true,
+  receiveOutgoing: true,
+});
+
+// Agent logs
+import { getLogs } from '@agent-relay/sdk';
+const logs = await getLogs('Worker1', { lines: 100 });
+```
+
+### Monitoring Patterns
+
+```typescript
+// Pattern 1: Supervisor with real-time monitoring
+class Supervisor {
+  private alerts: any[] = [];
+
+  async monitor(workers: string[]) {
+    // Bind as shadow to all workers
+    for (const worker of workers) {
+      this.client.bindAsShadow(worker, {
+        receiveIncoming: true,
+        receiveOutgoing: true,
+      });
+    }
+
+    // Log all activity
+    this.client.onMessage = (from, { body }, id, meta, originalTo) => {
+      console.log(`[${new Date().toISOString()}] ${from} → ${originalTo}: ${body.slice(0, 50)}...`);
+
+      // Check for issues
+      if (body.includes('ERROR') || body.includes('failed')) {
+        this.alerts.push({ worker: from, message: body, time: Date.now() });
+      }
+    };
+  }
+}
+
+// Pattern 2: Periodic health checks
+async function healthCheckLoop(interval = 30000) {
+  while (true) {
+    const health = await client.getHealth();
+
+    if (health.healthScore < 70) {
+      console.warn('System health degraded:', health.issues);
+      // Take action...
+    }
+
+    await new Promise(r => setTimeout(r, interval));
+  }
+}
+
+// Pattern 3: Auto-scaling based on metrics
+async function autoScale(minWorkers: number, maxWorkers: number) {
+  const metrics = await client.getMetrics();
+  const workers = metrics.agents.filter(a => a.name.startsWith('Worker'));
+  const avgCpu = workers.reduce((sum, w) => sum + (w.cpuPercent || 0), 0) / workers.length;
+
+  if (avgCpu > 80 && workers.length < maxWorkers) {
+    await client.spawn({ name: `Worker-${workers.length}`, cli: 'claude', task: 'General worker' });
+  } else if (avgCpu < 20 && workers.length > minWorkers) {
+    await client.release(workers[workers.length - 1].name);
+  }
+}
+```
+
+---
+
+## Combining Capabilities
+
+Real swarms combine multiple capabilities:
+
+```typescript
+// Full-featured swarm coordinator
+class SwarmCoordinator {
+  constructor(private client: RelayClient) {}
+
+  // Handoff with continuity
+  async delegateTask(target: string, task: string, context: any) {
+    return this.client.sendAndWait(target, task, {
+      data: { handoff: true, context },
+    });
+  }
+
+  // Consensus for critical decisions
+  async groupDecision(question: string, voters: string[]) {
+    this.client.createProposal({
+      title: question,
+      participants: voters,
+      consensusType: 'majority',
+    });
+  }
+
+  // Memory via state channel
+  async shareState(key: string, value: any) {
+    this.client.sendChannelMessage('#swarm-state', JSON.stringify({ key, value }));
+  }
+
+  // Discovery for dynamic routing
+  async findAvailableWorker(): Promise<string | null> {
+    const agents = await this.client.listAgents({ includeIdle: true });
+    const workers = agents.filter(a => a.name.startsWith('Worker') && a.idle);
+    return workers[0]?.name || null;
+  }
+
+  // Monitoring via shadows
+  async monitorWorker(name: string) {
+    this.client.bindAsShadow(name, { receiveIncoming: true, receiveOutgoing: true });
+  }
+}
+```
+
+---
+
+## Summary: Primitives → Capabilities
+
+| SDK Primitive | Swarm Capability |
+|---------------|------------------|
+| `sendMessage()` | Handoffs, task delegation |
+| `sendAndWait()` | Synchronous handoffs, checkpoints |
+| `getInbox()` | Continuity, missed message recovery |
+| Session resume | Continuity across disconnections |
+| `createProposal()` / `vote()` | Consensus decisions |
+| `sendChannelMessage()` | Shared memory, pub/sub |
+| State payloads (`data`) | Context transfer, memory |
+| `listAgents()` | Discovery, registry |
+| `getMetrics()` / `getHealth()` | Monitoring, auto-scaling |
+| `bindAsShadow()` | Invisible monitoring, QA |
+| `spawn()` / `release()` | Dynamic team composition |
+
+**Agent Relay gives you primitives. You build the swarm.**