echoclaw-relay-agent 0.19.0 → 0.19.2

package/dist/chat/ChatHandler.d.ts

@@ -216,6 +216,12 @@ export declare class ChatHandler {
      * message.content is an array of content blocks; we concatenate text blocks.
      */
     private _extractText;
+    /**
+     * Extract media content blocks (images + files) from OpenClaw message format.
+     * Gateway returns content blocks with type "image" or "input_file"/"file".
+     */
+    private static readonly MAX_MEDIA_BASE64_LEN;
+    private _extractMedia;
     /** 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. */

package/dist/chat/ChatHandler.js

@@ -586,6 +586,18 @@ export class ChatHandler {
                     final: true,
                 }).catch(() => { });
             }
+            // Send media blocks (images, files) if present in the final message
+            const mediaBlocks = this._extractMedia(eventPayload?.message);
+            for (const media of mediaBlocks) {
+                this._sendVia(sendBack, {
+                    type: 'chat_file',
+                    fileType: media.type,
+                    data: media.data,
+                    mimeType: media.mimeType,
+                    fileName: media.fileName,
+                    runId,
+                }).catch(() => { });
+            }
             // Clean up run tracking — move own runs to recent to prevent false external classification
             if (runId) {
                 const completedRun = this._activeRuns.get(runId);
@@ -635,6 +647,18 @@ export class ChatHandler {
                 final: true,
             }).catch(() => { });
         }
+        // Forward media blocks from side results
+        const mediaBlocks = this._extractMedia(payload?.message);
+        for (const media of mediaBlocks) {
+            this._sendVia(sendBack, {
+                type: 'chat_file',
+                fileType: media.type,
+                data: media.data,
+                mimeType: media.mimeType,
+                fileName: media.fileName,
+                runId: payload?.runId,
+            }).catch(() => { });
+        }
     }
     /**
      * Handle agent events — lifecycle, tool use, compaction, model fallback.
@@ -940,6 +964,39 @@ export class ChatHandler {
             .map((block) => block.text)
             .join('');
     }
+    _extractMedia(message) {
+        if (!message?.content || !Array.isArray(message.content))
+            return [];
+        const media = [];
+        const maxLen = ChatHandler.MAX_MEDIA_BASE64_LEN;
+        for (const block of message.content) {
+            if (!block || typeof block !== 'object')
+                continue;
+            // Image blocks: { type: "image", source: { type: "base64", media_type, data } }
+            if (block.type === 'image' && block.source?.data && block.source.data.length > 0) {
+                if (block.source.data.length <= maxLen) {
+                    media.push({
+                        type: 'image',
+                        data: block.source.data,
+                        mimeType: block.source.media_type || 'image/png',
+                        fileName: block.fileName,
+                    });
+                }
+            }
+            else if ((block.type === 'input_file' || block.type === 'file') && block.source?.data && block.source.data.length > 0) {
+                // File blocks: { type: "input_file" | "file", source: { type: "base64", media_type, data, filename } }
+                if (block.source.data.length <= maxLen) {
+                    media.push({
+                        type: 'file',
+                        data: block.source.data,
+                        mimeType: block.source.media_type || 'application/octet-stream',
+                        fileName: block.source.filename || block.fileName,
+                    });
+                }
+            }
+        }
+        return media;
+    }
     /** Send a message back to desktop via the persistent callback. Buffers if disconnected. */
     async _send(msg) {
         if (this._sendBack) {
@@ -995,3 +1052,14 @@ export class ChatHandler {
         await fn(msg);
     }
 }
+/**
+ * Extract media content blocks (images + files) from OpenClaw message format.
+ * Gateway returns content blocks with type "image" or "input_file"/"file".
+ */
+// 10MB base64 limit (~7.5MB raw) — prevents OOM on huge files
+Object.defineProperty(ChatHandler, "MAX_MEDIA_BASE64_LEN", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 10 * 1024 * 1024
+});

package/dist/index.d.ts

@@ -27,3 +27,5 @@ export { GatewayWatchdog } from './gateway/index.js';
 export { OpenClawWsClient } from './gateway/index.js';
 export type { GatewayConfig, BridgeEndpoint, BridgeStatus, DeviceInfo, OpenClawWsClientConfig, } from './gateway/index.js';
 export { DEFAULT_GATEWAY_CONFIG } from './gateway/index.js';
+export { LocalAgent, type LocalAgentConfig, type LocalAgentStatus } from './local/index.js';
+export { detectLocalOpenClaw, type LocalOpenClawInfo } from './local/index.js';

package/dist/index.js

@@ -30,3 +30,6 @@ export { GatewayBridge } from './gateway/index.js';
 export { GatewayWatchdog } from './gateway/index.js';
 export { OpenClawWsClient } from './gateway/index.js';
 export { DEFAULT_GATEWAY_CONFIG } from './gateway/index.js';
+// ── Local Connection ────────────────────────────────────────
+export { LocalAgent } from './local/index.js';
+export { detectLocalOpenClaw } from './local/index.js';

package/dist/local/LocalAgent.d.ts

@@ -0,0 +1,51 @@
+/**
+ * LocalAgent — Direct local connection to OpenClaw Gateway.
+ *
+ * Used when desktop and OpenClaw are on the same machine.
+ * Provides the SAME interface as RelayAgent — desktop doesn't know the difference.
+ *
+ * Architecture:
+ *   Desktop ← EventEmitter → LocalAgent → ChatHandler/InstallHandler → OpenClaw Gateway (localhost)
+ *
+ * No relay server, no encryption (localhost), no pairing needed.
+ * Reuses ChatHandler and InstallHandler via setSendBack() injection.
+ */
+import { EventEmitter } from 'node:events';
+export interface LocalAgentConfig {
+    /** OpenClaw Gateway port. Default: 18789 */
+    gatewayPort?: number;
+    /** OpenClaw Gateway host. Default: '127.0.0.1' */
+    gatewayHost?: string;
+    /** Gateway auth token (from ~/.openclaw/openclaw.json) */
+    gatewayToken: string;
+    /** Session key. Default: 'main' */
+    sessionKey?: string;
+}
+export type LocalAgentStatus = 'disconnected' | 'connecting' | 'connected';
+export declare class LocalAgent extends EventEmitter {
+    private readonly config;
+    private chatHandler;
+    private installHandler;
+    private _status;
+    private _stopped;
+    private _reconnectTimer;
+    private _reconnectAttempt;
+    constructor(config: LocalAgentConfig);
+    get status(): LocalAgentStatus;
+    get connectionMode(): 'local';
+    /**
+     * Connect to local OpenClaw Gateway.
+     */
+    connect(): Promise<void>;
+    /**
+     * Send a message to OpenClaw (from desktop).
+     * Routes to appropriate handler based on message type.
+     */
+    send(payload: any): Promise<void>;
+    /**
+     * Gracefully disconnect.
+     */
+    disconnect(): Promise<void>;
+    private setStatus;
+    private _scheduleReconnect;
+}

package/dist/local/LocalAgent.js

@@ -0,0 +1,200 @@
+/**
+ * LocalAgent — Direct local connection to OpenClaw Gateway.
+ *
+ * Used when desktop and OpenClaw are on the same machine.
+ * Provides the SAME interface as RelayAgent — desktop doesn't know the difference.
+ *
+ * Architecture:
+ *   Desktop ← EventEmitter → LocalAgent → ChatHandler/InstallHandler → OpenClaw Gateway (localhost)
+ *
+ * No relay server, no encryption (localhost), no pairing needed.
+ * Reuses ChatHandler and InstallHandler via setSendBack() injection.
+ */
+import { EventEmitter } from 'node:events';
+import { ChatHandler } from '../chat/ChatHandler.js';
+import { InstallHandler } from '../install/InstallHandler.js';
+export class LocalAgent extends EventEmitter {
+    constructor(config) {
+        super();
+        Object.defineProperty(this, "config", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "chatHandler", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "installHandler", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "_status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'disconnected'
+        });
+        Object.defineProperty(this, "_stopped", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "_reconnectTimer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "_reconnectAttempt", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        this.config = config;
+    }
+    get status() {
+        return this._status;
+    }
+    get connectionMode() {
+        return 'local';
+    }
+    /**
+     * Connect to local OpenClaw Gateway.
+     */
+    async connect() {
+        this._stopped = false;
+        this.setStatus('connecting');
+        try {
+            const port = this.config.gatewayPort ?? 18789;
+            const host = this.config.gatewayHost ?? '127.0.0.1';
+            const sessionKey = this.config.sessionKey ?? 'main';
+            // Create ChatHandler — it manages the WS connection to Gateway
+            this.chatHandler = new ChatHandler({
+                port,
+                host,
+                gatewayToken: this.config.gatewayToken,
+                sessionKey,
+            });
+            // Inject sendBack: messages go directly to desktop via EventEmitter
+            this.chatHandler.setSendBack(async (msg) => {
+                this.emit('message', msg);
+            });
+            // Create InstallHandler — needs wsClient + chatHandler
+            this.installHandler = new InstallHandler(this.chatHandler.client, this.chatHandler, { sessionKey });
+            this.installHandler.setSendBack(async (msg) => {
+                this.emit('message', msg);
+            });
+            // Listen for Gateway connection events
+            this.chatHandler.client.on('connected', () => {
+                this._reconnectAttempt = 0;
+                this.setStatus('connected');
+                this.emit('connected');
+            });
+            this.chatHandler.client.on('disconnected', () => {
+                if (this._status === 'connected') {
+                    this.setStatus('disconnected');
+                    this.emit('disconnected');
+                }
+                if (!this._stopped) {
+                    this._scheduleReconnect();
+                }
+            });
+            this.chatHandler.client.on('error', (err) => {
+                this.emit('error', err);
+            });
+            // Connect to Gateway
+            await this.chatHandler.connect();
+        }
+        catch (err) {
+            this.setStatus('disconnected');
+            if (!this._stopped) {
+                this._scheduleReconnect();
+            }
+            throw err;
+        }
+    }
+    /**
+     * Send a message to OpenClaw (from desktop).
+     * Routes to appropriate handler based on message type.
+     */
+    async send(payload) {
+        if (!payload?.type)
+            return;
+        const type = payload.type;
+        // Chat messages
+        if (type === 'chat' || type === 'system_prompt') {
+            if (this.chatHandler) {
+                await this.chatHandler.handle(payload, async (msg) => {
+                    this.emit('message', msg);
+                });
+            }
+            return;
+        }
+        // Install messages
+        if (type === 'install_request') {
+            if (this.installHandler) {
+                await this.installHandler.handleInstallRequest(payload);
+            }
+            return;
+        }
+        if (type === 'install_abort') {
+            if (this.installHandler) {
+                await this.installHandler.handleAbort(payload.requestId);
+            }
+            return;
+        }
+        // Unknown message type — ignore (forward compat)
+    }
+    /**
+     * Gracefully disconnect.
+     */
+    async disconnect() {
+        this._stopped = true;
+        if (this._reconnectTimer) {
+            clearTimeout(this._reconnectTimer);
+            this._reconnectTimer = null;
+        }
+        if (this.chatHandler) {
+            this.chatHandler.clearSendBack();
+            this.chatHandler.disconnect();
+            this.chatHandler = null;
+        }
+        if (this.installHandler) {
+            this.installHandler.clearSendBack();
+            this.installHandler = null;
+        }
+        this.setStatus('disconnected');
+    }
+    // ── Private ─────────────────────────────────────────────
+    setStatus(status) {
+        if (this._status !== status) {
+            this._status = status;
+            this.emit('status', status);
+        }
+    }
+    _scheduleReconnect() {
+        if (this._stopped || this._reconnectTimer)
+            return;
+        this._reconnectAttempt++;
+        const delay = Math.min(3000 * Math.pow(2, this._reconnectAttempt - 1), 60000);
+        this._reconnectTimer = setTimeout(async () => {
+            this._reconnectTimer = null;
+            if (this._stopped)
+                return;
+            try {
+                await this.connect();
+            }
+            catch {
+                // connect() failed, reconnect scheduled by disconnected event
+            }
+        }, delay);
+    }
+}

package/dist/local/LocalDetector.d.ts

@@ -0,0 +1,19 @@
+/**
+ * LocalDetector — Detect local OpenClaw installation.
+ *
+ * Checks two conditions (both must pass):
+ *   1. OpenClaw Gateway is reachable at localhost:<port>
+ *   2. Gateway auth token is readable from ~/.openclaw/openclaw.json
+ *
+ * If both pass → local mode. Otherwise → relay mode.
+ */
+export interface LocalOpenClawInfo {
+    gatewayPort: number;
+    gatewayToken: string;
+    configPath: string;
+}
+/**
+ * Detect if OpenClaw is installed and running locally.
+ * Returns config info if available, null otherwise.
+ */
+export declare function detectLocalOpenClaw(configPath?: string, port?: number): Promise<LocalOpenClawInfo | null>;

package/dist/local/LocalDetector.js

@@ -0,0 +1,77 @@
+/**
+ * LocalDetector — Detect local OpenClaw installation.
+ *
+ * Checks two conditions (both must pass):
+ *   1. OpenClaw Gateway is reachable at localhost:<port>
+ *   2. Gateway auth token is readable from ~/.openclaw/openclaw.json
+ *
+ * If both pass → local mode. Otherwise → relay mode.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const DEFAULT_GATEWAY_PORT = 18789;
+const OPENCLAW_CONFIG_PATH = join(homedir(), '.openclaw', 'openclaw.json');
+const DETECT_TIMEOUT_MS = 2000;
+/**
+ * Detect if OpenClaw is installed and running locally.
+ * Returns config info if available, null otherwise.
+ */
+export async function detectLocalOpenClaw(configPath = OPENCLAW_CONFIG_PATH, port = DEFAULT_GATEWAY_PORT) {
+    try {
+        // Step 1: Read gateway token from config file
+        const token = await readGatewayToken(configPath);
+        if (!token)
+            return null;
+        // Step 2: Check if Gateway is reachable
+        const reachable = await checkGatewayHealth(port, token);
+        if (!reachable)
+            return null;
+        return {
+            gatewayPort: port,
+            gatewayToken: token,
+            configPath,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read gateway auth token from openclaw.json.
+ * Returns null if file doesn't exist or token not found.
+ */
+async function readGatewayToken(configPath) {
+    try {
+        const raw = await readFile(configPath, 'utf-8');
+        const config = JSON.parse(raw);
+        // Token location: gateway.auth.token or gateway.token
+        const token = config?.gateway?.auth?.token ||
+            config?.gateway?.token ||
+            null;
+        if (!token || typeof token !== 'string')
+            return null;
+        return token;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ping Gateway health endpoint to verify it's running.
+ */
+async function checkGatewayHealth(port, token) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), DETECT_TIMEOUT_MS);
+        const res = await fetch(`http://127.0.0.1:${port}/v1/models`, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/local/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Local connection module — public API.
+ */
+export { LocalAgent, type LocalAgentConfig, type LocalAgentStatus } from './LocalAgent.js';
+export { detectLocalOpenClaw, type LocalOpenClawInfo } from './LocalDetector.js';

package/dist/local/index.js

@@ -0,0 +1,5 @@
+/**
+ * Local connection module — public API.
+ */
+export { LocalAgent } from './LocalAgent.js';
+export { detectLocalOpenClaw } from './LocalDetector.js';

package/package.json

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