@earzbook/openclaw 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @earzbook/openclaw
+
+Sidecar daemon that bridges the Earzbook mobile app to a locally-running OpenClaw agent via a WebSocket relay.
+
+Long-running Node process, installed once on the user's machine by the Earzbook pair flow. Registered as a per-user service (launchd LaunchAgent on macOS, systemd `--user` unit on Linux) so it auto-starts on login and survives crashes.
+
+## Install (user-facing — runs from the Earzbook pair script)
+
+```bash
+npm install -g @earzbook/openclaw
+```
+
+The Earzbook app's "Connect OpenClaw" flow prints a `curl … | bash` one-liner that runs the npm install above, writes `~/.earzbook/sidecar.json`, drops the launchd plist / systemd unit, and starts the service. No manual setup required.
+
+## Usage
+
+```bash
+earzbook-openclaw --config ~/.earzbook/sidecar.json
+```
+
+Config file shape:
+
+```json
+{
+  "relayUrl": "wss://api.earzbook.app/openclaw/relay",
+  "deviceToken": "<JWT issued by Earzbook backend at pair time>",
+  "userId": "<Earzbook user id>",
+  "agentId": "main",
+  "versionEndpoint": "https://api.earzbook.app/openclaw/sidecar/version"
+}
+```
+
+## What it does
+
+1. Opens a WebSocket to the Earzbook relay with `role: "plugin"` and authenticates with the `deviceToken` JWT.
+2. On each inbound `user_message`, spawns `openclaw agent --agent <agentId> --message <text> --json` to get the local OpenClaw agent's reply.
+3. Sends the reply back as an `agent_reply` frame.
+4. Pings every 30s, reconnects with exponential backoff (3s → 5min cap), checks for updates on startup + every 24h.
+
+See the architecture plan in `/Users/earzbook/.claude/plans/users-earzbook-documents-github-recall-rippling-sphinx.md` for the full design.
+
+## Why not the OpenClaw channel plugin?
+
+We started with a channel plugin at [`../earzbook-plugin/`](../earzbook-plugin/). OpenClaw 2026.5.22 doesn't import external channel plugin entry modules in its gateway daemon — the plugin's `lifecycle.start` and `registerFull` hooks only fire in CLI invocations. The plugin code stays in the repo for when OpenClaw fixes that, or when we fork them.
+
+The sidecar lives alongside as a self-contained workaround. Same wire protocol as the plugin would have used.

package/dist/adapter.d.ts

@@ -0,0 +1,29 @@
+import WebSocket from "ws";
+import type { AdapterCallbacks, AgentReplyFrame } from "./types.js";
+export interface AdapterOptions {
+    relayUrl: string;
+    deviceToken: string;
+    sidecarVersion: string;
+    pingIntervalMs?: number;
+    reconnectBaseMs?: number;
+    reconnectMaxMs?: number;
+    /** Override for tests — defaults to global WebSocket constructor. */
+    socketFactory?: (url: string) => WebSocket;
+}
+export interface AdapterHandle {
+    /** Send an agent_reply frame. Resolves once buffered to the socket. */
+    sendAgentReply(frame: Omit<AgentReplyFrame, "type">): Promise<void>;
+    /** Current connection state — useful for status surfaces. */
+    state(): AdapterState;
+    /** Stop reconnecting and close the active socket. */
+    close(reason?: string): Promise<void>;
+}
+export type AdapterState = "idle" | "connecting" | "connected" | "reconnecting" | "closed";
+/**
+ * Create and start the Earzbook relay adapter. The adapter immediately
+ * attempts to connect; callbacks are invoked on connection / message /
+ * disconnect events. Reconnects are automatic with exponential backoff.
+ * Caller owns lifetime via the returned handle.
+ */
+export declare function createAdapter(options: AdapterOptions, callbacks: AdapterCallbacks): AdapterHandle;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAYA,OAAO,SAA2B,MAAM,IAAI,CAAC;AAC7C,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EAQhB,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;CAC5C;AAED,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,6DAA6D;IAC7D,KAAK,IAAI,YAAY,CAAC;IACtB,qDAAqD;IACrD,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,YAAY,GACZ,WAAW,GACX,cAAc,GACd,QAAQ,CAAC;AASb;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,gBAAgB,GAC1B,aAAa,CA6Vf"}

package/dist/adapter.js

@@ -0,0 +1,368 @@
+// WebSocket lifecycle adapter for the Earzbook sidecar.
+//
+// Owns: connect → hello/welcome handshake, inbound user_message dispatch,
+// outbound agent_reply send, ack tracking, periodic ping keepalive, and
+// exponential-backoff reconnect with resume(lastAckSeq) on every reattempt.
+//
+// This is a copy-adapt of openclaw/earzbook-plugin/src/adapter.ts. We keep
+// them as separate files so the plugin and sidecar can evolve independently
+// (e.g. the sidecar may want different reconnect behavior, different log
+// tagging, or extra hooks for the daemon's process lifecycle). Wire
+// protocol stays identical so the relay treats both paths interchangeably.
+import WebSocket from "ws";
+import { PROTOCOL_VERSION } from "./types.js";
+import { log, warn, errLog } from "./logging.js";
+const DEFAULT_PING_INTERVAL_MS = 30_000;
+const DEFAULT_RECONNECT_BASE_MS = 3_000;
+const DEFAULT_RECONNECT_MAX_MS = 300_000;
+const RECONNECT_MULTIPLIER = 2;
+const TAG = "[earzbook-sidecar:adapter]";
+/**
+ * Create and start the Earzbook relay adapter. The adapter immediately
+ * attempts to connect; callbacks are invoked on connection / message /
+ * disconnect events. Reconnects are automatic with exponential backoff.
+ * Caller owns lifetime via the returned handle.
+ */
+export function createAdapter(options, callbacks) {
+    const pingIntervalMs = options.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
+    const reconnectBaseMs = options.reconnectBaseMs ?? DEFAULT_RECONNECT_BASE_MS;
+    const reconnectMaxMs = options.reconnectMaxMs ?? DEFAULT_RECONNECT_MAX_MS;
+    const socketFactory = options.socketFactory ?? ((url) => new WebSocket(url));
+    let socket = null;
+    let state = "idle";
+    let lastAckSeq = 0;
+    let reconnectAttempt = 0;
+    let pingTimer = null;
+    let reconnectTimer = null;
+    let stopped = false;
+    const outboundQueue = [];
+    function transition(next) {
+        state = next;
+        log(TAG, "state =", next);
+    }
+    function clearTimers() {
+        if (pingTimer) {
+            clearInterval(pingTimer);
+            pingTimer = null;
+        }
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+    }
+    function nextReconnectDelay() {
+        // Exponential backoff with ±12.5% jitter to avoid thundering herd.
+        const exp = reconnectBaseMs * Math.pow(RECONNECT_MULTIPLIER, reconnectAttempt);
+        const capped = Math.min(exp, reconnectMaxMs);
+        const jitter = Math.random() * 0.25 * capped;
+        return Math.floor(capped - capped * 0.125 + jitter);
+    }
+    function scheduleReconnect(reason) {
+        if (stopped)
+            return;
+        transition("reconnecting");
+        const delay = nextReconnectDelay();
+        reconnectAttempt += 1;
+        log(TAG, `reconnect attempt ${reconnectAttempt} backoff=${Math.round(delay / 1000)}s reason=${reason}`);
+        reconnectTimer = setTimeout(connect, delay);
+    }
+    function sendRaw(frame) {
+        if (!socket || socket.readyState !== WebSocket.OPEN)
+            return false;
+        try {
+            socket.send(JSON.stringify(frame));
+            return true;
+        }
+        catch (e) {
+            warn(TAG, "send failed:", e);
+            return false;
+        }
+    }
+    function flushOutbound() {
+        if (!socket || socket.readyState !== WebSocket.OPEN)
+            return;
+        while (outboundQueue.length > 0) {
+            const frame = outboundQueue[0];
+            if (!sendRaw(frame))
+                break;
+            outboundQueue.shift();
+        }
+    }
+    function handleServerFrame(frame) {
+        switch (frame.type) {
+            case "welcome":
+                handleWelcome(frame);
+                break;
+            case "user_message":
+                void handleUserMessage(frame);
+                break;
+            case "list_sessions":
+                void handleListSessions(frame);
+                break;
+            case "delete_session":
+                void handleDeleteSession(frame);
+                break;
+            case "fetch_history":
+                void handleFetchHistory(frame);
+                break;
+            case "pong":
+                // No-op — we use ping for keepalive only, not RTT measurement here.
+                break;
+            case "error":
+                errLog(TAG, `server error code=${frame.code} fatal=${frame.fatal} msg=${frame.message}`);
+                if (frame.fatal) {
+                    stopped = true;
+                    clearTimers();
+                    socket?.close();
+                    callbacks.onDisconnected({ fatal: true, reason: `server:${frame.code}` });
+                }
+                break;
+        }
+    }
+    function handleWelcome(frame) {
+        log(TAG, `welcome ok userId=${frame.userId} lastAckSeq=${frame.lastAckSeq}`);
+        transition("connected");
+        reconnectAttempt = 0;
+        // Reconcile our local lastAckSeq with the server's authoritative number.
+        lastAckSeq = frame.lastAckSeq;
+        flushOutbound();
+        startPing();
+        callbacks.onConnected(frame);
+    }
+    async function handleUserMessage(frame) {
+        log(TAG, `inbound seq=${frame.seq} conv=${frame.conversationId} chars=${frame.text.length} sessionKey=${frame.sessionKey ?? "(none)"}`);
+        try {
+            await callbacks.onMessage({
+                seq: frame.seq,
+                clientMessageId: frame.clientMessageId,
+                conversationId: frame.conversationId,
+                text: frame.text,
+                sentAt: frame.sentAt,
+                sessionKey: frame.sessionKey,
+            });
+        }
+        catch (e) {
+            errLog(TAG, "onMessage handler threw:", e);
+            // Still ack — handler errors should not block the inbound queue.
+        }
+        lastAckSeq = frame.seq;
+        sendRaw({ type: "ack", seq: frame.seq });
+    }
+    /**
+     * Inbound list_sessions — app asks "which trajectory files do you
+     * have on disk?". We dispatch to the handler, wrap the result in a
+     * `sessions_list` frame, send it back. If no handler is registered
+     * we return an empty list (forgiving — old sidecar versions just
+     * report nothing alive).
+     */
+    async function handleListSessions(_frame) {
+        log(TAG, "inbound list_sessions");
+        let sessionKeys = [];
+        if (callbacks.onListSessions) {
+            try {
+                sessionKeys = await callbacks.onListSessions();
+            }
+            catch (e) {
+                errLog(TAG, "onListSessions handler threw:", e);
+            }
+        }
+        else {
+            warn(TAG, "list_sessions received but no onListSessions handler registered");
+        }
+        log(TAG, `responding sessions_list count=${sessionKeys.length}`);
+        sendRaw({ type: "sessions_list", sessionKeys });
+    }
+    /**
+     * Inbound delete_session — app asked us to remove a chat's trajectory
+     * file from disk. We always send an ack frame back so the app can flip
+     * its UI state. If no handler is registered we ack with a generic
+     * "not supported" error rather than silently dropping.
+     */
+    async function handleDeleteSession(frame) {
+        log(TAG, `inbound delete_session sessionKey=${frame.sessionKey}`);
+        if (!callbacks.onDeleteSession) {
+            warn(TAG, "delete_session received but no onDeleteSession handler registered");
+            sendRaw({
+                type: "delete_session_ack",
+                sessionKey: frame.sessionKey,
+                success: false,
+                error: "sidecar has no delete handler",
+            });
+            return;
+        }
+        let result;
+        try {
+            result = await callbacks.onDeleteSession({ sessionKey: frame.sessionKey });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            errLog(TAG, "onDeleteSession handler threw:", msg);
+            sendRaw({
+                type: "delete_session_ack",
+                sessionKey: frame.sessionKey,
+                success: false,
+                error: `handler threw: ${msg}`,
+            });
+            return;
+        }
+        sendRaw({
+            type: "delete_session_ack",
+            sessionKey: frame.sessionKey,
+            success: result.success,
+            error: result.error,
+        });
+    }
+    /**
+     * Inbound fetch_history — app asks us to restore a chat's past messages
+     * from disk (after it cleared app data / re-paired). We read+parse the
+     * trajectory and reply with a `history` frame. We always reply (even on
+     * error / no handler) so the app's backfill pump can advance.
+     */
+    async function handleFetchHistory(frame) {
+        log(TAG, `inbound fetch_history sessionKey=${frame.sessionKey}`);
+        if (!callbacks.onFetchHistory) {
+            warn(TAG, "fetch_history received but no onFetchHistory handler registered");
+            sendRaw({
+                type: "history",
+                sessionKey: frame.sessionKey,
+                messages: [],
+                error: "sidecar has no history handler",
+            });
+            return;
+        }
+        let result;
+        try {
+            result = await callbacks.onFetchHistory({ sessionKey: frame.sessionKey });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            errLog(TAG, "onFetchHistory handler threw:", msg);
+            sendRaw({
+                type: "history",
+                sessionKey: frame.sessionKey,
+                messages: [],
+                error: `handler threw: ${msg}`,
+            });
+            return;
+        }
+        log(TAG, `responding history sessionKey=${frame.sessionKey} count=${result.messages.length} error=${result.error ?? "(none)"}`);
+        sendRaw({
+            type: "history",
+            sessionKey: frame.sessionKey,
+            messages: result.messages,
+            error: result.error,
+        });
+    }
+    function startPing() {
+        if (pingTimer)
+            return;
+        pingTimer = setInterval(() => {
+            sendRaw({ type: "ping", t: Date.now() });
+        }, pingIntervalMs);
+    }
+    function connect() {
+        if (stopped)
+            return;
+        transition("connecting");
+        log(TAG, `connecting to ${redact(options.relayUrl)}`);
+        let ws;
+        try {
+            ws = socketFactory(options.relayUrl);
+        }
+        catch (e) {
+            errLog(TAG, "socket factory threw:", e);
+            scheduleReconnect("factory-throw");
+            return;
+        }
+        socket = ws;
+        ws.on("open", () => {
+            log(TAG, "socket open — sending hello");
+            sendRaw({
+                type: "hello",
+                version: PROTOCOL_VERSION,
+                role: "plugin",
+                deviceToken: options.deviceToken,
+                lastAckSeq,
+                client: {
+                    sidecarVersion: options.sidecarVersion,
+                    nodeVersion: process.version,
+                    platform: process.platform,
+                },
+            });
+        });
+        ws.on("message", (data) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(data.toString());
+            }
+            catch (e) {
+                warn(TAG, "bad inbound JSON:", e);
+                return;
+            }
+            handleServerFrame(parsed);
+        });
+        ws.on("close", (code, reason) => {
+            const reasonStr = reason.toString() || `code=${code}`;
+            log(TAG, `socket closed code=${code} reason=${reasonStr}`);
+            clearTimers();
+            socket = null;
+            if (stopped) {
+                transition("closed");
+                callbacks.onDisconnected({ fatal: false, reason: "stopped" });
+                return;
+            }
+            callbacks.onDisconnected({ fatal: false, reason: reasonStr });
+            scheduleReconnect(reasonStr);
+        });
+        ws.on("error", (e) => {
+            warn(TAG, "socket error:", e.message);
+            // 'close' will follow; reconnect happens there.
+        });
+    }
+    // Kick off initial connection.
+    connect();
+    return {
+        async sendAgentReply(partial) {
+            const frame = { type: "agent_reply", ...partial };
+            if (socket && socket.readyState === WebSocket.OPEN) {
+                if (!sendRaw(frame))
+                    outboundQueue.push(frame);
+            }
+            else {
+                // Buffer until reconnect — keeps streaming chunks ordered.
+                outboundQueue.push(frame);
+            }
+        },
+        state() {
+            return state;
+        },
+        async close(reason = "explicit") {
+            log(TAG, "close requested reason=", reason);
+            stopped = true;
+            clearTimers();
+            if (socket) {
+                try {
+                    socket.close(1000, reason);
+                }
+                catch {
+                    /* ignore */
+                }
+                socket = null;
+            }
+            transition("closed");
+        },
+    };
+}
+/** Redact a URL's userinfo+query for logging. */
+function redact(url) {
+    try {
+        const u = new URL(url);
+        u.password = "";
+        u.username = "";
+        return `${u.protocol}//${u.host}${u.pathname}`;
+    }
+    catch {
+        return url.split("?")[0] ?? url;
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+import type { SidecarConfig } from "./types.js";
+export declare const DEFAULT_CONFIG_PATH: string;
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function loadConfig(path?: string): SidecarConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,mBAAmB,QAAgD,CAAC;AAEjF,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,UAAU,CAAC,IAAI,GAAE,MAA4B,GAAG,aAAa,CAqB5E"}

package/dist/config.js

@@ -0,0 +1,84 @@
+// Sidecar configuration loader.
+//
+// Reads ~/.earzbook/sidecar.json (or a path supplied via --config) and
+// validates the shape before the adapter starts. Validation is strict
+// because a corrupted config could cause the sidecar to dial a wrong
+// relay, or worse, leak the deviceToken JWT to the wrong host.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const DEFAULT_CONFIG_PATH = join(homedir(), ".earzbook", "openclaw.json");
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+export function loadConfig(path = DEFAULT_CONFIG_PATH) {
+    if (!existsSync(path)) {
+        throw new ConfigError(`config file not found at ${path} — run the Earzbook pair flow to provision`);
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new ConfigError(`failed to read config ${path}: ${msg}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new ConfigError(`config ${path} is not valid JSON: ${msg}`);
+    }
+    return validate(parsed, path);
+}
+function validate(parsed, path) {
+    if (!parsed || typeof parsed !== "object") {
+        throw new ConfigError(`config ${path}: top-level must be an object`);
+    }
+    const o = parsed;
+    requireString(o, "relayUrl", path);
+    requireString(o, "deviceToken", path);
+    requireString(o, "userId", path);
+    requireString(o, "agentId", path);
+    requireString(o, "versionEndpoint", path);
+    const relayUrl = o.relayUrl;
+    if (!/^wss?:\/\//.test(relayUrl)) {
+        throw new ConfigError(`config ${path}: relayUrl must start with ws:// or wss:// (got ${relayUrl})`);
+    }
+    const versionEndpoint = o.versionEndpoint;
+    if (!/^https?:\/\//.test(versionEndpoint)) {
+        throw new ConfigError(`config ${path}: versionEndpoint must start with http:// or https://`);
+    }
+    return {
+        relayUrl,
+        deviceToken: o.deviceToken,
+        userId: o.userId,
+        agentId: o.agentId,
+        versionEndpoint,
+        pingIntervalMs: optionalNumber(o, "pingIntervalMs"),
+        reconnectBaseMs: optionalNumber(o, "reconnectBaseMs"),
+        reconnectMaxMs: optionalNumber(o, "reconnectMaxMs"),
+        agentTimeoutMs: optionalNumber(o, "agentTimeoutMs"),
+    };
+}
+function requireString(o, key, path) {
+    const v = o[key];
+    if (typeof v !== "string" || v.length === 0) {
+        throw new ConfigError(`config ${path}: missing or empty required field "${key}"`);
+    }
+}
+function optionalNumber(o, key) {
+    const v = o[key];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
+        throw new ConfigError(`config field "${key}" must be a non-negative number`);
+    }
+    return v;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/dispatch.d.ts

@@ -0,0 +1,48 @@
+import { spawn } from "node:child_process";
+/**
+ * Build the final --session-key argv value. Pure function; safe to test.
+ * Returns the legacy constant when no per-frame sessionKey is given.
+ */
+export declare function resolveSessionKey(perFrameSessionKey?: string): string;
+export interface DispatchInput {
+    agentId: string;
+    text: string;
+    /**
+     * Optional per-message session key (v1 multi-session). When provided,
+     * the resolved key becomes `earzbook-app:<sessionKey>`. When omitted,
+     * the bare `earzbook-app` constant is used (legacy single-session).
+     */
+    sessionKey?: string;
+    /** Timeout in ms. Hard-kill at this point. Default 120_000. */
+    timeoutMs?: number;
+    /** Override for tests — defaults to the global child_process.spawn. */
+    spawnFn?: typeof spawn;
+}
+export type DispatchResult = {
+    ok: true;
+    replyText: string;
+    durationMs: number;
+} | {
+    ok: false;
+    userVisibleError: string;
+    durationMs: number;
+};
+/** Run one agent turn and return the reply text. */
+export declare function dispatchToAgent(input: DispatchInput): Promise<DispatchResult>;
+/**
+ * Pull the reply text out of `openclaw agent --json` stdout.
+ *
+ * OpenClaw 2026.5.22 emits this shape on success (verified against a real
+ * run):
+ *   {
+ *     "payloads": [{"text": "...", "mediaUrl": null}],
+ *     "meta": { ..., "finalAssistantVisibleText": "...", ... }
+ *   }
+ *
+ * `payloads[0].text` is the canonical reply text. `finalAssistantVisibleText`
+ * is a meta mirror — usually identical, but we treat it as a fallback.
+ * Older candidates (output/reply/text at top level) stay in the list so we
+ * don't break if OpenClaw changes the shape.
+ */
+export declare function extractReplyText(stdout: string): string;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AA+B9D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAoH7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA8DvD"}