echoclaw-relay-agent 0.8.2 → 0.9.4

package/dist/RelayAgent.d.ts

@@ -30,6 +30,7 @@ export declare class RelayAgent extends EventEmitter {
     private _stopped;
     private _starting;
     private _paired;
+    private _rekeyRetryCount;
     private _activePairing;
     private readonly config;
     private readonly subscribers;

package/dist/RelayAgent.js

@@ -97,6 +97,12 @@ export class RelayAgent extends EventEmitter {
             writable: true,
             value: false
         });
+        Object.defineProperty(this, "_rekeyRetryCount", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
         Object.defineProperty(this, "_activePairing", {
             enumerable: true,
             configurable: true,
@@ -150,6 +156,7 @@ export class RelayAgent extends EventEmitter {
         this._stopped = false;
         // Teardown previous transport before starting new
         if (this.transport) {
+            this.transport.removeAllListeners(); // Prevent listener accumulation
             this.transport.disconnect();
             this.transport = null;
         }
@@ -210,10 +217,14 @@ export class RelayAgent extends EventEmitter {
         this._activePairing?.abort();
         this._activePairing = null;
         this.gatewayManager?.stop();
-        this.transport?.disconnect();
-        this.transport = null;
+        if (this.transport) {
+            this.transport.removeAllListeners(); // Prevent leak
+            this.transport.disconnect();
+            this.transport = null;
+        }
         this.sessionKey = null;
         this.frameCrypto = null;
+        this._dataHandler = null;
         this.setStatus('disconnected');
     }
     // ── Private ────────────────────────────────────────────────
@@ -285,6 +296,11 @@ export class RelayAgent extends EventEmitter {
         this.frameCrypto = new FrameCrypto(result.sessionKey);
         this._paired = true;
         this._activePairing = null;
+        // Update transport URL so auto-reconnect uses ?resume=sessionId
+        // instead of the original ?code=XXXX (which was consumed after first pairing)
+        if (this.transport) {
+            this.transport.setUrl(`${this.config.relayServer}/agent/connect?resume=${result.sessionId}`);
+        }
         // Persist session for future auto-resume
         await this.sessionStore.save({
             pairingCode: result.pairingCode,
@@ -375,15 +391,20 @@ export class RelayAgent extends EventEmitter {
             if (this._paired && this.transport) {
                 // Transport reconnected after prior successful pairing —
                 // redo ECDH because desktop may have new ephemeral keys.
-                // Cancel any in-flight pairing and invalidate old crypto state.
+                // Cancel any in-flight pairing but KEEP old crypto state
+                // so data handler can still decrypt until re-key succeeds.
                 this._activePairing?.abort();
-                this.sessionKey = null;
-                this.frameCrypto = null;
+                // CRITICAL: Do NOT null sessionKey/frameCrypto here.
+                // If re-key fails, we want the data handler to keep working
+                // with the old keys rather than dropping all messages.
                 this.setStatus('connecting');
                 const pairing = new PairingProtocol(this.transport);
                 this._activePairing = pairing;
-                pairing.pairAsAgent()
+                // Use shorter timeout for re-key (30s) vs initial pairing (10 min).
+                // If desktop is online, ECDH completes in <1s; 30s gives ample margin.
+                pairing.pairAsAgent(undefined, 30000)
                     .then(result => {
+                    this._rekeyRetryCount = 0; // Reset on success
                     this.onPaired(result);
                     // V2: Reattach gateway callbacks after reconnect
                     if (this.gatewayManager) {
@@ -397,6 +418,28 @@ export class RelayAgent extends EventEmitter {
                 })
                     .catch(err => {
                     this._activePairing = null;
+                    this._rekeyRetryCount++;
+                    // Circuit breaker: after 5 consecutive failures, force full reconnect cycle
+                    // (disconnect + restart resets the relay server connection from scratch)
+                    if (this._rekeyRetryCount >= 5) {
+                        this._rekeyRetryCount = 0; // Reset for next cycle
+                        this.emit('error', new Error(`Re-key failed 5 times, forcing fresh reconnect`));
+                        if (this.transport) {
+                            this.transport.disconnect();
+                            this.transport.restart();
+                        }
+                        return;
+                    }
+                    // Re-key failed — keep old crypto intact, mark as connected
+                    // (data handler still works with old keys if desktop didn't re-key either)
+                    if (this._paired && this.sessionKey) {
+                        this.setStatus('connected');
+                    }
+                    // If WS is still OPEN, force reconnect to trigger fresh on('open')
+                    if (this.transport?.isConnected) {
+                        this.transport.disconnect();
+                        this.transport.restart();
+                    }
                     this.emit('error', err);
                 });
             }

package/dist/RelayClient.d.ts

@@ -36,6 +36,7 @@ export declare class RelayClient extends EventEmitter {
     private _stopped;
     private _paired;
     private _needsRekey;
+    private _rekeyRetryCount;
     private _activePairing;
     private readonly config;
     private readonly sessionStore;

package/dist/RelayClient.js

@@ -91,6 +91,12 @@ export class RelayClient extends EventEmitter {
             writable: true,
             value: false
         });
+        Object.defineProperty(this, "_rekeyRetryCount", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
         Object.defineProperty(this, "_activePairing", {
             enumerable: true,
             configurable: true,
@@ -253,13 +259,21 @@ export class RelayClient extends EventEmitter {
             await this.onPaired(result, 'resumed');
         }
         catch (err) {
-            // Resume failed — clean up transport, clear stale session to prevent infinite retry loop,
-            // and notify caller so UI can prompt for fresh pairing code.
+            // Resume failed — clean up transport
             this.transport?.disconnect();
             this.transport = null;
             this.frameCrypto = null;
             this.setStatus('disconnected');
-            await this.sessionStore.clear();
+            // Only clear session for permanent errors (server says session is dead).
+            // Transient errors (network, timeout) keep session.json for retry.
+            const errMsg = err instanceof Error ? err.message : String(err);
+            const isPermanent = errMsg.includes('DEVICE_TOKEN_MISMATCH') ||
+                errMsg.includes('SESSION_NOT_FOUND') ||
+                errMsg.includes('SESSION_EXPIRED') ||
+                errMsg.includes('INVALID_SESSION');
+            if (isPermanent) {
+                await this.sessionStore.clear();
+            }
             this.emit('resume_failed', {
                 error: err instanceof Error ? err : new Error(String(err)),
                 sessionId: session.relaySessionId,
@@ -354,7 +368,7 @@ export class RelayClient extends EventEmitter {
             if (this._paired && this._needsRekey && this.pairingCode && this.transport) {
                 // Server requested re-ECDH (e.g. AGENT_RESTARTED) —
                 // cancel any in-flight pairing and start fresh handshake.
-                // Invalidate old crypto state to prevent sending with stale keys.
+                // Invalidate old crypto state: agent has new keys, old ones are useless.
                 this._needsRekey = false;
                 this._activePairing?.abort();
                 this.sessionKey = null;
@@ -363,9 +377,30 @@ export class RelayClient extends EventEmitter {
                 const pairing = new PairingProtocol(this.transport);
                 this._activePairing = pairing;
                 pairing.pairAsClient(this.pairingCode)
-                    .then(result => this.onPaired(result, 'resumed'))
+                    .then(result => {
+                    this._rekeyRetryCount = 0; // Reset on success
+                    this.onPaired(result, 'resumed');
+                })
                     .catch(err => {
                     this._activePairing = null;
+                    this._rekeyRetryCount++;
+                    // Circuit breaker: stop after 5 consecutive re-key failures
+                    if (this._rekeyRetryCount >= 5) {
+                        this._needsRekey = false;
+                        this.emit('error', new Error(`Re-key failed after ${this._rekeyRetryCount} retries, giving up`));
+                        // Force transport to close and reconnect from scratch
+                        this.transport?.disconnect();
+                        return;
+                    }
+                    // Re-key failed — set _needsRekey back to true for retry.
+                    this._needsRekey = true;
+                    // If WS is still OPEN (pairing failed at protocol level, not transport level),
+                    // _needsRekey won't be consumed until next on('open').
+                    // Force a reconnect to trigger a fresh on('open').
+                    if (this.transport?.isConnected) {
+                        this.transport.disconnect();
+                        this.transport.restart();
+                    }
                     this.emit('error', err);
                 });
             }

package/dist/chat/ChatHandler.d.ts

@@ -1,28 +1,164 @@
 /**
- * ChatHandler — Routes chat messages to local OpenClaw via OpenAI-compatible API.
+ * ChatHandler — Routes chat messages to local OpenClaw via WebSocket Gateway.
  *
- * Receives decrypted messages from desktop, forwards to localhost:18789,
- * returns AI responses back through the relay.
+ * Receives decrypted messages from desktop, forwards to OpenClaw WS gateway
+ * (localhost:18789) using Ed25519 challenge-response auth, returns AI responses
+ * back through the relay.
+ *
+ * Zero-config: uses OpenClaw's silent local pairing — no user settings needed.
+ *
+ * **Async model:**
+ * OpenClaw chat is fully async — chat.send RPC returns immediately with
+ * { status:"started", runId:"..." }. AI responses arrive as streaming 'chat' events
+ * sometime later (could be seconds or minutes for complex tasks).
+ *
+ * This handler:
+ *   1. Registers a persistent sendBack callback (set once when desktop connects)
+ *   2. Listens for ALL chat events from OpenClaw, forwarding to desktop continuously
+ *   3. Tracks run IDs so we can correlate and send typing indicators
  *
  * Message types handled:
- *   - system_prompt: stored as conversation context
- *   - chat: forwarded to OpenClaw /v1/chat/completions
+ *   - chat:          forwarded to OpenClaw via chat.send RPC
+ *   - system_prompt:  stored as conversation context (future use)
+ *   - chat_abort:     cancels current AI generation
+ *
+ * Response types sent back to desktop:
+ *   - chat_delta:     streaming text fragment (incremental)
+ *   - chat_reply:     final complete response
+ *   - chat_typing:    typing indicator
+ *   - chat_error:     error message
  */
+import { OpenClawWsClient } from '../gateway/OpenClawWsClient.js';
 export interface ChatMessage {
     type: string;
     [key: string]: unknown;
 }
+export interface ChatHandlerConfig {
+    /** OpenClaw gateway port. Default: 18789 */
+    port?: number;
+    /** OpenClaw gateway host. Default: '127.0.0.1' */
+    host?: string;
+    /** State directory for device identity. Default: ~/.echoclaw/ */
+    stateDir?: string;
+    /** Session key for OpenClaw conversations. Default: 'main' */
+    sessionKey?: string;
+    /** Request timeout in ms. Default: 30_000 (30s for RPC only, events are async) */
+    requestTimeoutMs?: number;
+}
 export declare class ChatHandler {
-    private history;
-    private readonly openClawUrl;
-    constructor(openClawPort?: number);
+    private readonly wsClient;
+    private readonly sessionKey;
+    private readonly requestTimeoutMs;
+    private _connecting;
+    private _connected;
+    /**
+     * Persistent callback to send messages back to desktop.
+     * Set via setSendBack() when desktop connects to relay.
+     * Cleared when desktop disconnects.
+     */
+    private _sendBack;
+    /**
+     * Active chat runs — tracks ongoing AI responses.
+     * Key = runId, Value = run state.
+     */
+    private _activeRuns;
+    /** Periodic cleanup timer for stale runs. */
+    private _runCleanupTimer;
+    /** Pending agent lifecycle cleanup timers (for proper cleanup on disconnect). */
+    private _lifecycleTimers;
+    /** Buffered messages when _sendBack is null (relay disconnected but OpenClaw still active). */
+    private _messageBuffer;
+    constructor(config?: ChatHandlerConfig);
+    /** Expose the underlying WS client for event listening. */
+    get client(): OpenClawWsClient;
+    /** Whether the OpenClaw gateway connection is active. */
+    get isConnected(): boolean;
+    /**
+     * Set the persistent callback for sending messages back to desktop.
+     * Call this when the desktop-side relay connection is established.
+     */
+    setSendBack(fn: (msg: ChatMessage) => Promise<void>): void;
+    /**
+     * Clear the send-back callback (call when desktop disconnects).
+     */
+    clearSendBack(): void;
+    /**
+     * Connect to OpenClaw gateway. Non-blocking if already connected/connecting.
+     * Throws on failure (caller should handle gracefully).
+     */
+    connect(): Promise<void>;
     /**
      * Handle an incoming message from desktop.
-     * Returns an array of response messages to send back.
+     * sendBack is used for immediate error responses only;
+     * streaming responses use the persistent _sendBack callback.
+     */
+    handle(payload: any, sendBack: (msg: ChatMessage) => Promise<void>): Promise<void>;
+    /** Disconnect from OpenClaw gateway. */
+    disconnect(): void;
+    /**
+     * Clear pending run state (call on relay disconnect).
+     * Does NOT clear sendBack or message buffer — OpenClaw may still be processing
+     * and we want to buffer responses for when relay reconnects.
      */
-    handle(payload: any): Promise<ChatMessage[]>;
-    /** Clear conversation history (call on disconnect/reconnect). */
     clearHistory(): void;
-    private forwardToOpenClaw;
-    private trimHistory;
+    private _handleChat;
+    private _handleChatAbort;
+    private _handleChatHistory;
+    /**
+     * Handle streaming chat events from OpenClaw gateway.
+     *
+     * Event structure (verified from OpenClaw source):
+     * {
+     *   runId: string,
+     *   sessionKey: string,
+     *   seq: number,
+     *   state: "delta" | "final",
+     *   message?: {
+     *     role: "assistant",
+     *     content: [{ type: "text", text: string }],
+     *     timestamp: number
+     *   }
+     * }
+     *
+     * IMPORTANT: delta events contain ACCUMULATED text (full text so far),
+     * NOT incremental deltas. We compute the incremental part ourselves.
+     */
+    private _handleChatEvent;
+    /**
+     * Handle side result events — "btw" async task completions.
+     * These arrive when OpenClaw finishes a background task and wants
+     * to proactively inform the user.
+     */
+    private _handleSideResult;
+    /**
+     * Handle agent lifecycle events.
+     * - stream: "lifecycle", data.phase: "start" → typing indicator ON
+     * - stream: "lifecycle", data.phase: "end" | "error" → typing indicator OFF (if no chat final)
+     * - stream: "assistant" → streaming text from agent (also comes as 'chat' delta)
+     */
+    private _handleAgentEvent;
+    /** Cancel all pending agent lifecycle cleanup timers. */
+    private _clearLifecycleTimers;
+    /** Start periodic cleanup of stale runs (prevents memory leak). */
+    private _startRunCleanup;
+    private _stopRunCleanup;
+    /**
+     * Extract text from OpenClaw message format.
+     * message.content is an array of content blocks; we concatenate text blocks.
+     */
+    private _extractText;
+    /** Send a message back to desktop via the persistent callback. Buffers if disconnected. */
+    private _send;
+    /** Sequential send queue to prevent message reordering between flush and real-time messages. */
+    private _sendQueue;
+    private _enqueueSend;
+    /** Flush buffered messages to desktop after relay reconnects (sequential, preserves order). */
+    private _flushMessageBuffer;
+    /**
+     * Send a message via a captured sendBack reference.
+     * Used to avoid race conditions: the callback is captured synchronously
+     * at the top of event handlers, so clearSendBack() at an await boundary
+     * won't null it between the check and the call.
+     */
+    private _sendVia;
 }