agent-relay 1.3.2 → 1.5.0

package/dist/wrapper/relay-pty-orchestrator.d.ts

@@ -0,0 +1,270 @@
+/**
+ * RelayPtyOrchestrator - Orchestrates the relay-pty Rust binary
+ *
+ * This wrapper spawns the relay-pty binary and communicates via Unix socket.
+ * It provides the same interface as PtyWrapper but with improved latency
+ * (~550ms vs ~1700ms) by using direct PTY writes instead of tmux send-keys.
+ *
+ * Architecture:
+ * 1. Spawn relay-pty --name {agentName} -- {command} as child process
+ * 2. Connect to /tmp/relay-pty-{agentName}.sock for injection
+ * 3. Parse stdout for relay commands (relay-pty echoes all output)
+ * 4. Translate SEND envelopes → inject messages via socket
+ *
+ * @see docs/RUST_WRAPPER_DESIGN.md for protocol details
+ */
+import { BaseWrapper, type BaseWrapperConfig } from './base-wrapper.js';
+import type { SendPayload, SendMeta } from '../protocol/types.js';
+interface StatusResponse {
+    type: 'status';
+    agent_idle: boolean;
+    queue_length: number;
+    cursor_position?: [number, number];
+    last_output_ms: number;
+}
+/**
+ * Configuration for RelayPtyOrchestrator
+ */
+export interface RelayPtyOrchestratorConfig extends BaseWrapperConfig {
+    /** Path to relay-pty binary (default: searches PATH and ./relay-pty/target/release) */
+    relayPtyPath?: string;
+    /** Socket connect timeout in ms (default: 5000) */
+    socketConnectTimeoutMs?: number;
+    /** Socket reconnect attempts (default: 3) */
+    socketReconnectAttempts?: number;
+    /** Callback when agent exits */
+    onExit?: (code: number) => void;
+    /** Callback when injection fails after retries */
+    onInjectionFailed?: (messageId: string, error: string) => void;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * Events emitted by RelayPtyOrchestrator
+ */
+export interface RelayPtyOrchestratorEvents {
+    output: (data: string) => void;
+    exit: (code: number) => void;
+    error: (error: Error) => void;
+    'injection-failed': (event: {
+        messageId: string;
+        from: string;
+        error: string;
+    }) => void;
+    'backpressure': (event: {
+        queueLength: number;
+        accept: boolean;
+    }) => void;
+    'summary': (event: {
+        agentName: string;
+        summary: unknown;
+    }) => void;
+    'session-end': (event: {
+        agentName: string;
+        marker: unknown;
+    }) => void;
+}
+/**
+ * Orchestrator for relay-pty Rust binary
+ *
+ * Extends BaseWrapper to provide the same interface as PtyWrapper
+ * but uses the relay-pty binary for improved injection reliability.
+ */
+export declare class RelayPtyOrchestrator extends BaseWrapper {
+    protected config: RelayPtyOrchestratorConfig;
+    private relayPtyProcess?;
+    private socketPath;
+    private _logPath;
+    private _outboxPath;
+    private socket?;
+    private socketConnected;
+    private outputBuffer;
+    private rawBuffer;
+    private lastParsedLength;
+    private isInteractive;
+    private pendingInjections;
+    private backpressureActive;
+    private readyForMessages;
+    private lastUnreadIndicatorTime;
+    private readonly UNREAD_INDICATOR_COOLDOWN_MS;
+    constructor(config: RelayPtyOrchestratorConfig);
+    /**
+     * Debug log - only outputs when debug is enabled
+     */
+    private log;
+    /**
+     * Error log - always outputs (errors are important)
+     */
+    private logError;
+    /**
+     * Get the outbox path for this agent (for documentation purposes)
+     */
+    get outboxPath(): string;
+    /**
+     * Start the relay-pty process and connect to socket
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the relay-pty process gracefully
+     */
+    stop(): Promise<void>;
+    /**
+     * Inject content into the agent via socket
+     */
+    protected performInjection(content: string): Promise<void>;
+    /**
+     * Get cleaned output for parsing
+     */
+    protected getCleanOutput(): string;
+    /**
+     * Find the relay-pty binary
+     */
+    private findRelayPtyBinary;
+    /**
+     * Spawn the relay-pty process
+     */
+    private spawnRelayPty;
+    /**
+     * Handle output from relay-pty stdout (headless mode only)
+     * In interactive mode, stdout goes directly to terminal via inherited stdio
+     */
+    private handleOutput;
+    /**
+     * Format an unread message indicator if there are pending messages.
+     * Returns empty string if no pending messages or within cooldown period.
+     *
+     * Example output:
+     * ───────────────────────────
+     * 📬 2 unread messages (from: Alice, Bob)
+     */
+    private formatUnreadIndicator;
+    /**
+     * Handle stderr from relay-pty (logs and JSON parsed commands)
+     */
+    private handleStderr;
+    /**
+     * Handle a parsed command from Rust relay-pty
+     * Rust outputs structured JSON with 'kind' field: "message", "spawn", "release"
+     */
+    private handleRustParsedCommand;
+    /**
+     * Handle spawn command
+     */
+    private handleSpawnCommand;
+    /**
+     * Handle release command
+     */
+    private handleReleaseCommand;
+    /**
+     * Spawn agent via dashboard API
+     */
+    private spawnViaDashboardApi;
+    /**
+     * Release agent via dashboard API
+     */
+    private releaseViaDashboardApi;
+    /**
+     * Connect to the relay-pty socket
+     */
+    private connectToSocket;
+    /**
+     * Attempt a single socket connection
+     */
+    private attemptSocketConnection;
+    /**
+     * Disconnect from socket
+     */
+    private disconnectSocket;
+    /**
+     * Send a request to the socket and optionally wait for response
+     */
+    private sendSocketRequest;
+    /**
+     * Handle a response from the socket
+     */
+    private handleSocketResponse;
+    /**
+     * Handle injection result response
+     */
+    private handleInjectResult;
+    /**
+     * Handle backpressure notification
+     */
+    private handleBackpressure;
+    /**
+     * Inject a message into the agent via socket
+     */
+    private injectMessage;
+    /**
+     * Process queued messages
+     */
+    private processMessageQueue;
+    /**
+     * Override handleIncomingMessage to trigger queue processing
+     */
+    protected handleIncomingMessage(from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string): void;
+    /**
+     * Parse relay commands from output
+     */
+    private parseRelayCommands;
+    /**
+     * Parse fenced multi-line messages
+     */
+    private parseFencedMessages;
+    /**
+     * Parse single-line messages
+     */
+    private parseSingleLineMessages;
+    /**
+     * Check for [[SUMMARY]] blocks
+     */
+    private checkForSummary;
+    /**
+     * Check for [[SESSION_END]] blocks
+     */
+    private checkForSessionEnd;
+    /**
+     * Query status from relay-pty
+     */
+    queryStatus(): Promise<StatusResponse | null>;
+    /**
+     * Get raw output buffer
+     */
+    getRawOutput(): string;
+    /**
+     * Check if backpressure is active
+     */
+    isBackpressureActive(): boolean;
+    /**
+     * Get the socket path
+     */
+    getSocketPath(): string;
+    /**
+     * Get the relay-pty process PID
+     */
+    get pid(): number | undefined;
+    /**
+     * Get the log file path (not used by relay-pty, returns undefined)
+     */
+    get logPath(): string | undefined;
+    /**
+     * Kill the process forcefully
+     */
+    kill(): Promise<void>;
+    /**
+     * Get output lines (for compatibility with PtyWrapper)
+     * @param limit Maximum number of lines to return
+     */
+    getOutput(limit?: number): string[];
+    /**
+     * Write data directly to the process stdin
+     * @param data Data to write
+     */
+    write(data: string | Buffer): Promise<void>;
+    /**
+     * Get the agent ID (from continuity if available)
+     */
+    getAgentId(): string | undefined;
+}
+export {};
+//# sourceMappingURL=relay-pty-orchestrator.d.ts.map