TypeScript SDK Reference

npm install @agent-relay/sdk

const codex = await relay.spawnAgent({
  cli: 'codex',
  model: Models.Codex.GPT_5_3_CODEX,
  channels: ['dev'],
  task: 'Implement the approved plan.',
});

const reviewer = await relay.spawnAgent({
  name: 'Reviewer',
  cli: 'opencode',
  runtime: 'headless',
  model: Models.Opencode.OPENAI_GPT_5_2,
  channels: ['reviews'],
  task: 'Review the branch and summarize risks.',
});

interface Agent {
  readonly name: string;
  readonly runtime: AgentRuntime;
  readonly channels: string[];
  readonly status: AgentStatus; // 'spawning' | 'ready' | 'idle' | 'exited'
  exitCode?: number;
  exitSignal?: string;
  exitReason?: string;

  sendMessage(input: {
    to: string;
    text: string;
    threadId?: string;
    priority?: number;
    data?: Record<string, unknown>;
  }): Promise<Message>;

  release(reasonOrOptions?: string | ReleaseOptions): Promise<void>;
  waitForReady(timeoutMs?: number): Promise<void>;
  waitForExit(timeoutMs?: number): Promise<'exited' | 'timeout' | 'released'>;
  waitForIdle(timeoutMs?: number): Promise<'idle' | 'timeout' | 'exited'>;
  waitForResult(timeoutMs?: number): Promise<AgentResult>;
  onOutput(callback: (chunk: string) => void): () => void; // returns unsubscribe
}

import { AgentRelayClient } from '@agent-relay/sdk';

// Spawn a broker and connect to it.
const client = await AgentRelayClient.spawn({ cwd: '/my/project' });

// Or connect to an already-running broker by reading .agent-relay/connection.json.
// const client = AgentRelayClient.connect({ cwd: '/my/project' });

// Or connect directly when you already know the broker URL and API key.
// const client = new AgentRelayClient({
//   baseUrl: 'http://127.0.0.1:3888',
//   apiKey: process.env.RELAY_BROKER_API_KEY,
// });

import { AgentRelayClient, type InboundDeliveryMode } from '@agent-relay/sdk';

const client = AgentRelayClient.connect({ cwd: '/my/project' });
const name = 'Reviewer';

const previousMode: InboundDeliveryMode = await client.getInboundDeliveryMode(name);
await client.setInboundDeliveryMode(name, 'manual_flush');

try {
  const snapshot = await client.snapshot(name, 'plain');
  console.log(snapshot.screen);

  const pending = await client.getPending(name);
  console.log(`Queued messages: ${pending.length}`);

  const input = client.openInputStream(name);
  try {
    await input.waitUntilOpen();
    const result = await input.send('please continue\n');
    console.log(`Wrote ${result.bytes_written} bytes`);
  } catch (error) {
    console.error(`Input stream failed: ${error instanceof Error ? error.message : error}`);
  } finally {
    input.close();
  }

  await client.resizePty(name, 40, 120);
  await client.flushPending(name);
} finally {
  await client.setInboundDeliveryMode(name, previousMode);
}

for await (const chunk of client.subscribeWorkerStream('Reviewer', { stream: 'stdout' })) {
  process.stdout.write(chunk);
}

// Named human
const human = relay.human({ name: 'Orchestrator' });
await human.sendMessage({ to: 'Worker', text: 'Start the task' });

// System identity (name: "system")
const sys = relay.system();
await sys.sendMessage({ to: 'Worker', text: 'Stop and report status' });

// Broadcast to all agents
await relay.broadcast('All hands: stand by for new task');

relay.addListener('messageReceived', (msg: Message) => { ... })
relay.addListener('messageSent', (msg: Message) => { ... })
relay.addListener('agentSpawned', (agent: Agent) => { ... })
relay.addListener('agentReleased', (agent: Agent) => { ... })
relay.addListener('agentExited', (agent: Agent) => { ... })
relay.addListener('agentReady', (agent: Agent) => { ... })
relay.addListener('agentIdle', ({ name, idleSecs }) => { ... })
relay.addListener('agentActivityChanged', ({ name, active, pendingDeliveries, reason }) => { ... })
relay.addListener('agentExitRequested', ({ name, reason }) => { ... })
relay.addListener('workerOutput', ({ name, stream, chunk }) => { ... })
relay.addListener('deliveryUpdate', (event: BrokerEvent) => { ... })
relay.addListener('agentResult', (result: AgentResult) => { ... })

interface Message {
  eventId: string;
  from: string;
  to: string;
  text: string;
  threadId?: string;
  data?: Record<string, unknown>;
}

// List all known agents
const agents = await relay.listAgents(): Promise<Agent[]>

// Get broker status
const status = await relay.getStatus(): Promise<BrokerStatus>

// Read last N lines of an agent's log file
const logs = await relay.getLogs('Worker', { lines: 100 })
// logs.found: boolean, logs.content: string

// List agents that have log files
const names = await relay.listLoggedAgents(): Promise<string[]>

// Stream an agent's log file (returns handle with .unsubscribe())
const handle = relay.followLogs('Worker', {
  historyLines: 50,
  onEvent(event) {
    if (event.type === 'log') console.log(event.content);
  },
})
handle.unsubscribe();

// Wait for the first of many agents to exit
const { agent, result } = await AgentRelay.waitForAny([agent1, agent2], 60000)

// Shut down all agents and the broker
await relay.shutdown()

import {
  getBrokerLogDir,
  listBrokerLogs,
  tailBrokerLog,
  pruneBrokerLogs,
  clearBrokerLogs,
} from '@agent-relay/sdk';

// Resolve the directory for the current platform.
const dir = getBrokerLogDir();

// List every {brokerId}.log[.YYYY-MM-DD] file, newest first.
const files = await listBrokerLogs();
// files: Array<{ path, name, brokerId, date, size, mtime }>

// Tail the most recent log file for a broker.
const tail = await tailBrokerLog('myproject', { lines: 500 });
// tail?.path / tail?.content — null if no log file exists

// Retention: remove rotated files older than 7 days. The active
// un-suffixed file is never touched.
const { removed, kept } = await pruneBrokerLogs({ keepDays: 7 });

// Wipe one broker's logs (or pass nothing to wipe everything).
await clearBrokerLogs({ brokerId: 'myproject' });

import { AgentRelay, Models } from '@agent-relay/sdk';

const relay = new AgentRelay();

relay.addListener('messageReceived', (msg) => {
  console.log(`${msg.from} → ${msg.to}: ${msg.text}`);
});

relay.addListener('agentSpawned', (agent) => {
  console.log(`Spawned: ${agent.name}`);
});

// Spawn agents
const planner = await relay.spawnAgent({
  name: 'Planner',
  cli: 'claude',
  model: Models.Claude.OPUS,
  task: 'Plan the feature implementation',
});

const coder = await relay.spawnAgent({
  name: 'Coder',
  cli: 'codex',
  model: Models.Codex.GPT_5_3_CODEX,
  task: 'Implement the plan',
});

// Wait for both to be ready
await planner.waitForReady();
await coder.waitForReady();

// Send a message
await planner.sendMessage({ to: 'Coder', text: 'Start implementing the auth module' });

// Wait for coder to finish
await coder.waitForExit(300_000);

await relay.shutdown();

import { Models } from '@agent-relay/sdk';

// Claude
Models.Claude.OPUS; // 'opus'
Models.Claude.SONNET; // 'sonnet'
Models.Claude.HAIKU; // 'haiku'

// Codex
Models.Codex.GPT_5_4; // 'gpt-5.4' (default)
Models.Codex.GPT_5_3_CODEX; // 'gpt-5.3-codex'

// Gemini
Models.Gemini.GEMINI_3_1_PRO_PREVIEW; // 'gemini-3.1-pro-preview' (default)
Models.Gemini.GEMINI_2_5_PRO; // 'gemini-2.5-pro'

// OpenCode
Models.Opencode.OPENAI_GPT_5_2; // 'openai/gpt-5.2' (default)
Models.Opencode.OPENCODE_GPT_5_NANO; // 'opencode/gpt-5-nano'

import { AgentRelayProtocolError, AgentRelayProcessError } from '@agent-relay/sdk';

try {
  await relay.spawnAgent({ cli: 'claude' });
} catch (err) {
  if (err instanceof AgentRelayProtocolError) {
    // Broker returned an error response (err.code available)
  }
  if (err instanceof AgentRelayProcessError) {
    // Broker process failed to start or crashed
  }
}