agent-relay 2.3.13 → 2.4.0

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

@@ -1,538 +1,152 @@
-/**
- * RelayClient - Agent Relay SDK Client
- * @agent-relay/sdk
- *
- * Lightweight client for agent-to-agent communication via Agent Relay daemon.
- */
-import { type Envelope, type SendPayload, type SendMeta, type AckPayload, type PayloadKind, type SpeakOnTrigger, type EntityType, type ChannelMessagePayload, type MessageAttachment, type SpawnResultPayload, type ReleaseResultPayload, type SendInputResultPayload, type SetModelResultPayload, type ListWorkersResultPayload, type StatusResponsePayload, type InboxMessage, type MessagesResponsePayload, type AgentInfo, type RemoveAgentResponsePayload, type HealthResponsePayload, type MetricsResponsePayload, type CreateProposalOptions, type VoteOptions, type AgentReadyPayload } from '@agent-relay/protocol';
-export type ClientState = 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF';
-export interface SyncOptions {
-    timeoutMs?: number;
-    kind?: PayloadKind;
-    data?: Record<string, unknown>;
-    thread?: string;
+import { type AgentRuntime, type BrokerEvent, type BrokerStats, type BrokerStatus, type CrashInsightsResponse, type ProtocolError, type RestartPolicy } from './protocol.js';
+export interface AgentRelayClientOptions {
+    binaryPath?: string;
+    binaryArgs?: string[];
+    brokerName?: string;
+    channels?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    requestTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    clientName?: string;
+    clientVersion?: string;
 }
-/**
- * Options for the request() method.
- */
-export interface RequestOptions {
-    /** Timeout in milliseconds (default: 30000) */
-    timeout?: number;
-    /** Optional structured data to include with the request */
-    data?: Record<string, unknown>;
-    /** Optional thread identifier for grouping related messages */
-    thread?: string;
-    /** Message kind (default: 'message') */
-    kind?: PayloadKind;
+export interface SpawnPtyInput {
+    name: string;
+    cli: string;
+    args?: string[];
+    channels?: string[];
+    task?: string;
+    model?: string;
+    cwd?: string;
+    team?: string;
+    shadowOf?: string;
+    shadowMode?: string;
+    /** Silence duration in seconds before emitting agent_idle (0 = disabled, default: 30). */
+    idleThresholdSecs?: number;
+    /** Auto-restart policy for crashed agents. */
+    restartPolicy?: RestartPolicy;
+    /** Name of a previously released agent whose continuity context should be injected. */
+    continueFrom?: string;
 }
-/**
- * Response from the request() method.
- */
-export interface RequestResponse {
-    /** Sender of the response */
-    from: string;
-    /** Response body text */
-    body: string;
-    /** Optional structured data from the response */
-    data?: Record<string, unknown>;
-    /** The correlation ID used for this request/response */
-    correlationId: string;
-    /** Thread identifier if set */
-    thread?: string;
-    /** The full payload for advanced use cases */
-    payload: SendPayload;
+export interface SpawnHeadlessClaudeInput {
+    name: string;
+    args?: string[];
+    channels?: string[];
+    task?: string;
 }
-/**
- * Extended spawn result with optional readiness information.
- * When `waitForReady` is true, the spawn will wait for the agent to complete
- * its HELLO/WELCOME handshake before resolving.
- */
-export interface SpawnResult extends SpawnResultPayload {
-    /** Whether the agent is ready to receive messages (only set when waitForReady is true) */
-    ready?: boolean;
-    /** Agent ready details (only set when waitForReady is true and spawn succeeded) */
-    readyInfo?: AgentReadyPayload;
+export interface SendMessageInput {
+    to: string;
+    text: string;
+    from?: string;
+    threadId?: string;
+    priority?: number;
+    data?: Record<string, unknown>;
 }
-export interface ClientConfig {
-    /** Daemon socket path (default: /tmp/agent-relay.sock) */
-    socketPath: string;
-    /** Agent name */
-    agentName: string;
-    /** Entity type: 'agent' (default) or 'user' */
-    entityType?: EntityType;
-    /** CLI identifier (claude, codex, gemini, etc.) */
+export interface ListAgent {
+    name: string;
+    runtime: AgentRuntime;
     cli?: string;
-    /** Program identifier */
-    program?: string;
-    /** Model identifier */
     model?: string;
-    /** Task description */
-    task?: string;
-    /** Working directory */
-    workingDirectory?: string;
-    /** Team name */
     team?: string;
-    /** Display name for human users */
-    displayName?: string;
-    /** Avatar URL for human users */
-    avatarUrl?: string;
-    /** Suppress console logging */
-    quiet?: boolean;
-    /** Auto-reconnect on disconnect */
-    reconnect: boolean;
-    /** Max reconnect attempts */
-    maxReconnectAttempts: number;
-    /** Initial reconnect delay (ms) */
-    reconnectDelayMs: number;
-    /** Max reconnect delay (ms) */
-    reconnectMaxDelayMs: number;
-    /**
-     * Mark this client as a system component.
-     * Allows using reserved agent names (Dashboard, cli, system).
-     * Should only be set by trusted system components.
-     */
-    _isSystemComponent?: boolean;
+    channels: string[];
+    parent?: string;
+    pid?: number;
 }
-/**
- * RelayClient for agent-to-agent communication.
- */
-export declare class RelayClient {
-    private config;
-    private socket?;
-    private parser;
-    private _state;
-    private sessionId?;
-    private resumeToken?;
-    private reconnectAttempts;
-    private reconnectDelay;
-    private reconnectTimer?;
-    private _destroyed;
-    private dedupeCache;
-    private writeQueue;
-    private writeScheduled;
-    private pendingSyncAcks;
-    private pendingSpawns;
-    private pendingReleases;
-    private pendingSendInputs;
-    private pendingSetModels;
-    private pendingListWorkers;
-    private pendingQueries;
-    private pendingRequests;
-    private pendingAgentReady;
-    onMessage?: (from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string) => void;
-    /**
-     * Callback for channel messages.
-     */
-    onChannelMessage?: (from: string, channel: string, body: string, envelope: Envelope<ChannelMessagePayload>) => void;
-    onStateChange?: (state: ClientState) => void;
-    onError?: (error: Error) => void;
-    /**
-     * Callback when an agent becomes ready (completes HELLO/WELCOME handshake).
-     * This is broadcast by the daemon when any agent connects.
-     * Useful for knowing when a spawned agent is ready to receive messages.
-     */
-    onAgentReady?: (info: AgentReadyPayload) => void;
-    constructor(config?: Partial<ClientConfig>);
-    get state(): ClientState;
-    get agentName(): string;
-    get currentSessionId(): string | undefined;
-    /**
-     * Connect to the relay daemon.
-     */
-    connect(): Promise<void>;
-    /**
-     * Disconnect from the relay daemon.
-     */
-    disconnect(): void;
-    /**
-     * Permanently destroy the client.
-     */
-    destroy(): void;
-    /**
-     * Send a message to another agent.
-     */
-    sendMessage(to: string, body: string, kind?: PayloadKind, data?: Record<string, unknown>, thread?: string, meta?: SendMeta): boolean;
-    /**
-     * Send an ACK for a delivered message.
-     */
-    sendAck(payload: AckPayload): boolean;
-    /**
-     * Send a message and wait for ACK response.
-     */
-    sendAndWait(to: string, body: string, options?: SyncOptions): Promise<AckPayload>;
-    /**
-     * Send a request to another agent and wait for their response.
-     *
-     * This implements a request/response pattern where the message is sent with
-     * a correlation ID, and the method waits for the target agent to respond
-     * with a message containing that correlation ID.
-     *
-     * @example
-     * ```typescript
-     * // Simple request
-     * const response = await client.request('Worker', 'Process this task');
-     * console.log(response.body); // Worker's response
-     *
-     * // With options
-     * const response = await client.request('Worker', 'Process task', {
-     *   timeout: 60000,
-     *   data: { taskId: '123', priority: 'high' },
-     *   thread: 'task-thread-1',
-     * });
-     * ```
-     *
-     * @param to - Target agent name
-     * @param body - Request message body
-     * @param options - Request options (timeout, data, thread, kind)
-     * @returns Promise that resolves with the response from the target agent
-     * @throws Error if client is not ready, send fails, timeout occurs, or agent disconnects
-     */
-    request(to: string, body: string, options?: RequestOptions): Promise<RequestResponse>;
-    /**
-     * Respond to a request from another agent.
-     *
-     * This is a convenience method for responding to messages that have a
-     * correlation ID. The response will be routed back to the requesting agent.
-     *
-     * @param correlationId - The correlation ID from the original request (from data._correlationId or meta.replyTo)
-     * @param to - Target agent (the one who sent the original request)
-     * @param body - Response body
-     * @param data - Optional structured data to include in the response
-     * @returns true if the message was sent
-     */
-    respond(correlationId: string, to: string, body: string, data?: Record<string, unknown>): boolean;
-    /**
-     * Broadcast a message to all agents.
-     */
-    broadcast(body: string, kind?: PayloadKind, data?: Record<string, unknown>): boolean;
-    /**
-     * Subscribe to a topic.
-     */
-    subscribe(topic: string): boolean;
-    /**
-     * Unsubscribe from a topic.
-     */
-    unsubscribe(topic: string): boolean;
-    /**
-     * Bind as a shadow to a primary agent.
-     */
-    bindAsShadow(primaryAgent: string, options?: {
-        speakOn?: SpeakOnTrigger[];
-        receiveIncoming?: boolean;
-        receiveOutgoing?: boolean;
-    }): boolean;
-    /**
-     * Unbind from a primary agent.
-     */
-    unbindAsShadow(primaryAgent: string): boolean;
-    /**
-     * Send log output to the daemon for dashboard streaming.
-     */
-    sendLog(data: string): boolean;
-    /**
-     * Spawn a new agent via the relay daemon.
-     * @param options - Spawn options
-     * @param options.name - Name for the new agent
-     * @param options.cli - CLI to use (claude, codex, gemini, etc.)
-     * @param options.task - Task description
-     * @param options.cwd - Working directory
-     * @param options.team - Team name
-     * @param options.interactive - Interactive mode
-     * @param options.shadowMode - Shadow execution mode ('subagent' or 'process')
-     * @param options.shadowOf - Spawn as shadow of this agent
-     * @param options.shadowAgent - Shadow agent profile to use (for subagent mode)
-     * @param options.shadowTriggers - When to trigger the shadow (for subagent mode)
-     * @param options.shadowSpeakOn - Shadow speak-on triggers
-     * @param options.waitForReady - Wait for the agent to be ready before resolving (default: false)
-     * @param options.readyTimeoutMs - Timeout for agent to become ready (default: 60000ms)
-     * @param timeoutMs - Timeout for spawn operation (default: 60000ms)
-     * @returns Spawn result. When waitForReady is true, includes `ready` and `readyInfo` fields.
-     */
-    spawn(options: {
+export declare class AgentRelayProtocolError extends Error {
+    code: string;
+    retryable: boolean;
+    data?: unknown;
+    constructor(payload: ProtocolError);
+}
+export declare class AgentRelayProcessError extends Error {
+    constructor(message: string);
+}
+export declare class AgentRelayClient {
+    private readonly options;
+    private child?;
+    private stdoutRl?;
+    private stderrRl?;
+    private lastStderrLine?;
+    private requestSeq;
+    private pending;
+    private startingPromise?;
+    private eventListeners;
+    private stderrListeners;
+    private eventBuffer;
+    private maxBufferSize;
+    private exitPromise?;
+    /** The workspace key returned by the broker in its hello_ack response. */
+    workspaceKey?: string;
+    constructor(options?: AgentRelayClientOptions);
+    static start(options?: AgentRelayClientOptions): Promise<AgentRelayClient>;
+    onEvent(listener: (event: BrokerEvent) => void): () => void;
+    queryEvents(filter?: {
+        kind?: string;
+        name?: string;
+        since?: number;
+        limit?: number;
+    }): BrokerEvent[];
+    getLastEvent(kind: string, name?: string): BrokerEvent | undefined;
+    onBrokerStderr(listener: (line: string) => void): () => void;
+    start(): Promise<void>;
+    /**
+     * Pre-register a batch of agents with Relaycast before their steps execute.
+     * The broker warms its token cache in parallel; subsequent spawn_agent calls
+     * hit the cache rather than waiting on individual HTTP registrations.
+     * Fire-and-forget from the caller's perspective — broker responds immediately
+     * and registers in the background.
+     */
+    preflightAgents(agents: Array<{
         name: string;
-        cli: string;
-        task?: string;
-        cwd?: string;
-        team?: string;
-        /** Model override (e.g., 'opus', 'sonnet', 'haiku'). Takes precedence over agent profile. */
-        model?: string;
-        interactive?: boolean;
-        shadowMode?: 'subagent' | 'process';
-        shadowOf?: string;
-        shadowAgent?: string;
-        shadowTriggers?: SpeakOnTrigger[];
-        shadowSpeakOn?: SpeakOnTrigger[];
-        /** User ID for cloud persistence */
-        userId?: string;
-        /** Include ACK/DONE workflow conventions in agent instructions */
-        includeWorkflowConventions?: boolean;
-        /** Override the spawner name (defaults to this client's agentName) */
-        spawnerName?: string;
-        /** Wait for the agent to complete connection before resolving */
-        waitForReady?: boolean;
-        /** Timeout for agent to become ready (default: 60000ms). Only used when waitForReady is true. */
-        readyTimeoutMs?: number;
-    }, timeoutMs?: number): Promise<SpawnResult>;
-    /**
-     * Wait for an agent to become ready (complete HELLO/WELCOME handshake).
-     * This is useful when you want to wait for an agent that was spawned through
-     * another mechanism, or to verify an agent is connected before sending messages.
-     *
-     * @example
-     * ```typescript
-     * // Wait for an agent that might be spawning
-     * try {
-     *   const readyInfo = await client.waitForAgentReady('Worker', 30000);
-     *   console.log(`Worker is ready: ${readyInfo.cli}`);
-     * } catch (err) {
-     *   console.error('Worker did not become ready in time');
-     * }
-     * ```
-     *
-     * @param name - Agent name to wait for
-     * @param timeoutMs - Timeout in milliseconds (default: 60000ms)
-     * @returns Promise that resolves with AgentReadyPayload when the agent connects
-     * @throws Error if the agent doesn't become ready within the timeout
-     */
-    waitForAgentReady(name: string, timeoutMs?: number): Promise<AgentReadyPayload>;
-    /**
-     * Release (terminate) an agent via the relay daemon.
-     * @param name - Agent name to release
-     * @param timeoutMs - Timeout for release operation (default: 10000ms)
-     */
-    release(name: string, reason?: string, timeoutMs?: number): Promise<ReleaseResultPayload>;
-    /**
-     * Send input data to a spawned agent's PTY.
-     * @param name - Agent name to send input to
-     * @param data - Input data to send
-     * @param timeoutMs - Timeout for the operation (default: 10000ms)
-     */
-    sendWorkerInput(name: string, data: string, timeoutMs?: number): Promise<SendInputResultPayload>;
-    /**
-     * Change the model of a running spawned agent.
-     * The command waits for the agent to be idle before sending the model switch command.
-     *
-     * @param name - Agent name to switch model for
-     * @param model - Target model (e.g., 'opus', 'sonnet', 'haiku')
-     * @param options - Options including idle wait timeout
-     * @param operationTimeoutMs - Timeout for the overall protocol operation (default: 45000ms)
-     */
-    setWorkerModel(name: string, model: string, options?: {
+        cli: string | AgentRuntime;
+    }>): Promise<void>;
+    spawnPty(input: SpawnPtyInput): Promise<{
+        name: string;
+        runtime: AgentRuntime;
+    }>;
+    spawnHeadlessClaude(input: SpawnHeadlessClaudeInput): Promise<{
+        name: string;
+        runtime: AgentRuntime;
+    }>;
+    release(name: string, reason?: string): Promise<{
+        name: string;
+    }>;
+    sendInput(name: string, data: string): Promise<{
+        name: string;
+        bytes_written: number;
+    }>;
+    setModel(name: string, model: string, opts?: {
         timeoutMs?: number;
-    }, operationTimeoutMs?: number): Promise<SetModelResultPayload>;
-    /**
-     * List active spawned workers.
-     * @param timeoutMs - Timeout for the operation (default: 10000ms)
-     */
-    listWorkers(timeoutMs?: number): Promise<ListWorkersResultPayload>;
-    /**
-     * Join a channel.
-     * @param channel - Channel name (e.g., '#general', 'dm:alice:bob')
-     * @param displayName - Optional display name for this member
-     */
-    joinChannel(channel: string, displayName?: string): boolean;
-    /**
-     * Admin join: Add any member to a channel (does not require member to be connected).
-     * @param channel - Channel name
-     * @param member - Name of the member to add
-     */
-    adminJoinChannel(channel: string, member: string): boolean;
-    /**
-     * Leave a channel.
-     * @param channel - Channel name to leave
-     * @param reason - Optional reason for leaving
-     */
-    leaveChannel(channel: string, reason?: string): boolean;
-    /**
-     * Admin remove: Remove any member from a channel.
-     * @param channel - Channel name
-     * @param member - Name of the member to remove
-     */
-    adminRemoveMember(channel: string, member: string): boolean;
-    /**
-     * Send a message to a channel.
-     * @param channel - Channel name
-     * @param body - Message content
-     * @param options - Optional thread, mentions, attachments
-     */
-    sendChannelMessage(channel: string, body: string, options?: {
-        thread?: string;
-        mentions?: string[];
-        attachments?: MessageAttachment[];
-        data?: Record<string, unknown>;
-    }): boolean;
-    /**
-     * Create a consensus proposal.
-     *
-     * The proposal will be broadcast to all participants. They can vote using
-     * the `vote()` method. Results are delivered via `onMessage` callback.
-     *
-     * @example
-     * ```typescript
-     * client.createProposal({
-     *   title: 'Approve API design',
-     *   description: 'Should we proceed with the REST API design?',
-     *   participants: ['Developer', 'Reviewer', 'Lead'],
-     *   consensusType: 'majority',
-     * });
-     * ```
-     *
-     * @param options - Proposal options
-     * @returns true if the message was sent
-     */
-    createProposal(options: CreateProposalOptions): boolean;
-    /**
-     * Vote on a consensus proposal.
-     *
-     * @example
-     * ```typescript
-     * // Approve with a reason
-     * client.vote({
-     *   proposalId: 'prop_123',
-     *   value: 'approve',
-     *   reason: 'Looks good to me',
-     * });
-     *
-     * // Reject without reason
-     * client.vote({ proposalId: 'prop_123', value: 'reject' });
-     * ```
-     *
-     * @param options - Vote options
-     * @returns true if the message was sent
-     */
-    vote(options: VoteOptions): boolean;
-    /**
-     * Send a query to the daemon and wait for a response.
-     * @internal
-     */
-    private query;
-    /**
-     * Get daemon status information.
-     * @returns Daemon status including version, uptime, and counts
-     */
-    getStatus(): Promise<StatusResponsePayload>;
-    /**
-     * Get messages from the inbox.
-     * @param options - Filter options
-     * @param options.limit - Maximum number of messages to return
-     * @param options.unreadOnly - Only return unread messages
-     * @param options.from - Filter by sender
-     * @param options.channel - Filter by channel
-     * @returns Array of inbox messages
-     */
-    getInbox(options?: {
-        limit?: number;
-        unreadOnly?: boolean;
-        from?: string;
-        channel?: string;
-    }): Promise<InboxMessage[]>;
-    /**
-     * Query all messages (not filtered by recipient).
-     * Used by dashboard to get message history.
-     * @param options - Query options
-     * @param options.limit - Maximum number of messages to return (default: 100)
-     * @param options.sinceTs - Only return messages after this timestamp
-     * @param options.from - Filter by sender
-     * @param options.to - Filter by recipient
-     * @param options.thread - Filter by thread ID
-     * @param options.order - Sort order ('asc' or 'desc', default: 'desc')
-     * @returns Array of messages
-     */
-    queryMessages(options?: {
-        limit?: number;
-        sinceTs?: number;
-        from?: string;
-        to?: string;
-        thread?: string;
-        order?: 'asc' | 'desc';
-    }): Promise<MessagesResponsePayload['messages']>;
-    /**
-     * List online agents.
-     * @param options - Filter options
-     * @param options.includeIdle - Include idle agents (default: true)
-     * @param options.project - Filter by project
-     * @returns Array of agent info
-     */
-    listAgents(options?: {
-        includeIdle?: boolean;
-        project?: string;
-    }): Promise<AgentInfo[]>;
-    /**
-     * Get system health information.
-     * @param options - Include options
-     * @param options.includeCrashes - Include crash history (default: true)
-     * @param options.includeAlerts - Include alerts (default: true)
-     * @returns Health information including score, issues, and recommendations
-     */
-    getHealth(options?: {
-        includeCrashes?: boolean;
-        includeAlerts?: boolean;
-    }): Promise<HealthResponsePayload>;
-    /**
-     * Get resource metrics for agents.
-     * @param options - Filter options
-     * @param options.agent - Filter to a specific agent
-     * @returns Metrics including memory, CPU, and system info
-     */
-    getMetrics(options?: {
-        agent?: string;
-    }): Promise<MetricsResponsePayload>;
-    /**
-     * List only currently connected agents (not historical/registered agents).
-     * Use this instead of listAgents() when you need accurate liveness information.
-     * @param options - Filter options
-     * @param options.project - Filter by project
-     * @returns Array of currently connected agent info
-     */
-    listConnectedAgents(options?: {
-        project?: string;
-    }): Promise<AgentInfo[]>;
-    /**
-     * Remove an agent from the registry (sessions, agents.json).
-     * Use this to clean up stale agents that are no longer needed.
-     * @param name - Agent name to remove
-     * @param options - Removal options
-     * @param options.removeMessages - Also remove all messages from/to this agent (default: false)
-     * @returns Result indicating if the agent was removed
-     */
-    removeAgent(name: string, options?: {
-        removeMessages?: boolean;
-    }): Promise<RemoveAgentResponsePayload>;
-    private setState;
-    private sendHello;
-    private send;
-    private flushWrites;
-    private handleData;
-    private processFrame;
-    private handleWelcome;
-    private handleDeliver;
-    /**
-     * Extract correlation ID from a delivered message.
-     * Checks both payload_meta.replyTo and payload.data._correlationId
-     */
-    private extractCorrelationId;
-    private handleChannelMessage;
-    private handleAck;
-    private handleSpawnResult;
-    private handleReleaseResult;
-    private handleSendInputResult;
-    private handleSetModelResult;
-    private handleListWorkersResult;
-    private handleAgentReady;
-    private handleQueryResponse;
-    private handlePing;
-    private handleErrorFrame;
-    private handleDisconnect;
-    private handleError;
-    private rejectPendingSyncAcks;
-    private rejectPendingSpawns;
-    private rejectPendingReleases;
-    private rejectPendingSendInputs;
-    private rejectPendingSetModels;
-    private rejectPendingListWorkers;
-    private rejectPendingQueries;
-    private rejectPendingRequests;
-    private rejectPendingAgentReady;
-    private scheduleReconnect;
+    }): Promise<{
+        name: string;
+        model: string;
+        success: boolean;
+    }>;
+    getMetrics(agent?: string): Promise<{
+        agents: Array<{
+            name: string;
+            pid: number;
+            memory_bytes: number;
+            uptime_secs: number;
+        }>;
+        broker?: BrokerStats;
+    }>;
+    getCrashInsights(): Promise<CrashInsightsResponse>;
+    sendMessage(input: SendMessageInput): Promise<{
+        event_id: string;
+        targets: string[];
+    }>;
+    listAgents(): Promise<ListAgent[]>;
+    getStatus(): Promise<BrokerStatus>;
+    shutdown(): Promise<void>;
+    waitForExit(): Promise<void>;
+    private startInternal;
+    private disposeProcessHandles;
+    private failAllPending;
+    private handleStdoutLine;
+    private requestHello;
+    private requestOk;
+    private sendRequest;
 }
 //# sourceMappingURL=client.d.ts.map