@moltzap/client 2026.407.0

package/dist/ws-client.d.ts

@@ -0,0 +1,41 @@
+import { type EventFrame } from "@moltzap/protocol";
+export interface WsClientLogger {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+export interface MoltZapWsClientOptions {
+    serverUrl: string;
+    agentKey: string;
+    onEvent: (event: EventFrame) => void;
+    onDisconnect: () => void;
+    onReconnect: (helloOk: unknown) => void;
+    logger?: WsClientLogger;
+}
+/**
+ * WebSocket connection lifecycle:
+ *
+ *   connect -> auth/connect -> HelloOk -> active
+ *       | (disconnect)
+ *   backoff (1s, 2s, 4s, 8s, max 30s with jitter) -> reconnect -> auth/connect -> ...
+ */
+export declare class MoltZapWsClient {
+    private options;
+    private ws;
+    private reconnectAttempt;
+    private maxReconnectDelay;
+    private pendingRequests;
+    private requestCounter;
+    private closed;
+    private _helloOk;
+    constructor(options: MoltZapWsClientOptions);
+    get helloOk(): unknown;
+    connect(): Promise<unknown>;
+    sendRpc(method: string, params?: unknown): Promise<unknown>;
+    /** Close the socket permanently (no reconnection). */
+    close(): void;
+    /** Close the socket without marking as permanently closed, triggering reconnection. */
+    disconnect(): void;
+    private scheduleReconnect;
+}
+//# sourceMappingURL=ws-client.d.ts.map

package/dist/ws-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-client.d.ts","sourceRoot":"","sources":["../src/ws-client.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACnC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACnC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACrC,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;IAed,OAAO,CAAC,OAAO;IAd3B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,iBAAiB,CAAU;IACnC,OAAO,CAAC,eAAe,CAMnB;IACJ,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAiB;gBAEb,OAAO,EAAE,sBAAsB;IAEnD,IAAI,OAAO,IAAI,OAAO,CAErB;IAEK,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAqD3B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IA4CjE,sDAAsD;IACtD,KAAK,IAAI,IAAI;IAKb,uFAAuF;IACvF,UAAU,IAAI,IAAI;IAIlB,OAAO,CAAC,iBAAiB;CAiB1B"}

package/dist/ws-client.js

@@ -0,0 +1,138 @@
+import WebSocket from "ws";
+import { PROTOCOL_VERSION, } from "@moltzap/protocol";
+/**
+ * WebSocket connection lifecycle:
+ *
+ *   connect -> auth/connect -> HelloOk -> active
+ *       | (disconnect)
+ *   backoff (1s, 2s, 4s, 8s, max 30s with jitter) -> reconnect -> auth/connect -> ...
+ */
+export class MoltZapWsClient {
+    options;
+    ws = null;
+    reconnectAttempt = 0;
+    maxReconnectDelay = 30_000;
+    pendingRequests = new Map();
+    requestCounter = 0;
+    closed = false;
+    _helloOk = null;
+    constructor(options) {
+        this.options = options;
+    }
+    get helloOk() {
+        return this._helloOk;
+    }
+    async connect() {
+        return new Promise((resolve, reject) => {
+            const url = this.options.serverUrl.replace(/^http/, "ws") + "/ws";
+            this.ws = new WebSocket(url);
+            this.ws.on("open", async () => {
+                try {
+                    const helloOk = await this.sendRpc("auth/connect", {
+                        agentKey: this.options.agentKey,
+                        minProtocol: PROTOCOL_VERSION,
+                        maxProtocol: PROTOCOL_VERSION,
+                    });
+                    this._helloOk = helloOk;
+                    this.reconnectAttempt = 0;
+                    resolve(helloOk);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+            this.ws.on("message", (data) => {
+                try {
+                    const frame = JSON.parse(data.toString());
+                    if (frame.type === "response" && frame.id) {
+                        const pending = this.pendingRequests.get(frame.id);
+                        if (pending) {
+                            this.pendingRequests.delete(frame.id);
+                            if (frame.error) {
+                                const err = frame.error;
+                                pending.reject(new Error(err.message ?? "RPC error"));
+                            }
+                            else {
+                                pending.resolve(frame.result);
+                            }
+                        }
+                    }
+                    else if (frame.type === "event") {
+                        this.options.onEvent(frame);
+                    }
+                }
+                catch {
+                    this.options.logger?.warn("Malformed frame:", data.toString());
+                }
+            });
+            this.ws.on("close", () => {
+                this.options.onDisconnect();
+                if (!this.closed)
+                    this.scheduleReconnect();
+            });
+            this.ws.on("error", () => {
+                // error is followed by close
+            });
+        });
+    }
+    async sendRpc(method, params) {
+        const attempt = () => new Promise((resolve, reject) => {
+            const id = `rpc-${++this.requestCounter}`;
+            const frame = {
+                jsonrpc: "2.0",
+                type: "request",
+                id,
+                method,
+                params,
+            };
+            this.pendingRequests.set(id, { resolve, reject });
+            if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+                this.pendingRequests.delete(id);
+                reject(new Error("WebSocket not connected"));
+                return;
+            }
+            this.ws.send(JSON.stringify(frame));
+            setTimeout(() => {
+                if (this.pendingRequests.has(id)) {
+                    this.pendingRequests.delete(id);
+                    reject(new Error(`RPC timeout: ${method}`));
+                }
+            }, 30_000);
+        });
+        try {
+            return await attempt();
+        }
+        catch (err) {
+            if (err instanceof Error &&
+                err.message.startsWith("RPC timeout:") &&
+                method !== "auth/connect") {
+                return attempt();
+            }
+            throw err;
+        }
+    }
+    /** Close the socket permanently (no reconnection). */
+    close() {
+        this.closed = true;
+        this.ws?.close();
+    }
+    /** Close the socket without marking as permanently closed, triggering reconnection. */
+    disconnect() {
+        this.ws?.close();
+    }
+    scheduleReconnect() {
+        const baseDelay = Math.min(1000 * 2 ** this.reconnectAttempt, this.maxReconnectDelay);
+        const jitter = baseDelay * (0.5 + Math.random() * 0.5);
+        this.reconnectAttempt++;
+        setTimeout(async () => {
+            try {
+                const helloOk = await this.connect();
+                this.options.onReconnect(helloOk);
+            }
+            catch {
+                // connect failed, will retry on close event
+            }
+        }, jitter);
+    }
+}
+//# sourceMappingURL=ws-client.js.map

package/dist/ws-client.js.map

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

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@moltzap/client",
+  "version": "2026.407.0",
+  "description": "MoltZap client service — connection, conversation state, and cross-conversation context",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chughtapan/moltzap"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "moltzap": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "ws": "^8.18.0",
+    "@moltzap/protocol": "2026.408.0"
+  },
+  "devDependencies": {
+    "@testcontainers/postgresql": "^10.18.0",
+    "@types/pg": "^8.11.0",
+    "@types/ws": "^8.5.0",
+    "pg": "^8.13.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "@moltzap/server-core": "2026.408.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts"
+  }
+}