agent-relay 2.3.13 → 2.4.0

package/packages/sdk/dist/relay-adapter.js

@@ -0,0 +1,210 @@
+/**
+ * RelayAdapter — high-level interface over the broker SDK.
+ *
+ * Wraps AgentRelayClient with auto-start, safe result patterns,
+ * and convenience methods. Usable by any integration: dashboard,
+ * MCP, ACP bridge, CLI, or custom tooling.
+ *
+ * Usage:
+ *   import { RelayAdapter } from '@agent-relay/sdk';
+ *
+ *   const relay = new RelayAdapter({ cwd: projectRoot });
+ *   await relay.start();
+ *
+ *   await relay.spawn({ name: 'Worker1', cli: 'claude', task: 'Build auth' });
+ *   const agents = await relay.listAgents();
+ *   await relay.sendMessage({ to: 'Worker1', text: 'status?' });
+ *   await relay.release('Worker1');
+ *
+ *   await relay.shutdown();
+ */
+import { AgentRelayClient, } from './client.js';
+const WORKFLOW_BOOTSTRAP_TASK = 'You are connected to Agent Relay. Do not reply to this message and wait for relay messages and respond using Relaycast MCP tools.';
+const WORKFLOW_CONVENTIONS = [
+    'Messaging requirements:',
+    '- When you receive `Relay message from <sender> ...`, reply using `relay_send(to: "<sender>", message: "...")`.',
+    '- Send `ACK: ...` when you receive a task.',
+    '- Send `DONE: ...` when the task is complete.',
+    '- Do not reply only in terminal text; send the response via relay_send.',
+    '- Use relay_inbox() and relay_who() when context is missing.',
+].join('\n');
+function hasWorkflowConventions(task) {
+    const lower = task.toLowerCase();
+    return lower.includes('relay_send(') || (lower.includes('ack:') && lower.includes('done:'));
+}
+function buildSpawnTask(task, includeWorkflowConventions) {
+    const normalized = typeof task === 'string' ? task.trim() : '';
+    if (!includeWorkflowConventions) {
+        return normalized.length > 0 ? normalized : undefined;
+    }
+    if (normalized.length === 0) {
+        return `${WORKFLOW_BOOTSTRAP_TASK}\n\n${WORKFLOW_CONVENTIONS}`;
+    }
+    if (hasWorkflowConventions(normalized)) {
+        return normalized;
+    }
+    return `${normalized}\n\n${WORKFLOW_CONVENTIONS}`;
+}
+// ── Adapter ─────────────────────────────────────────────────────────
+export class RelayAdapter {
+    client;
+    started = false;
+    constructor(opts) {
+        const clientOpts = {
+            binaryPath: opts.binaryPath,
+            channels: opts.channels ?? ['general'],
+            cwd: opts.cwd,
+            env: opts.env,
+            clientName: opts.clientName ?? 'relay-adapter',
+        };
+        this.client = new AgentRelayClient(clientOpts);
+    }
+    // ── Lifecycle ───────────────────────────────────────────────────
+    /** Start the broker process. Idempotent. */
+    async start() {
+        if (this.started)
+            return;
+        await this.client.start();
+        this.started = true;
+    }
+    /** Shut down the broker and all spawned agents. */
+    async shutdown() {
+        await this.client.shutdown();
+        this.started = false;
+    }
+    // ── Spawn / Release ─────────────────────────────────────────────
+    /** Spawn an agent via the broker's PTY runtime. */
+    async spawn(req) {
+        await this.start();
+        try {
+            const input = {
+                name: req.name,
+                cli: req.cli,
+                task: buildSpawnTask(req.task, req.includeWorkflowConventions),
+                channels: ['general'],
+                model: req.model,
+                cwd: req.cwd,
+                team: req.team,
+                shadowOf: req.shadowOf,
+                shadowMode: req.shadowMode,
+            };
+            const result = await this.client.spawnPty(input);
+            // Try to get PID from agent list
+            let pid;
+            try {
+                const agents = await this.client.listAgents();
+                pid = agents.find((a) => a.name === req.name)?.pid;
+            }
+            catch {
+                // Non-fatal — PID is informational
+            }
+            return { success: true, name: result.name, pid };
+        }
+        catch (err) {
+            return { success: false, name: req.name, error: err?.message ?? String(err) };
+        }
+    }
+    /** Release (stop) a spawned agent. */
+    async release(name, reason) {
+        await this.start();
+        try {
+            await this.client.release(name, reason);
+            return { success: true, name };
+        }
+        catch (err) {
+            return { success: false, name, error: err?.message ?? String(err) };
+        }
+    }
+    // ── Query ───────────────────────────────────────────────────────
+    /** List all agents managed by this broker instance. */
+    async listAgents() {
+        await this.start();
+        const agents = await this.client.listAgents();
+        return agents.map((a) => ({
+            name: a.name,
+            cli: undefined, // Rust binary doesn't track CLI in list_agents response
+            pid: a.pid,
+            channels: a.channels,
+            parent: a.parent,
+            runtime: a.runtime,
+        }));
+    }
+    /** Check if a specific agent is spawned. */
+    async hasAgent(name) {
+        const agents = await this.listAgents();
+        return agents.some((a) => a.name === name);
+    }
+    /** Get broker status (agent count, pending deliveries). */
+    async getStatus() {
+        await this.start();
+        return this.client.getStatus();
+    }
+    // ── Messaging ───────────────────────────────────────────────────
+    /** Send a message to an agent or channel. */
+    async sendMessage(input) {
+        await this.start();
+        return this.client.sendMessage(input);
+    }
+    // ── PTY Input ───────────────────────────────────────────────────
+    /**
+     * Send raw input to an agent's PTY stdin.
+     * Useful for interrupts (ESC sequences), confirmations, etc.
+     */
+    async sendInput(name, data) {
+        await this.start();
+        await this.client.sendInput(name, data);
+    }
+    /**
+     * Send an interrupt (ESC ESC) to an agent.
+     * Convenience wrapper around sendInput.
+     */
+    async interruptAgent(name) {
+        try {
+            await this.sendInput(name, '\x1b\x1b');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── Model ───────────────────────────────────────────────────────
+    /** Switch an agent's model at runtime. */
+    async setModel(name, model, opts) {
+        await this.start();
+        return this.client.setModel(name, model, opts);
+    }
+    // ── Metrics ─────────────────────────────────────────────────────
+    /** Get resource metrics for agents (memory, uptime) and broker stats. */
+    async getMetrics(agent) {
+        await this.start();
+        return this.client.getMetrics(agent);
+    }
+    /** Get crash insights: recent crashes, patterns, and health score. */
+    async getCrashInsights() {
+        await this.start();
+        return this.client.getCrashInsights();
+    }
+    // ── Events ──────────────────────────────────────────────────────
+    /**
+     * Subscribe to broker events (agent_spawned, agent_released,
+     * relay_inbound, worker_stream, etc.).
+     *
+     * Returns an unsubscribe function.
+     */
+    onEvent(listener) {
+        return this.client.onEvent(listener);
+    }
+    /**
+     * Subscribe to broker stderr output (debug logs from the Rust binary).
+     * Returns an unsubscribe function.
+     */
+    onStderr(listener) {
+        return this.client.onBrokerStderr(listener);
+    }
+    // ── Underlying client (escape hatch) ────────────────────────────
+    /** Access the underlying AgentRelayClient for advanced operations. */
+    get raw() {
+        return this.client;
+    }
+}
+//# sourceMappingURL=relay-adapter.js.map

package/packages/sdk/dist/relay-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-adapter.js","sourceRoot":"","sources":["../src/relay-adapter.ts"],"names":[],"mappings":"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"}

package/packages/sdk/dist/relay.d.ts

@@ -0,0 +1,304 @@
+/**
+ * High-level facade for the Agent Relay SDK.
+ *
+ * Provides a clean, property-based API on top of the lower-level
+ * {@link AgentRelayClient} protocol client.
+ *
+ * @example
+ * ```ts
+ * import { AgentRelay } from "@agent-relay/sdk";
+ *
+ * const relay = new AgentRelay();
+ *
+ * relay.onMessageReceived = (message) => console.log(message);
+ * relay.onAgentSpawned = (agent) => console.log("spawned", agent.name);
+ *
+ * const codex = await relay.codex.spawn();
+ * const human = relay.human({ name: "System" });
+ * await human.sendMessage({ to: codex.name, text: "Hello!" });
+ *
+ * const agents = await relay.listAgents();
+ * for (const a of agents) await a.release();
+ * await relay.shutdown();
+ * ```
+ */
+import { type SendMessageInput, type SpawnPtyInput } from './client.js';
+import type { AgentRuntime, BrokerEvent, BrokerStatus, RestartPolicy } from './protocol.js';
+import { type FollowLogsOptions, type LogFollowHandle, type LogsResult } from './logs.js';
+export interface Message {
+    eventId: string;
+    from: string;
+    to: string;
+    text: string;
+    threadId?: string;
+    data?: Record<string, unknown>;
+}
+export type AgentStatus = 'spawning' | 'ready' | 'idle' | 'exited';
+export type DeliveryWaitStatus = 'ack' | 'failed' | 'timeout';
+export type DeliveryStateStatus = 'queued' | 'injected' | 'active' | 'verified' | 'failed';
+export interface DeliveryWaitResult {
+    eventId: string;
+    status: DeliveryWaitStatus;
+    targets: string[];
+}
+export interface DeliveryState {
+    eventId: string;
+    to: string;
+    status: DeliveryStateStatus;
+    updatedAt: number;
+}
+export interface SpawnOptions {
+    args?: string[];
+    channels?: string[];
+    model?: string;
+    cwd?: string;
+    team?: string;
+    shadowOf?: string;
+    shadowMode?: string;
+    idleThresholdSecs?: number;
+    restartPolicy?: RestartPolicy;
+}
+export interface SpawnAndWaitOptions extends SpawnOptions {
+    timeoutMs?: number;
+    waitForMessage?: boolean;
+}
+type AgentOutputPayload = {
+    stream: string;
+    chunk: string;
+};
+type AgentOutputCallback = ((chunk: string) => void) | ((data: AgentOutputPayload) => void);
+export interface Agent {
+    readonly name: string;
+    readonly runtime: AgentRuntime;
+    readonly channels: string[];
+    /** Current lifecycle status of the agent. */
+    readonly status: AgentStatus;
+    /** Set when the agent exits. Available after `onAgentExited` fires. */
+    exitCode?: number;
+    /** Set when the agent exits via signal. Available after `onAgentExited` fires. */
+    exitSignal?: string;
+    /** Set when the agent requests exit via /exit. Available after `onAgentExitRequested` fires. */
+    exitReason?: string;
+    release(reason?: string): Promise<void>;
+    waitForReady(timeoutMs?: number): Promise<void>;
+    /** Wait for the agent process to exit on its own.
+     *  @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;
+        threadId?: string;
+        priority?: number;
+        data?: Record<string, unknown>;
+    }): Promise<Message>;
+    /** Register a callback for PTY output from this agent. Returns an unsubscribe function. */
+    onOutput(callback: AgentOutputCallback): () => void;
+}
+export interface HumanHandle {
+    readonly name: string;
+    sendMessage(input: {
+        to: string;
+        text: string;
+        threadId?: string;
+        priority?: number;
+        data?: Record<string, unknown>;
+    }): Promise<Message>;
+}
+export interface AgentSpawner {
+    spawn(options?: {
+        name?: string;
+        args?: string[];
+        channels?: string[];
+        task?: string;
+        model?: string;
+        cwd?: string;
+    }): Promise<Agent>;
+}
+export type EventHook<T> = ((value: T) => void) | null;
+export interface AgentRelayOptions {
+    binaryPath?: string;
+    binaryArgs?: string[];
+    brokerName?: string;
+    channels?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    requestTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    /**
+     * Name for the auto-created Relaycast workspace.
+     * If omitted, a random name is generated.
+     * Ignored when RELAY_API_KEY is already set in env or process.env.
+     */
+    workspaceName?: string;
+    /**
+     * Base URL for the Relaycast API.
+     * Defaults to RELAYCAST_BASE_URL env var or https://api.relaycast.dev.
+     */
+    relaycastBaseUrl?: string;
+}
+export declare class AgentRelay {
+    onMessageReceived: EventHook<Message>;
+    onMessageSent: EventHook<Message>;
+    onAgentSpawned: EventHook<Agent>;
+    onAgentReleased: EventHook<Agent>;
+    onAgentExited: EventHook<Agent>;
+    onAgentReady: EventHook<Agent>;
+    onWorkerOutput: EventHook<{
+        name: string;
+        stream: string;
+        chunk: string;
+    }>;
+    onDeliveryUpdate: EventHook<BrokerEvent>;
+    onAgentExitRequested: EventHook<{
+        name: string;
+        reason: string;
+    }>;
+    onAgentIdle: EventHook<{
+        name: string;
+        idleSecs: number;
+    }>;
+    /** The resolved Relaycast workspace API key (available after first spawn). */
+    get workspaceKey(): string | undefined;
+    /** Observer URL for the auto-created workspace (available after first spawn). */
+    get observerUrl(): string | undefined;
+    readonly codex: AgentSpawner;
+    readonly claude: AgentSpawner;
+    readonly gemini: AgentSpawner;
+    private readonly clientOptions;
+    private readonly defaultChannels;
+    private readonly workspaceName?;
+    private readonly relaycastBaseUrl?;
+    private relayApiKey?;
+    private client?;
+    private startPromise?;
+    private unsubEvent?;
+    private readonly knownAgents;
+    private readonly readyAgents;
+    private readonly messageReadyAgents;
+    private readonly exitedAgents;
+    private readonly idleAgents;
+    private readonly deliveryStates;
+    private readonly outputListeners;
+    private readonly exitResolvers;
+    private exitResolverSeq;
+    private readonly idleResolvers;
+    private idleResolverSeq;
+    constructor(options?: AgentRelayOptions);
+    /**
+     * Subscribe to broker stderr output. Listener is wired immediately if the
+     * client is already started, otherwise it is attached when the client starts.
+     * Returns an unsubscribe function.
+     */
+    onBrokerStderr(listener: (line: string) => void): () => void;
+    spawnPty(input: SpawnPtyInput): Promise<Agent>;
+    spawn(name: string, cli: string, task?: string, options?: SpawnOptions): Promise<Agent>;
+    spawnAndWait(name: string, cli: string, task: string, options?: SpawnAndWaitOptions): Promise<Agent>;
+    human(opts: {
+        name: string;
+    }): HumanHandle;
+    system(): HumanHandle;
+    /**
+     * Broadcast a message to all connected agents.
+     * @param text — the message body
+     * @param options — optional sender name (defaults to "human:orchestrator")
+     */
+    broadcast(text: string, options?: {
+        from?: string;
+    }): Promise<Message>;
+    sendAndWaitForDelivery(input: SendMessageInput, timeoutMs?: number): Promise<DeliveryWaitResult>;
+    listAgents(): Promise<Agent[]>;
+    /** Pre-register a batch of agents with Relaycast before steps execute. */
+    preflightAgents(agents: Array<{
+        name: string;
+        cli: string;
+    }>): Promise<void>;
+    /** List agents with PIDs from the broker (for worker registration). */
+    listAgentsRaw(): Promise<Array<{
+        name: string;
+        pid?: number;
+    }>>;
+    getStatus(): Promise<BrokerStatus>;
+    getDeliveryState(eventId: string): DeliveryState | undefined;
+    /**
+     * Read the last N lines of an agent's log file.
+     *
+     * @example
+     * ```ts
+     * const logs = await relay.getLogs("Worker1", { lines: 100 });
+     * if (logs.found) console.log(logs.content);
+     * ```
+     */
+    getLogs(agentName: string, options?: {
+        lines?: number;
+    }): Promise<LogsResult>;
+    /** List all agents that have log files. */
+    listLoggedAgents(): Promise<string[]>;
+    /**
+     * Follow an agent's local log file with history bootstrap + incremental updates.
+     *
+     * @example
+     * ```ts
+     * const handle = relay.followLogs("Worker1", {
+     *   historyLines: 100,
+     *   onEvent(event) {
+     *     if (event.type === "log") console.log(event.content);
+     *   },
+     * });
+     *
+     * // Later:
+     * handle.unsubscribe();
+     * ```
+     */
+    followLogs(agentName: string, options: Omit<FollowLogsOptions, 'logsDir'>): LogFollowHandle;
+    /**
+     * Wait for any one of the given agents to exit. Returns the first agent
+     * that exits along with its exit reason.
+     *
+     * @example
+     * ```ts
+     * const { agent, result } = await AgentRelay.waitForAny([worker1, worker2], 60_000);
+     * console.log(`${agent.name} finished: ${result}`);
+     * ```
+     */
+    static waitForAny(agents: Agent[], timeoutMs?: number): Promise<{
+        agent: Agent;
+        result: 'exited' | 'timeout' | 'released';
+    }>;
+    /**
+     * Resolves when the agent process has started and connected to the broker.
+     * The agent's CLI may not yet be ready to receive messages.
+     * Use `waitForAgentMessage()` for full readiness.
+     */
+    waitForAgentReady(name: string, timeoutMs?: number): Promise<Agent>;
+    waitForAgentMessage(name: string, timeoutMs?: number): Promise<Agent>;
+    shutdown(): Promise<void>;
+    private ensureAgentHandle;
+    private updateDeliveryState;
+    private resolveEventTimestamp;
+    /** Resolve a target to a channel name. If `to` is `#channel`, use that
+     *  channel. If it's a known agent name, use the agent's first channel.
+     *  Otherwise fall back to the relay's default channel. */
+    private resolveChannel;
+    private inferOutputMode;
+    private dispatchOutput;
+    /**
+     * Ensure a Relaycast workspace API key is available.
+     * Resolution order:
+     *   1. Already resolved (cached from a previous call)
+     *   2. RELAY_API_KEY in options.env
+     *   3. RELAY_API_KEY in process.env
+     *   4. Auto-create a fresh workspace via the Relaycast REST API
+     */
+    private ensureRelaycastApiKey;
+    private ensureStarted;
+    private wireEvents;
+    private makeAgent;
+    private createSpawner;
+}
+export {};
+//# sourceMappingURL=relay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"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"}