agent-relay 2.0.19 → 2.0.21

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

@@ -4,7 +4,7 @@
  *
  * 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 } from './protocol/types.js';
+import { type Envelope, type SendPayload, type SendMeta, type AckPayload, type PayloadKind, type SpeakOnTrigger, type EntityType, type ChannelMessagePayload, type MessageAttachment, type SpawnResultPayload, type ReleaseResultPayload, type StatusResponsePayload, type InboxMessage, type AgentInfo, type HealthResponsePayload, type MetricsResponsePayload, type CreateProposalOptions, type VoteOptions } from './protocol/types.js';
 export type ClientState = 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF';
 export interface SyncOptions {
     timeoutMs?: number;
@@ -62,6 +62,9 @@ export declare class RelayClient {
     private writeQueue;
     private writeScheduled;
     private pendingSyncAcks;
+    private pendingSpawns;
+    private pendingReleases;
+    private pendingQueries;
     onMessage?: (from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string) => void;
     /**
      * Callback for channel messages.
@@ -125,6 +128,35 @@ export declare class RelayClient {
      * 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.shadowOf - Spawn as shadow of this agent
+     * @param options.shadowSpeakOn - Shadow speak-on triggers
+     * @param timeoutMs - Timeout for spawn operation (default: 30000ms)
+     */
+    spawn(options: {
+        name: string;
+        cli: string;
+        task?: string;
+        cwd?: string;
+        team?: string;
+        interactive?: boolean;
+        shadowOf?: string;
+        shadowSpeakOn?: SpeakOnTrigger[];
+    }, timeoutMs?: number): Promise<SpawnResultPayload>;
+    /**
+     * 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, timeoutMs?: number): Promise<ReleaseResultPayload>;
     /**
      * Join a channel.
      * @param channel - Channel name (e.g., '#general', 'dm:alice:bob')
@@ -161,6 +193,102 @@ export declare class RelayClient {
         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[]>;
+    /**
+     * 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>;
     private setState;
     private sendHello;
     private send;
@@ -171,11 +299,17 @@ export declare class RelayClient {
     private handleDeliver;
     private handleChannelMessage;
     private handleAck;
+    private handleSpawnResult;
+    private handleReleaseResult;
+    private handleQueryResponse;
     private handlePing;
     private handleErrorFrame;
     private handleDisconnect;
     private handleError;
     private rejectPendingSyncAcks;
+    private rejectPendingSpawns;
+    private rejectPendingReleases;
+    private rejectPendingQueries;
     private scheduleReconnect;
 }
 //# sourceMappingURL=client.d.ts.map

package/packages/sdk/dist/client.js

@@ -73,6 +73,9 @@ export class RelayClient {
     writeQueue = [];
     writeScheduled = false;
     pendingSyncAcks = new Map();
+    pendingSpawns = new Map();
+    pendingReleases = new Map();
+    pendingQueries = new Map();
     // Event handlers
     onMessage;
     /**
@@ -350,6 +353,91 @@ export class RelayClient {
         return this.send(envelope);
     }
     // =============================================================================
+    // Spawn/Release Operations
+    // =============================================================================
+    /**
+     * 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.shadowOf - Spawn as shadow of this agent
+     * @param options.shadowSpeakOn - Shadow speak-on triggers
+     * @param timeoutMs - Timeout for spawn operation (default: 30000ms)
+     */
+    async spawn(options, timeoutMs = 30000) {
+        if (this._state !== 'READY') {
+            throw new Error('Client not ready');
+        }
+        const envelopeId = generateId();
+        return new Promise((resolve, reject) => {
+            const timeoutHandle = setTimeout(() => {
+                this.pendingSpawns.delete(envelopeId);
+                reject(new Error(`Spawn timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pendingSpawns.set(envelopeId, { resolve, reject, timeoutHandle });
+            const envelope = {
+                v: PROTOCOL_VERSION,
+                type: 'SPAWN',
+                id: envelopeId,
+                ts: Date.now(),
+                payload: {
+                    name: options.name,
+                    cli: options.cli,
+                    task: options.task || '',
+                    cwd: options.cwd,
+                    team: options.team,
+                    interactive: options.interactive,
+                    shadowOf: options.shadowOf,
+                    shadowSpeakOn: options.shadowSpeakOn,
+                    spawnerName: this.config.agentName,
+                },
+            };
+            const sent = this.send(envelope);
+            if (!sent) {
+                clearTimeout(timeoutHandle);
+                this.pendingSpawns.delete(envelopeId);
+                reject(new Error('Failed to send spawn message'));
+            }
+        });
+    }
+    /**
+     * Release (terminate) an agent via the relay daemon.
+     * @param name - Agent name to release
+     * @param timeoutMs - Timeout for release operation (default: 10000ms)
+     */
+    async release(name, timeoutMs = 10000) {
+        if (this._state !== 'READY') {
+            throw new Error('Client not ready');
+        }
+        const envelopeId = generateId();
+        return new Promise((resolve, reject) => {
+            const timeoutHandle = setTimeout(() => {
+                this.pendingReleases.delete(envelopeId);
+                reject(new Error(`Release timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pendingReleases.set(envelopeId, { resolve, reject, timeoutHandle });
+            const envelope = {
+                v: PROTOCOL_VERSION,
+                type: 'RELEASE',
+                id: envelopeId,
+                ts: Date.now(),
+                payload: {
+                    name,
+                },
+            };
+            const sent = this.send(envelope);
+            if (!sent) {
+                clearTimeout(timeoutHandle);
+                this.pendingReleases.delete(envelopeId);
+                reject(new Error('Failed to send release message'));
+            }
+        });
+    }
+    // =============================================================================
     // Channel Operations
     // =============================================================================
     /**
@@ -461,6 +549,188 @@ export class RelayClient {
         };
         return this.send(envelope);
     }
+    // =============================================================================
+    // Consensus Operations
+    // =============================================================================
+    /**
+     * 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) {
+        if (this._state !== 'READY') {
+            return false;
+        }
+        // Build the PROPOSE command message
+        const lines = [
+            `PROPOSE: ${options.title}`,
+            `TYPE: ${options.consensusType ?? 'majority'}`,
+            `PARTICIPANTS: ${options.participants.join(', ')}`,
+            `DESCRIPTION: ${options.description}`,
+        ];
+        if (options.timeoutMs !== undefined) {
+            lines.push(`TIMEOUT: ${options.timeoutMs}`);
+        }
+        if (options.quorum !== undefined) {
+            lines.push(`QUORUM: ${options.quorum}`);
+        }
+        if (options.threshold !== undefined) {
+            lines.push(`THRESHOLD: ${options.threshold}`);
+        }
+        const body = lines.join('\n');
+        // Send to the special _consensus recipient
+        return this.sendMessage('_consensus', body, 'action');
+    }
+    /**
+     * 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) {
+        if (this._state !== 'READY') {
+            return false;
+        }
+        // Build the VOTE command
+        let body = `VOTE ${options.proposalId} ${options.value}`;
+        if (options.reason) {
+            body += ` ${options.reason}`;
+        }
+        // Send to the special _consensus recipient
+        return this.sendMessage('_consensus', body, 'action');
+    }
+    // =============================================================================
+    // Query Operations
+    // =============================================================================
+    /**
+     * Send a query to the daemon and wait for a response.
+     * @internal
+     */
+    async query(type, payload, timeoutMs = 5000) {
+        if (this._state !== 'READY') {
+            throw new Error('Client not ready');
+        }
+        const envelopeId = generateId();
+        return new Promise((resolve, reject) => {
+            const timeoutHandle = setTimeout(() => {
+                this.pendingQueries.delete(envelopeId);
+                reject(new Error(`Query timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pendingQueries.set(envelopeId, {
+                resolve: resolve,
+                reject,
+                timeoutHandle,
+            });
+            const envelope = {
+                v: PROTOCOL_VERSION,
+                type: type,
+                id: envelopeId,
+                ts: Date.now(),
+                payload,
+            };
+            const sent = this.send(envelope);
+            if (!sent) {
+                clearTimeout(timeoutHandle);
+                this.pendingQueries.delete(envelopeId);
+                reject(new Error(`Failed to send ${type} query`));
+            }
+        });
+    }
+    /**
+     * Get daemon status information.
+     * @returns Daemon status including version, uptime, and counts
+     */
+    async getStatus() {
+        return this.query('STATUS', {});
+    }
+    /**
+     * 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
+     */
+    async getInbox(options = {}) {
+        const payload = {
+            agent: this.config.agentName,
+            limit: options.limit,
+            unreadOnly: options.unreadOnly,
+            from: options.from,
+            channel: options.channel,
+        };
+        const response = await this.query('INBOX', payload);
+        return response.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
+     */
+    async listAgents(options = {}) {
+        const payload = {
+            includeIdle: options.includeIdle ?? true,
+            project: options.project,
+        };
+        const response = await this.query('LIST_AGENTS', payload);
+        return response.agents || [];
+    }
+    /**
+     * 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
+     */
+    async getHealth(options = {}) {
+        const payload = {
+            includeCrashes: options.includeCrashes ?? true,
+            includeAlerts: options.includeAlerts ?? true,
+        };
+        return this.query('HEALTH', payload);
+    }
+    /**
+     * 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
+     */
+    async getMetrics(options = {}) {
+        const payload = {
+            agent: options.agent,
+        };
+        return this.query('METRICS', payload);
+    }
     // Private methods
     setState(state) {
         this._state = state;
@@ -552,6 +822,12 @@ export class RelayClient {
             case 'ACK':
                 this.handleAck(envelope);
                 break;
+            case 'SPAWN_RESULT':
+                this.handleSpawnResult(envelope);
+                break;
+            case 'RELEASE_RESULT':
+                this.handleReleaseResult(envelope);
+                break;
             case 'ERROR':
                 this.handleErrorFrame(envelope);
                 break;
@@ -560,6 +836,13 @@ export class RelayClient {
                     console.warn('[sdk] Server busy, backing off');
                 }
                 break;
+            case 'STATUS_RESPONSE':
+            case 'INBOX_RESPONSE':
+            case 'LIST_AGENTS_RESPONSE':
+            case 'HEALTH_RESPONSE':
+            case 'METRICS_RESPONSE':
+                this.handleQueryResponse(envelope);
+                break;
         }
     }
     handleWelcome(envelope) {
@@ -627,6 +910,37 @@ export class RelayClient {
         this.pendingSyncAcks.delete(correlationId);
         pending.resolve(envelope.payload);
     }
+    handleSpawnResult(envelope) {
+        const replyTo = envelope.payload.replyTo;
+        if (!replyTo)
+            return;
+        const pending = this.pendingSpawns.get(replyTo);
+        if (!pending)
+            return;
+        clearTimeout(pending.timeoutHandle);
+        this.pendingSpawns.delete(replyTo);
+        pending.resolve(envelope.payload);
+    }
+    handleReleaseResult(envelope) {
+        const replyTo = envelope.payload.replyTo;
+        if (!replyTo)
+            return;
+        const pending = this.pendingReleases.get(replyTo);
+        if (!pending)
+            return;
+        clearTimeout(pending.timeoutHandle);
+        this.pendingReleases.delete(replyTo);
+        pending.resolve(envelope.payload);
+    }
+    handleQueryResponse(envelope) {
+        // Query responses use the envelope id to match requests
+        const pending = this.pendingQueries.get(envelope.id);
+        if (!pending)
+            return;
+        clearTimeout(pending.timeoutHandle);
+        this.pendingQueries.delete(envelope.id);
+        pending.resolve(envelope.payload);
+    }
     handlePing(envelope) {
         this.send({
             v: PROTOCOL_VERSION,
@@ -656,6 +970,9 @@ export class RelayClient {
         this.parser.reset();
         this.socket = undefined;
         this.rejectPendingSyncAcks(new Error('Disconnected while awaiting ACK'));
+        this.rejectPendingSpawns(new Error('Disconnected while awaiting spawn result'));
+        this.rejectPendingReleases(new Error('Disconnected while awaiting release result'));
+        this.rejectPendingQueries(new Error('Disconnected while awaiting query response'));
         if (this._destroyed) {
             this.setState('DISCONNECTED');
             return;
@@ -685,6 +1002,27 @@ export class RelayClient {
             this.pendingSyncAcks.delete(correlationId);
         }
     }
+    rejectPendingSpawns(error) {
+        for (const [id, pending] of this.pendingSpawns.entries()) {
+            clearTimeout(pending.timeoutHandle);
+            pending.reject(error);
+            this.pendingSpawns.delete(id);
+        }
+    }
+    rejectPendingReleases(error) {
+        for (const [id, pending] of this.pendingReleases.entries()) {
+            clearTimeout(pending.timeoutHandle);
+            pending.reject(error);
+            this.pendingReleases.delete(id);
+        }
+    }
+    rejectPendingQueries(error) {
+        for (const [id, pending] of this.pendingQueries.entries()) {
+            clearTimeout(pending.timeoutHandle);
+            pending.reject(error);
+            this.pendingQueries.delete(id);
+        }
+    }
     scheduleReconnect() {
         this.setState('BACKOFF');
         this.reconnectAttempts++;

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

@@ -27,6 +27,7 @@
  */
 export { RelayClient, type ClientState, type ClientConfig, type SyncOptions, } from './client.js';
 export { createRelay, createPair, type Relay, type RelayConfig, } from './standalone.js';
-export { PROTOCOL_VERSION, type MessageType, type PayloadKind, type Envelope, type EntityType, type SendPayload, type SendMeta, type SyncMeta, type DeliveryInfo, type AckPayload, type ErrorCode, type ErrorPayload, type SpeakOnTrigger, type ShadowConfig, type SpawnPayload, type SpawnResultPayload, type ReleasePayload, type ReleaseResultPayload, type ChannelMessagePayload, type ChannelJoinPayload, type ChannelLeavePayload, } from './protocol/index.js';
+export { PROTOCOL_VERSION, type MessageType, type PayloadKind, type Envelope, type EntityType, type SendPayload, type SendMeta, type SyncMeta, type DeliveryInfo, type AckPayload, type ErrorCode, type ErrorPayload, type SpeakOnTrigger, type ShadowConfig, type SpawnPayload, type SpawnResultPayload, type ReleasePayload, type ReleaseResultPayload, type ChannelMessagePayload, type ChannelJoinPayload, type ChannelLeavePayload, type MessageAttachment, type StatusResponsePayload, type InboxMessage, type AgentInfo, type HealthResponsePayload, type CrashRecord, type AlertRecord, type MetricsResponsePayload, type AgentMetrics, type ConsensusType, type VoteValue, type ProposalStatus, type CreateProposalOptions, type VoteOptions, } from './protocol/index.js';
 export { encodeFrame, encodeFrameLegacy, FrameParser, MAX_FRAME_BYTES, } from './protocol/index.js';
+export { getLogs, listLoggedAgents, type GetLogsOptions, type LogsResult, } from './logs.js';
 //# sourceMappingURL=index.d.ts.map

package/packages/sdk/dist/index.js

@@ -33,4 +33,6 @@ export { createRelay, createPair, } from './standalone.js';
 export { PROTOCOL_VERSION, } from './protocol/index.js';
 // Framing utilities
 export { encodeFrame, encodeFrameLegacy, FrameParser, MAX_FRAME_BYTES, } from './protocol/index.js';
+// Log utilities (file-based, doesn't require connection)
+export { getLogs, listLoggedAgents, } from './logs.js';
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,61 @@
+/**
+ * Log reading utilities for Agent Relay SDK.
+ *
+ * These utilities read agent logs from the local filesystem.
+ */
+/**
+ * Options for reading agent logs.
+ */
+export interface GetLogsOptions {
+    /** Directory containing worker logs. Defaults to `.agent-relay/worker-logs` in cwd. */
+    logsDir?: string;
+    /** Number of lines to return from the end. Default: 50 */
+    lines?: number;
+}
+/**
+ * Result of a logs query.
+ */
+export interface LogsResult {
+    /** Agent name */
+    agent: string;
+    /** Log content */
+    content: string;
+    /** Whether log file exists */
+    found: boolean;
+    /** Number of lines returned */
+    lineCount: number;
+}
+/**
+ * Get logs for a specific agent.
+ *
+ * @example
+ * ```typescript
+ * import { getLogs } from '@agent-relay/sdk';
+ *
+ * const result = await getLogs('Worker1', { lines: 100 });
+ * if (result.found) {
+ *   console.log(result.content);
+ * }
+ * ```
+ *
+ * @param agent - Agent name
+ * @param options - Options for reading logs
+ * @returns Log content and metadata
+ */
+export declare function getLogs(agent: string, options?: GetLogsOptions): Promise<LogsResult>;
+/**
+ * List all agents that have log files.
+ *
+ * @example
+ * ```typescript
+ * import { listLoggedAgents } from '@agent-relay/sdk';
+ *
+ * const agents = await listLoggedAgents();
+ * console.log('Agents with logs:', agents);
+ * ```
+ *
+ * @param logsDir - Directory containing worker logs
+ * @returns Array of agent names
+ */
+export declare function listLoggedAgents(logsDir?: string): Promise<string[]>;
+//# sourceMappingURL=logs.d.ts.map