echoclaw-relay-agent 0.9.6 → 0.9.9

package/dist/RelayAgent.d.ts

@@ -35,6 +35,15 @@ export declare class RelayAgent extends EventEmitter {
     private readonly config;
     private readonly subscribers;
     private gatewayManager;
+    private _rekeyListener;
+    /** Ephemeral keypair generated on transport reconnect for proactive HELLO.
+     *  Reused by the passive re-key listener to avoid glare (both sides generate
+     *  different keys → ECDH mismatch). Cleared after successful re-key. */
+    private _proactiveKeyPair;
+    /** Guard against concurrent re-key attempts. If two desktop HELLOs arrive
+     *  in rapid succession, the second must wait — otherwise both enter the async
+     *  handler, generate different keypairs, and cause ECDH mismatch. */
+    private _rekeyInFlight;
     constructor(config: RelayAgentConfig);
     /** Current connection status. */
     get status(): ClientStatus;
@@ -59,5 +68,11 @@ export declare class RelayAgent extends EventEmitter {
     private onPaired;
     private setupDataHandler;
     private setupTransportEvents;
+    /**
+     * Install a persistent listener that responds to desktop HELLO messages
+     * with a fresh ECDH handshake. This allows re-keying at any time,
+     * not just on transport reconnect.
+     */
+    private installRekeyListener;
     private setStatus;
 }

package/dist/RelayAgent.js

@@ -16,7 +16,7 @@
  *   await agent.send({ type: 'greeting', text: 'Hello from OpenClaw' });
  */
 import { EventEmitter } from 'node:events';
-// @echoclaw/crypto used via FrameCrypto and PairingProtocol
+import { generateKeyPair, completeHandshake, toBase64, fromBase64, } from 'echoclaw-crypto';
 import { RelayTransport } from './relay/RelayTransport.js';
 import { PairingProtocol } from './relay/PairingProtocol.js';
 import { SessionStore } from './relay/SessionStore.js';
@@ -127,6 +127,30 @@ export class RelayAgent extends EventEmitter {
             writable: true,
             value: null
         });
+        Object.defineProperty(this, "_rekeyListener", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /** Ephemeral keypair generated on transport reconnect for proactive HELLO.
+         *  Reused by the passive re-key listener to avoid glare (both sides generate
+         *  different keys → ECDH mismatch). Cleared after successful re-key. */
+        Object.defineProperty(this, "_proactiveKeyPair", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /** Guard against concurrent re-key attempts. If two desktop HELLOs arrive
+         *  in rapid succession, the second must wait — otherwise both enter the async
+         *  handler, generate different keypairs, and cause ECDH mismatch. */
+        Object.defineProperty(this, "_rekeyInFlight", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
         this.config = config;
         this.sessionStore = new SessionStore(config.sessionPath);
         // V2: Create gateway manager if enabled
@@ -225,6 +249,9 @@ export class RelayAgent extends EventEmitter {
         this.sessionKey = null;
         this.frameCrypto = null;
         this._dataHandler = null;
+        this._rekeyListener = null;
+        this._proactiveKeyPair = null;
+        this._rekeyInFlight = false;
         this.setStatus('disconnected');
     }
     // ── Private ────────────────────────────────────────────────
@@ -267,7 +294,10 @@ export class RelayAgent extends EventEmitter {
         this.pairing = new PairingProtocol(this.transport);
         this.transport.connect();
         try {
-            const result = await this.pairing.pairAsAgent();
+            // Pass saved pairing code so HKDF info matches the desktop side.
+            // Without this, agent derives with undefined while desktop derives
+            // with the saved code → AES-GCM key mismatch → decrypt failure.
+            const result = await this.pairing.pairAsAgent(session.pairingCode || undefined);
             await this.onPaired(result);
         }
         catch (err) {
@@ -308,6 +338,10 @@ export class RelayAgent extends EventEmitter {
             lastConnected: new Date().toISOString(),
         });
         this.setupDataHandler();
+        // Re-install re-key listener so future desktop HELLOs are handled.
+        // Without this, after a re-key, the listener references the old transport
+        // message handler and subsequent re-keys silently fail (Reviewer #3 finding).
+        this.installRekeyListener();
         this.setStatus('connected');
         this.emit('paired', {
             pairingCode: result.pairingCode,
@@ -387,63 +421,136 @@ export class RelayAgent extends EventEmitter {
         this.transport.on('error', (err) => {
             this.emit('error', err);
         });
-        this.transport.on('open', () => {
-            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._rekeyRetryCount = 0; // Reset on success
-                    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;
-                    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.on('open', async () => {
+            if (!this.transport || !this._paired || !this.sessionKey)
+                return;
+            // Transport reconnected after a disconnect.
+            // Don't emit 'connected' yet — the old sessionKey is stale because
+            // desktop will re-key. Emitting 'connected' would let consumers call
+            // send() with the old key, causing decrypt failures on the other side.
+            // Status stays 'reconnecting' until onPaired() completes the re-key.
+            //
+            // Send a proactive HELLO so the desktop knows we're back and can
+            // start re-keying immediately — prevents deadlock where both sides
+            // wait for the other to initiate.
+            //
+            // The keypair is stored in _proactiveKeyPair so the passive re-key
+            // listener can reuse the SAME keypair when desktop responds with its
+            // own HELLO. ECDH is symmetric: ECDH(a, B) == ECDH(b, A), so both
+            // sides derive the same session key regardless of message ordering.
+            try {
+                this._proactiveKeyPair = await generateKeyPair();
+                this.transport.send(this.transport.buildMessage('HELLO', this.sessionId, 'agent', {
+                    pubkey: toBase64(this._proactiveKeyPair.publicKey),
+                }));
+            }
+            catch (err) {
+                // Non-fatal — passive listener still works as fallback
+                this._proactiveKeyPair = null;
+                this.emit('error', new Error(`Proactive HELLO failed: ${err instanceof Error ? err.message : err}`));
+            }
+            // Timeout: if desktop doesn't respond within 30s, clear stale keypair
+            // and force reconnect so we get a fresh attempt.
+            setTimeout(() => {
+                if (this._proactiveKeyPair) {
+                    this._proactiveKeyPair = null;
+                    // If still not re-keyed, force reconnect
+                    if (this._status === 'reconnecting' && this.transport) {
                         this.transport.disconnect();
-                        this.transport.restart();
                     }
-                    this.emit('error', err);
+                }
+            }, 30000);
+            // V2: Reattach gateway callbacks after reconnect
+            if (this.gatewayManager) {
+                this.gatewayManager.onReconnected(async (r) => {
+                    try {
+                        await this.send(r);
+                    }
+                    catch { /* send may fail */ }
                 });
             }
         });
+        // Passive re-key listener: always respond to desktop HELLO messages,
+        // even when already paired. This fixes the critical bug where:
+        //  - CLI→service transition: desktop reconnects, sends HELLO, but
+        //    agent has no active PairingProtocol to respond → timeout → circuit breaker.
+        //  - Desktop restart: resumeSession() sends HELLO, agent doesn't respond.
+        //
+        // The listener is persistent — it stays active for the lifetime of the transport.
+        // It only triggers when _paired=true AND no _activePairing is in-flight.
+        this.installRekeyListener();
+    }
+    /**
+     * Install a persistent listener that responds to desktop HELLO messages
+     * with a fresh ECDH handshake. This allows re-keying at any time,
+     * not just on transport reconnect.
+     */
+    installRekeyListener() {
+        if (!this.transport)
+            return;
+        // Remove previous listener to prevent accumulation
+        if (this._rekeyListener) {
+            this.transport.removeListener('message', this._rekeyListener);
+        }
+        this._rekeyListener = async (msg) => {
+            // Only respond to desktop HELLO with pubkey when:
+            // 1. We're already paired (initial pairing is handled by PairingProtocol)
+            // 2. No active PairingProtocol in-flight (avoid competing listeners)
+            // 3. Transport is still alive (null guard per Reviewer #3)
+            if (msg.type !== 'HELLO' ||
+                msg.sender_role !== 'desktop' ||
+                !msg.pubkey ||
+                !this._paired ||
+                this._activePairing ||
+                !this.transport ||
+                this._rekeyInFlight // Prevent concurrent re-key (Reviewer #1 P1)
+            ) {
+                return;
+            }
+            this._rekeyInFlight = true;
+            try {
+                // Reuse proactive keypair if available (sent during on('open')),
+                // otherwise generate a fresh one. This avoids "glare" — if both
+                // sides independently generate keypairs, the ECDH results won't
+                // match because each side would use a different agent pubkey.
+                let keyPair;
+                let alreadySentHello = false;
+                if (this._proactiveKeyPair) {
+                    keyPair = this._proactiveKeyPair;
+                    this._proactiveKeyPair = null; // Consume — single use
+                    alreadySentHello = true; // HELLO was already sent in on('open')
+                }
+                else {
+                    keyPair = await generateKeyPair();
+                }
+                // Only send HELLO if we haven't already (proactive path)
+                if (!alreadySentHello && this.transport) {
+                    this.transport.send(this.transport.buildMessage('HELLO', this.sessionId, 'agent', {
+                        pubkey: toBase64(keyPair.publicKey),
+                    }));
+                }
+                // Complete ECDH with desktop's public key
+                const theirPub = fromBase64(msg.pubkey);
+                const sessionKey = await completeHandshake(keyPair.privateKey, theirPub, this.pairingCode || undefined);
+                // Update crypto state
+                this._rekeyRetryCount = 0;
+                this._proactiveKeyPair = null; // Ensure cleanup
+                await this.onPaired({
+                    sessionKey,
+                    sessionId: msg.session_id || this.sessionId,
+                    pairingCode: this.pairingCode,
+                });
+                this.emit('rekeyed', { sessionId: this.sessionId });
+            }
+            catch (err) {
+                this._proactiveKeyPair = null; // Cleanup on error
+                this.emit('error', new Error(`Passive re-key failed: ${err instanceof Error ? err.message : err}`));
+            }
+            finally {
+                this._rekeyInFlight = false;
+            }
+        };
+        this.transport.on('message', this._rekeyListener);
     }
     setStatus(status) {
         if (this._status !== status) {

package/dist/cli.js

@@ -12,6 +12,7 @@
 import { RelayAgent } from './RelayAgent.js';
 import { getServiceManager } from './service/platform.js';
 import { ChatHandler } from './chat/ChatHandler.js';
+import { handleMemorySync } from './gateway/WorkspaceSync.js';
 const DEFAULT_RELAY = 'wss://relay.echoclaw.me';
 // ── ASCII Banners ───────────────────────────────────────────
 const RESET = '\x1b[0m';
@@ -366,7 +367,23 @@ async function runDaemon(relay, code, gateway, bridgePort) {
         const payloadType = payload?.type;
         const isChatMsg = payloadType === 'chat' || payloadType === 'system_prompt' ||
             payloadType === 'chat_abort' || payloadType === 'chat_history';
-        if (isChatMsg) {
+        if (payloadType === 'memory_sync') {
+            // Desktop sends guide content for OpenClaw workspace
+            console.log(`  [memory_sync] version=${payload.version}`);
+            try {
+                const ack = await handleMemorySync(payload);
+                console.log(`  [memory_sync] ${ack.status} (v${ack.version})`);
+                await agent.send(ack);
+            }
+            catch (err) {
+                console.error(`  [memory_sync] error: ${err.message}`);
+                try {
+                    await agent.send({ type: 'memory_sync_ack', version: payload.version, status: 'error', error: err.message });
+                }
+                catch { /* send may fail */ }
+            }
+        }
+        else if (isChatMsg) {
             console.log(`  [message] type=${payloadType}`);
             // Route chat-related messages to ChatHandler
             // sendBack callback is for immediate error responses; async events use persistent callback

package/dist/gateway/WorkspaceSync.d.ts

@@ -0,0 +1,28 @@
+/**
+ * WorkspaceSync — Write memory/guide files to OpenClaw workspace.
+ *
+ * Handles `memory_sync` messages from the desktop client:
+ *   1. Check version — skip if already written
+ *   2. Write MEMORY_SECTION.md, ECHOCLAW_DEV_GUIDE.md, CLAWAPP_SPEC.md
+ *   3. Update/append the EchoClaw section in MEMORY.md
+ *   4. Write version marker
+ *   5. Reply with ack
+ */
+export interface MemorySyncPayload {
+    type: 'memory_sync';
+    version: string;
+    memory_section: string;
+    dev_guide: string;
+    spec: string;
+}
+export interface MemorySyncAck {
+    type: 'memory_sync_ack';
+    version: string;
+    status: 'written' | 'skipped' | 'error';
+    error?: string;
+}
+/**
+ * Handle a memory_sync message: write guide files to OpenClaw workspace.
+ * Returns the ack payload to send back to the desktop.
+ */
+export declare function handleMemorySync(payload: MemorySyncPayload): Promise<MemorySyncAck>;

package/dist/gateway/WorkspaceSync.js

@@ -0,0 +1,90 @@
+/**
+ * WorkspaceSync — Write memory/guide files to OpenClaw workspace.
+ *
+ * Handles `memory_sync` messages from the desktop client:
+ *   1. Check version — skip if already written
+ *   2. Write MEMORY_SECTION.md, ECHOCLAW_DEV_GUIDE.md, CLAWAPP_SPEC.md
+ *   3. Update/append the EchoClaw section in MEMORY.md
+ *   4. Write version marker
+ *   5. Reply with ack
+ */
+import { readFile, writeFile, appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const WORKSPACE_DIR = join(homedir(), '.openclaw', 'workspace');
+const VERSION_FILE = '.echoclaw-guide-version';
+// Exact heading used in MEMORY.md for the EchoClaw section.
+const SECTION_HEADING = '## EchoClaw 应用平台';
+// Regex built from SECTION_HEADING to prevent constant/regex drift.
+// Handles both LF and CRLF line endings to avoid data loss on Windows.
+const SECTION_RE = new RegExp(SECTION_HEADING.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') +
+    '[\\s\\S]*?(?=\\r?\\n## |$)');
+// Mutex: prevent concurrent memory_sync from corrupting MEMORY.md
+let _syncInFlight = false;
+/**
+ * Handle a memory_sync message: write guide files to OpenClaw workspace.
+ * Returns the ack payload to send back to the desktop.
+ */
+export async function handleMemorySync(payload) {
+    // Input validation (P1 #3: prevent undefined fields from bricking state)
+    if (!payload.version || typeof payload.version !== 'string') {
+        return { type: 'memory_sync_ack', version: payload.version ?? '', status: 'error', error: 'missing version' };
+    }
+    if (typeof payload.memory_section !== 'string' ||
+        typeof payload.dev_guide !== 'string' ||
+        typeof payload.spec !== 'string') {
+        return { type: 'memory_sync_ack', version: payload.version, status: 'error', error: 'missing content fields' };
+    }
+    // Concurrency guard (P1 #6: prevent concurrent writes corrupting MEMORY.md)
+    if (_syncInFlight) {
+        return { type: 'memory_sync_ack', version: payload.version, status: 'skipped' };
+    }
+    _syncInFlight = true;
+    try {
+        return await doSync(payload);
+    }
+    finally {
+        _syncInFlight = false;
+    }
+}
+async function doSync(payload) {
+    const workspacePath = WORKSPACE_DIR;
+    try {
+        // Ensure workspace directory exists
+        await mkdir(workspacePath, { recursive: true });
+        const versionFilePath = join(workspacePath, VERSION_FILE);
+        // 1. Check existing version — skip if same
+        const existingVersion = await readFile(versionFilePath, 'utf-8').catch(() => '');
+        if (existingVersion.trim() === payload.version.trim()) {
+            return { type: 'memory_sync_ack', version: payload.version, status: 'skipped' };
+        }
+        // 2. Write individual guide files
+        await writeFile(join(workspacePath, 'MEMORY_SECTION.md'), payload.memory_section, 'utf-8');
+        await writeFile(join(workspacePath, 'ECHOCLAW_DEV_GUIDE.md'), payload.dev_guide, 'utf-8');
+        await writeFile(join(workspacePath, 'CLAWAPP_SPEC.md'), payload.spec, 'utf-8');
+        // 3. Update MEMORY.md — replace existing EchoClaw section or append
+        const memoryPath = join(workspacePath, 'MEMORY.md');
+        const memory = await readFile(memoryPath, 'utf-8').catch(() => '');
+        if (memory.includes(SECTION_HEADING)) {
+            // Replace existing section using SECTION_RE (handles CRLF).
+            // Use function form to prevent $& / $' / $` in content being interpreted.
+            const updated = memory.replace(SECTION_RE, () => payload.memory_section);
+            await writeFile(memoryPath, updated, 'utf-8');
+        }
+        else if (memory.length > 0) {
+            // Append to existing MEMORY.md with blank line separator
+            await appendFile(memoryPath, '\n\n' + payload.memory_section, 'utf-8');
+        }
+        else {
+            // Create new MEMORY.md
+            await writeFile(memoryPath, payload.memory_section, 'utf-8');
+        }
+        // 4. Write version marker (last — so partial failures re-trigger on next attempt)
+        await writeFile(versionFilePath, payload.version + '\n', 'utf-8');
+        return { type: 'memory_sync_ack', version: payload.version, status: 'written' };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { type: 'memory_sync_ack', version: payload.version, status: 'error', error: msg };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echoclaw-relay-agent",
-  "version": "0.9.6",
+  "version": "0.9.9",
   "description": "EchoClaw Relay Connection — E2E encrypted relay transport, pairing, and session management",
   "type": "module",
   "main": "./dist/index.js",