@earzbook/openclaw 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,236 @@
+export declare const PROTOCOL_VERSION = 1;
+export interface HelloFrame {
+    type: "hello";
+    version: number;
+    role: "plugin";
+    deviceToken: string;
+    /** Sequence of the last server frame we successfully processed. */
+    lastAckSeq?: number;
+    /** Optional client metadata for diagnostics. Never include secrets. */
+    client?: {
+        sidecarVersion: string;
+        nodeVersion?: string;
+        platform?: string;
+    };
+}
+export interface AckFrame {
+    type: "ack";
+    /** Sequence of the inbound frame we are acknowledging. */
+    seq: number;
+}
+export interface AgentReplyFrame {
+    type: "agent_reply";
+    /** Conversation we are replying inside, copied from the originating user_message. */
+    conversationId: string;
+    /** Server-generated chunk sequence for ordered reassembly on the app side. */
+    chunkSeq: number;
+    /** Append-only text chunk (markdown allowed). Empty string on isFinal=true is valid. */
+    text: string;
+    /** True on the LAST chunk of a turn. App marks the AI bubble complete on this frame. */
+    isFinal: boolean;
+    /** Optional opaque id correlating to the inbound user_message that triggered the reply. */
+    inReplyTo?: string;
+    /**
+     * Per-session routing tag echoed back from the originating user_message
+     * (v2 flat sessions). The app uses this to look up the right local
+     * Conversation row when persisting the reply.
+     */
+    sessionKey?: string;
+}
+export interface SessionsListFrame {
+    type: "sessions_list";
+    /**
+     * The session-keys for which a trajectory file currently exists on
+     * this sidecar's disk. Each entry is the BARE sessionKey (i.e. the
+     * portion after the `earzbook-app:` namespace prefix that we add when
+     * invoking openclaw). The app compares directly to its
+     * `openclaw_session_key` Watermelon column to derive lock state.
+     */
+    sessionKeys: string[];
+}
+export interface DeleteSessionAckFrame {
+    type: "delete_session_ack";
+    /** The session-key the app asked us to delete; echoed verbatim. */
+    sessionKey: string;
+    /** True iff the trajectory file was successfully removed (or didn't exist). */
+    success: boolean;
+    /** Free-form failure detail (set only when success=false). */
+    error?: string;
+}
+/**
+ * One restored message from an on-disk OpenClaw session trajectory.
+ * Shared shape between the `history` wire frame and the adapter callback.
+ */
+export interface OpenClawHistoryMessage {
+    /** Who spoke. We only surface user + assistant turns (tool noise dropped). */
+    role: "user" | "assistant";
+    /** Plain visible text (assistant text blocks joined; thinking/tool stripped). */
+    text: string;
+    /** Original message timestamp (ms since epoch) so the app preserves order. */
+    at: number;
+}
+export interface HistoryFrame {
+    type: "history";
+    /** The session-key the app asked about; echoed verbatim so it can match the response. */
+    sessionKey: string;
+    /**
+     * Chronological user+assistant messages parsed from the session's
+     * trajectory .jsonl on disk. Empty when the session has no displayable
+     * content OR when `error` is set.
+     */
+    messages: OpenClawHistoryMessage[];
+    /** Set only on failure (bad sessionKey, read error). messages is [] then. */
+    error?: string;
+}
+export interface PingFrame {
+    type: "ping";
+    /** Monotonic timestamp (ms since epoch) for round-trip diagnostics only. */
+    t: number;
+}
+export type ClientFrame = HelloFrame | AckFrame | AgentReplyFrame | SessionsListFrame | DeleteSessionAckFrame | HistoryFrame | PingFrame;
+export interface WelcomeFrame {
+    type: "welcome";
+    /** Server has accepted hello and advertises the last seq it saw from us. */
+    lastAckSeq: number;
+    /** Identity confirmation (userId only — no PII). */
+    userId: string;
+    /** Server time so we can detect clock skew for diagnostics. */
+    serverTime: number;
+}
+export interface UserMessageFrame {
+    type: "user_message";
+    /** Server-monotonic sequence within this connection. Sidecar must ack. */
+    seq: number;
+    /** App-generated stable id (idempotency key); echo back on agent_reply.inReplyTo. */
+    clientMessageId: string;
+    /** Local conversation id from the app. */
+    conversationId: string;
+    /** Plain user text (markdown allowed but rare in inbound). */
+    text: string;
+    /** App-side send timestamp (ms). May lag real time on slow networks. */
+    sentAt: number;
+    /**
+     * Per-session routing tag (v2 flat sessions). When present, the sidecar
+     * invokes openclaw with `--session-key earzbook-app:<sessionKey>` so
+     * each chat gets its own isolated trajectory file on disk. When absent,
+     * falls back to the legacy bare `earzbook-app` constant for compat
+     * with older app versions.
+     */
+    sessionKey?: string;
+}
+export interface ListSessionsFrame {
+    type: "list_sessions";
+}
+export interface DeleteSessionFrame {
+    type: "delete_session";
+    /**
+     * The session-key whose on-disk files should be removed. The sidecar
+     * looks up the OpenClaw manifest entry under
+     *   `agent:<agentId>:earzbook-app:<sessionKey>`
+     * to find the actual file basename (a UUID OpenClaw assigned), then
+     * unlinks the three associated files (.jsonl, .trajectory.jsonl,
+     * .trajectory-path.json) + scrubs the entry from sessions.json.
+     *
+     * Validated against [a-zA-Z0-9_-]+ before any filesystem access to
+     * prevent path traversal.
+     */
+    sessionKey: string;
+}
+export interface FetchHistoryFrame {
+    type: "fetch_history";
+    /**
+     * The session-key whose on-disk message history the app wants restored.
+     * The sidecar looks up the OpenClaw manifest entry under
+     *   `agent:<agentId>:earzbook-app:<sessionKey>`
+     * and parses the associated trajectory .jsonl. Validated against
+     * [a-zA-Z0-9_-]+ before any filesystem access to prevent path traversal.
+     */
+    sessionKey: string;
+}
+export interface PongFrame {
+    type: "pong";
+    /** Echoes the t from the originating ping. */
+    t: number;
+}
+export interface ErrorFrame {
+    type: "error";
+    /** Stable machine code (e.g. "auth_invalid", "rate_limited", "version_mismatch"). */
+    code: string;
+    /** Human-readable detail, safe to log. */
+    message: string;
+    /** When true, the sidecar should NOT auto-reconnect (auth failed permanently). */
+    fatal: boolean;
+}
+export type ServerFrame = WelcomeFrame | UserMessageFrame | ListSessionsFrame | DeleteSessionFrame | FetchHistoryFrame | PongFrame | ErrorFrame;
+export interface InboundEnvelope {
+    seq: number;
+    clientMessageId: string;
+    conversationId: string;
+    text: string;
+    sentAt: number;
+    /** Per-session routing tag from the originating user_message (v2 flat sessions). */
+    sessionKey?: string;
+}
+export interface DeleteSessionResult {
+    success: boolean;
+    error?: string;
+}
+export interface AdapterCallbacks {
+    /** Called for every inbound user_message AFTER the adapter has updated lastAckSeq. */
+    onMessage(envelope: InboundEnvelope): Promise<void> | void;
+    /** Called once after a successful welcome (initial connect AND every reconnect). */
+    onConnected(welcome: WelcomeFrame): void;
+    /** Called when the socket closes; reconnect will follow unless fatal=true. */
+    onDisconnected(info: {
+        fatal: boolean;
+        reason: string;
+    }): void;
+    /**
+     * Called for each inbound `list_sessions` frame. The handler returns
+     * the set of session-keys currently on disk (bare, without the
+     * `earzbook-app:` prefix). The adapter wraps them in a `sessions_list`
+     * frame and sends it back to the app.
+     */
+    onListSessions?(): Promise<string[]>;
+    /**
+     * Called for each inbound `delete_session` frame. The handler resolves
+     * the trajectory file on disk and removes it. The adapter sends a
+     * `delete_session_ack` carrying the returned success/error fields.
+     */
+    onDeleteSession?(frame: {
+        sessionKey: string;
+    }): Promise<DeleteSessionResult>;
+    /**
+     * Called for each inbound `fetch_history` frame. The handler reads the
+     * session's on-disk trajectory .jsonl and returns its user+assistant
+     * messages. The adapter wraps them in a `history` frame back to the app
+     * (used to restore chats after the user cleared app data / re-paired).
+     */
+    onFetchHistory?(frame: {
+        sessionKey: string;
+    }): Promise<{
+        messages: OpenClawHistoryMessage[];
+        error?: string;
+    }>;
+}
+export interface SidecarConfig {
+    /** wss:// or ws:// URL of the Earzbook backend relay. */
+    relayUrl: string;
+    /** Long-lived device token issued at pairing time. Treated as opaque. */
+    deviceToken: string;
+    /** Earzbook user id this sidecar is bound to. */
+    userId: string;
+    /** OpenClaw agent id to dispatch inbound messages to (typically "main"). */
+    agentId: string;
+    /** HTTPS URL to GET for version-check polling. */
+    versionEndpoint: string;
+    /** Optional override for ping interval (ms). Default 30_000. */
+    pingIntervalMs?: number;
+    /** Optional override for reconnect base delay (ms). Default 3_000. */
+    reconnectBaseMs?: number;
+    /** Optional override for reconnect max delay (ms). Default 300_000 (5 min). */
+    reconnectMaxMs?: number;
+    /** Optional override for openclaw agent spawn timeout (ms). Default 120_000. */
+    agentTimeoutMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,22 @@
+// Frame and message types exchanged between the Earzbook sidecar (running
+// on the user's machine) and the Earzbook backend relay
+// (recall_backend/websocket/openclaw-relay.js).
+//
+// Wire protocol (JSON over WebSocket) — same as the plugin path:
+//   client → server : hello | ack | agent_reply | sessions_list | delete_session_ack | history | ping
+//   server → client : welcome | user_message | list_sessions | delete_session | fetch_history | pong | error
+//
+// All frames are JSON objects with a `type` discriminator. The sidecar
+// presents itself as `role: "plugin"` so the relay routes app messages
+// here exactly as it would route them to the channel plugin.
+//
+// v2 (flat sessions): `user_message` + `agent_reply` carry `sessionKey`
+// (per-chat AI-memory isolation: `--session-key earzbook-app:<sessionKey>`).
+// `list_sessions` (app→sidecar) + `sessions_list` (sidecar→app) drives
+// the per-chat strict lock: the app marks a chat 🔒 when its sessionKey
+// is NOT in the sidecar's reported set (i.e. the trajectory file isn't
+// on this machine). `delete_session` cascade-deletes a chat's files.
+// `deviceId` was removed from frames — flat model routes by sessionKey
+// only; the relay still enforces one-plugin-per-user.
+export const PROTOCOL_VERSION = 1;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,wDAAwD;AACxD,gDAAgD;AAChD,EAAE;AACF,iEAAiE;AACjE,sGAAsG;AACtG,6GAA6G;AAC7G,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,6DAA6D;AAC7D,EAAE;AACF,wEAAwE;AACxE,6EAA6E;AAC7E,uEAAuE;AACvE,wEAAwE;AACxE,uEAAuE;AACvE,qEAAqE;AACrE,uEAAuE;AACvE,sDAAsD;AAEtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@earzbook/openclaw",
+  "version": "0.1.0",
+  "description": "Earzbook ↔ OpenClaw sidecar daemon. Bridges the Earzbook mobile app to a locally-running OpenClaw agent via a WebSocket relay.",
+  "type": "module",
+  "bin": {
+    "earzbook-openclaw": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node ./scripts/post-build.mjs",
+    "watch": "tsc -p tsconfig.json --watch",
+    "clean": "rm -rf dist",
+    "test": "node --test --import tsx 'tests/*.test.ts'",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.5.13",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "earzbook",
+    "openclaw",
+    "sidecar",
+    "websocket",
+    "chat-bridge"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/earzbook/earzbook.git",
+    "directory": "openclaw/earzbook-sidecar"
+  },
+  "license": "MIT"
+}