@agent-relay/wrapper 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Relay Client
+ * Connects to the daemon and handles message sending/receiving.
+ *
+ * @deprecated **MIGRATION REQUIRED** - This module will be removed in a future version.
+ *
+ * ## Migration Path
+ *
+ * Replace imports from `@agent-relay/wrapper` with `@agent-relay/sdk`:
+ *
+ * ```typescript
+ * // BEFORE (deprecated)
+ * import { RelayClient } from '@agent-relay/wrapper';
+ *
+ * // AFTER (recommended)
+ * import { RelayClient } from '@agent-relay/sdk';
+ * ```
+ *
+ * The `@agent-relay/sdk` provides the same API with:
+ * - Identical method signatures
+ * - Same configuration options
+ * - Compatible event handlers
+ *
+ * ## Timeline
+ *
+ * - Current: Deprecation warning on first use
+ * - Next minor: TypeScript deprecation errors
+ * - Next major: This module will be removed
+ *
+ * ## Internal Use Only
+ *
+ * This client is retained only for internal daemon/wrapper integration.
+ * External consumers should always use `@agent-relay/sdk`.
+ *
+ * Optimizations:
+ * - Monotonic ID generation (faster than UUID)
+ * - Write coalescing (batch socket writes)
+ * - Circular dedup cache (O(1) eviction)
+ */
+import { type Envelope, type SendPayload, type SendMeta, type AckPayload, type PayloadKind, type SpeakOnTrigger, type EntityType } from '@agent-relay/protocol/types';
+import type { ChannelMessagePayload, MessageAttachment } from '@agent-relay/protocol/channels';
+export type ClientState = 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF';
+export interface SyncOptions {
+    timeoutMs?: number;
+    kind?: PayloadKind;
+    data?: Record<string, unknown>;
+    thread?: string;
+}
+export interface ClientConfig {
+    socketPath: string;
+    agentName: string;
+    /** Entity type: 'agent' (default) or 'user' for human users */
+    entityType?: EntityType;
+    /** Optional CLI identifier to surface to the dashboard */
+    cli?: string;
+    /** Optional program identifier (e.g., 'claude', 'gpt-4o') */
+    program?: string;
+    /** Optional model identifier (e.g., 'claude-3-opus-2024-xx') */
+    model?: string;
+    /** Optional task description for registry/dashboard */
+    task?: string;
+    /** Optional working directory to surface in registry/dashboard */
+    workingDirectory?: string;
+    /** Display name for human users */
+    displayName?: string;
+    /** Avatar URL for human users */
+    avatarUrl?: string;
+    /** Suppress client-side console logging */
+    quiet?: boolean;
+    reconnect: boolean;
+    maxReconnectAttempts: number;
+    reconnectDelayMs: number;
+    reconnectMaxDelayMs: number;
+    /** Internal flag to suppress deprecation warning (for wrapper internal use only) */
+    _internal?: boolean;
+}
+/**
+ * @deprecated Use `RelayClient` from `@agent-relay/sdk` instead.
+ * This class will be removed in a future major version.
+ */
+export declare class RelayClient {
+    /** Track if deprecation warning has been shown (warn once per process) */
+    private static _deprecationWarningShown;
+    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;
+    /**
+     * Handler for incoming messages.
+     * @param from - The sender agent name
+     * @param payload - The message payload
+     * @param messageId - Unique message ID
+     * @param meta - Optional message metadata
+     * @param originalTo - Original 'to' field from sender (e.g., '*' for broadcasts)
+     */
+    onMessage?: (from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string) => void;
+    /**
+     * Callback for channel messages.
+     * @param from - Sender name
+     * @param channel - Channel name
+     * @param body - Message content
+     * @param envelope - Full envelope for additional data
+     */
+    onChannelMessage?: (from: string, channel: string, body: string, envelope: Envelope<ChannelMessagePayload>) => void;
+    onStateChange?: (state: ClientState) => void;
+    onError?: (error: Error) => void;
+    constructor(config?: Partial<ClientConfig>);
+    get state(): ClientState;
+    get agentName(): string;
+    /** Get the session ID assigned by the server */
+    get currentSessionId(): string | undefined;
+    /**
+     * Connect to the relay daemon.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the relay daemon.
+     */
+    disconnect(): void;
+    /**
+     * Permanently destroy the client. Disconnects and prevents any reconnection.
+     */
+    destroy(): void;
+    /**
+     * Send a message to another agent.
+     * @param to - Target agent name or '*' for broadcast
+     * @param body - Message body
+     * @param kind - Message type (default: 'message')
+     * @param data - Optional structured data
+     * @param thread - Optional thread ID for grouping related messages
+     * @param meta - Optional message metadata (importance, replyTo, etc.)
+     */
+    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 a correlated ACK response.
+     */
+    sendAndWait(to: string, body: string, options?: SyncOptions): Promise<AckPayload>;
+    /**
+     * Broadcast a message to all agents.
+     */
+    broadcast(body: string, kind?: PayloadKind, data?: Record<string, unknown>): boolean;
+    /**
+     * 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).
+     * Used by dashboard to sync channel memberships for agents.
+     * @param channel - Channel name (e.g., '#general')
+     * @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 (does not require member to be connected).
+     * Used by dashboard to remove channel members.
+     * @param channel - Channel name (e.g., '#general')
+     * @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;
+    /**
+     * Subscribe to a topic.
+     */
+    subscribe(topic: string): boolean;
+    /**
+     * Unsubscribe from a topic.
+     */
+    unsubscribe(topic: string): boolean;
+    /**
+     * Bind this agent as a shadow to a primary agent.
+     * As a shadow, this agent will receive copies of messages to/from the primary.
+     * @param primaryAgent - The agent to shadow
+     * @param options - Shadow configuration options
+     */
+    bindAsShadow(primaryAgent: string, options?: {
+        /** When this shadow should speak (default: ['EXPLICIT_ASK']) */
+        speakOn?: SpeakOnTrigger[];
+        /** Receive copies of messages TO the primary (default: true) */
+        receiveIncoming?: boolean;
+        /** Receive copies of messages FROM the primary (default: true) */
+        receiveOutgoing?: boolean;
+    }): boolean;
+    /**
+     * Unbind this agent from a primary agent (stop shadowing).
+     * @param primaryAgent - The agent to stop shadowing
+     */
+    unbindAsShadow(primaryAgent: string): boolean;
+    /**
+     * Send log/output data to the daemon for dashboard streaming.
+     * Used by daemon-connected agents (not spawned workers) to stream their output.
+     * @param data - The log/output data to send
+     * @returns true if sent successfully, false otherwise
+     */
+    sendLog(data: string): boolean;
+    private setState;
+    private sendHello;
+    private send;
+    /**
+     * Flush all queued writes in a single syscall.
+     */
+    private flushWrites;
+    private handleData;
+    private processFrame;
+    private handleWelcome;
+    private handleDeliver;
+    private handleAck;
+    private handleChannelMessage;
+    private handlePing;
+    private handleErrorFrame;
+    private handleDisconnect;
+    private handleError;
+    private rejectPendingSyncAcks;
+    private scheduleReconnect;
+    /**
+     * Check if message was already delivered (deduplication).
+     * Uses circular buffer for O(1) eviction.
+     * @returns true if the message has already been seen.
+     */
+    private markDelivered;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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