echoclaw-relay-agent 0.8.1 → 0.9.3

package/dist/RelayAgent.d.ts

@@ -29,6 +29,8 @@ export declare class RelayAgent extends EventEmitter {
     private _dataHandler;
     private _stopped;
     private _starting;
+    private _paired;
+    private _activePairing;
     private readonly config;
     private readonly subscribers;
     private gatewayManager;

package/dist/RelayAgent.js

@@ -91,6 +91,18 @@ export class RelayAgent extends EventEmitter {
             writable: true,
             value: false
         });
+        Object.defineProperty(this, "_paired", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "_activePairing", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         Object.defineProperty(this, "config", {
             enumerable: true,
             configurable: true,
@@ -138,6 +150,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;
         }
@@ -194,11 +207,18 @@ export class RelayAgent extends EventEmitter {
     /** Gracefully stop the agent. */
     async stop() {
         this._stopped = true;
+        this._paired = false;
+        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 ────────────────────────────────────────────────
@@ -268,6 +288,13 @@ export class RelayAgent extends EventEmitter {
         this.sessionId = result.sessionId;
         this.pairingCode = result.pairingCode;
         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,
@@ -355,18 +382,42 @@ export class RelayAgent extends EventEmitter {
             this.emit('error', err);
         });
         this.transport.on('open', () => {
-            if (this.sessionKey) {
-                this.setStatus('connected');
-                this.emit('connected');
-                // V2: Reattach gateway callbacks after reconnect
-                if (this.gatewayManager) {
-                    this.gatewayManager.onReconnected(async (r) => {
-                        try {
-                            await this.send(r);
-                        }
-                        catch { /* send may fail */ }
-                    });
-                }
+            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 but KEEP old crypto state
+                // so data handler can still decrypt until re-key succeeds.
+                this._activePairing?.abort();
+                // 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;
+                // 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.onPaired(result);
+                    // V2: Reattach gateway callbacks after reconnect
+                    if (this.gatewayManager) {
+                        this.gatewayManager.onReconnected(async (r) => {
+                            try {
+                                await this.send(r);
+                            }
+                            catch { /* send may fail */ }
+                        });
+                    }
+                })
+                    .catch(err => {
+                    this._activePairing = null;
+                    // 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');
+                    }
+                    this.emit('error', err);
+                });
             }
         });
     }

package/dist/RelayClient.d.ts

@@ -34,6 +34,9 @@ export declare class RelayClient extends EventEmitter {
     private _status;
     private _connecting;
     private _stopped;
+    private _paired;
+    private _needsRekey;
+    private _activePairing;
     private readonly config;
     private readonly sessionStore;
     private readonly subscribers;

package/dist/RelayClient.js

@@ -79,6 +79,24 @@ export class RelayClient extends EventEmitter {
             writable: true,
             value: false
         });
+        Object.defineProperty(this, "_paired", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "_needsRekey", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "_activePairing", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         Object.defineProperty(this, "config", {
             enumerable: true,
             configurable: true,
@@ -178,6 +196,10 @@ export class RelayClient extends EventEmitter {
     /** Disconnect from the relay. */
     async disconnect() {
         this._stopped = true;
+        this._paired = false;
+        this._needsRekey = false;
+        this._activePairing?.abort();
+        this._activePairing = null;
         this.transport?.disconnect();
         this.transport = null;
         this.sessionKey = null;
@@ -231,13 +253,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,
@@ -250,6 +280,8 @@ export class RelayClient extends EventEmitter {
         this.sessionId = result.sessionId;
         this.pairingCode = result.pairingCode;
         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 /client/connect (which would create a new session)
         if (this.transport) {
@@ -319,8 +351,37 @@ export class RelayClient extends EventEmitter {
         this.transport.on('error', (err) => {
             this.emit('error', err);
         });
+        // Listen for server CLOSE messages (e.g. AGENT_RESTARTED) to know re-ECDH is needed.
+        // Without this, normal network drops would unnecessarily trigger re-ECDH.
+        this.transport.on('message', (msg) => {
+            if (msg.type === 'CLOSE' && msg.sender_role === 'server') {
+                this._needsRekey = true;
+            }
+        });
         this.transport.on('open', () => {
-            if (this.sessionKey) {
+            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: agent has new keys, old ones are useless.
+                this._needsRekey = false;
+                this._activePairing?.abort();
+                this.sessionKey = null;
+                this.frameCrypto = null;
+                this.setStatus('connecting');
+                const pairing = new PairingProtocol(this.transport);
+                this._activePairing = pairing;
+                pairing.pairAsClient(this.pairingCode)
+                    .then(result => this.onPaired(result, 'resumed'))
+                    .catch(err => {
+                    this._activePairing = null;
+                    // Re-key failed — set _needsRekey back to true so next reconnect retries.
+                    // Without this, the client gets stuck with no crypto and no recovery path.
+                    this._needsRekey = true;
+                    this.emit('error', err);
+                });
+            }
+            else if (this.sessionKey) {
+                // Normal reconnect (network drop) — old session key still valid
                 this.setStatus('connected');
                 this.emit('connected');
             }

package/dist/chat/ChatHandler.d.ts

@@ -1,28 +1,161 @@
 /**
- * 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;
+    /** Flush buffered messages to desktop after relay reconnects. */
+    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;
 }