@ekodb/ekodb-client 0.20.0 → 0.22.0

package/dist/client.js

@@ -402,8 +402,8 @@ class EkoDBClient {
             params.append("transaction_id", options.transactionId);
         }
         const url = params.toString()
-            ? `/api/insert/${collection}?${params.toString()}`
-            : `/api/insert/${collection}`;
+            ? `/api/insert/${encodeURIComponent(collection)}?${params.toString()}`
+            : `/api/insert/${encodeURIComponent(collection)}`;
         return this.makeRequest("POST", url, data);
     }
     /**
@@ -428,15 +428,57 @@ class EkoDBClient {
      * const results = await client.find("users", { limit: 10 });
      * ```
      */
-    async find(collection, query = {}) {
+    async find(collection, query = {}, options) {
         const queryObj = query instanceof query_builder_1.QueryBuilder ? query.build() : query;
-        return this.makeRequest("POST", `/api/find/${collection}`, queryObj);
+        // bypass_ripple and transaction_id are query parameters — the same way every
+        // other method (insert/update/findById) carries bypass_ripple — not part of
+        // the FindBody. Hoist any bypass_ripple carried on the query object (e.g. from
+        // QueryBuilder.bypassRipple()) out of the body so it is ALWAYS sent as a query
+        // param; an explicit options.bypassRipple wins.
+        let body = queryObj;
+        let bypassRipple = options?.bypassRipple;
+        if (body && typeof body === "object" && "bypass_ripple" in body) {
+            const { bypass_ripple, ...rest } = body;
+            body = rest;
+            if (bypassRipple === undefined)
+                bypassRipple = bypass_ripple;
+        }
+        const params = new URLSearchParams();
+        if (options?.transactionId)
+            params.append("transaction_id", options.transactionId);
+        if (bypassRipple !== undefined)
+            params.append("bypass_ripple", String(bypassRipple));
+        const qs = params.toString();
+        const url = qs
+            ? `/api/find/${encodeURIComponent(collection)}?${qs}`
+            : `/api/find/${encodeURIComponent(collection)}`;
+        return this.makeRequest("POST", url, body);
     }
     /**
-     * Find a document by ID
+     * Find a document by ID.
+     * @param options - Optional read options. `transactionId` reads within a
+     *   transaction (read-your-writes); see {@link FindByIdOptions}.
      */
-    async findById(collection, id) {
-        return this.makeRequest("GET", `/api/find/${collection}/${id}`);
+    async findById(collection, id, options) {
+        const params = new URLSearchParams();
+        if (options?.selectFields?.length) {
+            params.append("select_fields", options.selectFields.join(","));
+        }
+        if (options?.excludeFields?.length) {
+            params.append("exclude_fields", options.excludeFields.join(","));
+        }
+        // bypass_ripple is a GET query param, the same way the non-transactional
+        // findById carries it; it rides alongside transaction_id when both are set.
+        if (options?.bypassRipple !== undefined) {
+            params.append("bypass_ripple", String(options.bypassRipple));
+        }
+        if (options?.transactionId) {
+            params.append("transaction_id", options.transactionId);
+        }
+        const url = params.toString()
+            ? `/api/find/${encodeURIComponent(collection)}/${encodeURIComponent(id)}?${params.toString()}`
+            : `/api/find/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`;
+        return this.makeRequest("GET", url);
     }
     /**
      * Find a document by ID with field projection
@@ -444,8 +486,9 @@ class EkoDBClient {
      * @param id - Document ID
      * @param selectFields - Fields to include in the result
      * @param excludeFields - Fields to exclude from the result
+     * @param transactionId - Read within a transaction (read-your-writes)
      */
-    async findByIdWithProjection(collection, id, selectFields, excludeFields) {
+    async findByIdWithProjection(collection, id, selectFields, excludeFields, transactionId) {
         const params = new URLSearchParams();
         if (selectFields?.length) {
             params.append("select_fields", selectFields.join(","));
@@ -453,9 +496,12 @@ class EkoDBClient {
         if (excludeFields?.length) {
             params.append("exclude_fields", excludeFields.join(","));
         }
+        if (transactionId) {
+            params.append("transaction_id", transactionId);
+        }
         const url = params.toString()
-            ? `/api/find/${collection}/${id}?${params.toString()}`
-            : `/api/find/${collection}/${id}`;
+            ? `/api/find/${encodeURIComponent(collection)}/${encodeURIComponent(id)}?${params.toString()}`
+            : `/api/find/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`;
         return this.makeRequest("GET", url);
     }
     /**
@@ -474,8 +520,8 @@ class EkoDBClient {
             params.append("transaction_id", options.transactionId);
         }
         const url = params.toString()
-            ? `/api/update/${collection}/${id}?${params.toString()}`
-            : `/api/update/${collection}/${id}`;
+            ? `/api/update/${encodeURIComponent(collection)}/${encodeURIComponent(id)}?${params.toString()}`
+            : `/api/update/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`;
         return this.makeRequest("PUT", url, record);
     }
     /**
@@ -492,7 +538,7 @@ class EkoDBClient {
      * @param value - The value for the action (omit for pop/shift/clear)
      */
     async updateWithAction(collection, id, action, field, value) {
-        const url = `/api/update/${collection}/${id}/action/${action}`;
+        const url = `/api/update/${encodeURIComponent(collection)}/${encodeURIComponent(id)}/action/${encodeURIComponent(action)}`;
         return this.makeRequest("PUT", url, {
             field,
             value: value ?? null,
@@ -509,7 +555,7 @@ class EkoDBClient {
      * @param actions - Array of [action, field, value] tuples
      */
     async updateWithActionSequence(collection, id, actions) {
-        const url = `/api/update/sequence/${collection}/${id}`;
+        const url = `/api/update/sequence/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`;
         return this.makeRequest("PUT", url, actions);
     }
     /**
@@ -527,8 +573,8 @@ class EkoDBClient {
             params.append("transaction_id", options.transactionId);
         }
         const url = params.toString()
-            ? `/api/delete/${collection}/${id}?${params.toString()}`
-            : `/api/delete/${collection}/${id}`;
+            ? `/api/delete/${encodeURIComponent(collection)}/${encodeURIComponent(id)}?${params.toString()}`
+            : `/api/delete/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`;
         await this.makeRequest("DELETE", url);
     }
     /**
@@ -547,8 +593,8 @@ class EkoDBClient {
         }
         const inserts = records.map((data) => ({ data }));
         const url = params.toString()
-            ? `/api/batch/insert/${collection}?${params.toString()}`
-            : `/api/batch/insert/${collection}`;
+            ? `/api/batch/insert/${encodeURIComponent(collection)}?${params.toString()}`
+            : `/api/batch/insert/${encodeURIComponent(collection)}`;
         return this.makeRequest("POST", url, { inserts });
     }
     /**
@@ -560,7 +606,7 @@ class EkoDBClient {
             data: u.data,
             bypass_ripple: u.bypassRipple,
         }));
-        return this.makeRequest("PUT", `/api/batch/update/${collection}`, { updates: formattedUpdates });
+        return this.makeRequest("PUT", `/api/batch/update/${encodeURIComponent(collection)}`, { updates: formattedUpdates });
     }
     /**
      * Batch delete multiple documents
@@ -570,7 +616,7 @@ class EkoDBClient {
             id: id,
             bypass_ripple: bypassRipple,
         }));
-        return this.makeRequest("DELETE", `/api/batch/delete/${collection}`, { deletes });
+        return this.makeRequest("DELETE", `/api/batch/delete/${encodeURIComponent(collection)}`, { deletes });
     }
     /**
      * Set a key-value pair with optional TTL
@@ -598,6 +644,12 @@ class EkoDBClient {
     async kvDelete(key) {
         await this.makeRequest("DELETE", `/api/kv/delete/${encodeURIComponent(key)}`, undefined, 0, true);
     }
+    /**
+     * Clear the entire KV store (all keys in the namespace).
+     */
+    async kvClear() {
+        await this.makeRequest("DELETE", "/api/kv/clear", undefined, 0, true);
+    }
     /**
      * Batch get multiple keys
      * @param keys - Array of keys to retrieve
@@ -663,7 +715,18 @@ class EkoDBClient {
     // Transaction Operations
     // ============================================================================
     /**
-     * Begin a new transaction
+     * Begin a new transaction.
+     *
+     * Transactions are buffered: statements issued with this `transactionId`
+     * (passed via the `transactionId` option on insert/update/delete/find/…) are
+     * staged and applied atomically only at {@link commitTransaction}. They are
+     * invisible to everyone else until commit, and visible to this transaction's
+     * own reads (read-your-writes) only when those reads also carry the
+     * `transactionId`. {@link rollbackTransaction} discards the staged writes.
+     * `commitTransaction` may reject with a conflict (HTTP 409) if a record this
+     * transaction read or wrote was changed by another committed transaction —
+     * retry the transaction in that case.
+     *
      * @param isolationLevel - Transaction isolation level (default: "ReadCommitted")
      * @returns Transaction ID
      */
@@ -687,12 +750,31 @@ class EkoDBClient {
         await this.makeRequest("POST", `/api/transactions/${encodeURIComponent(transactionId)}/commit`, undefined, 0, true);
     }
     /**
-     * Rollback a transaction
+     * Rollback a transaction (discards all staged writes; nothing was applied).
      * @param transactionId - The transaction ID to rollback
      */
     async rollbackTransaction(transactionId) {
         await this.makeRequest("POST", `/api/transactions/${encodeURIComponent(transactionId)}/rollback`, undefined, 0, true);
     }
+    /**
+     * Create a savepoint within a transaction. A later
+     * {@link rollbackToSavepoint} discards everything staged after it.
+     */
+    async createSavepoint(transactionId, name) {
+        await this.makeRequest("POST", `/api/transactions/${encodeURIComponent(transactionId)}/savepoints`, { name }, 0, true);
+    }
+    /**
+     * Roll the transaction back to a savepoint, discarding writes staged after it.
+     */
+    async rollbackToSavepoint(transactionId, name) {
+        await this.makeRequest("POST", `/api/transactions/${encodeURIComponent(transactionId)}/savepoints/${encodeURIComponent(name)}/rollback`, undefined, 0, true);
+    }
+    /**
+     * Release (forget) a savepoint. Staged work is unaffected.
+     */
+    async releaseSavepoint(transactionId, name) {
+        await this.makeRequest("DELETE", `/api/transactions/${encodeURIComponent(transactionId)}/savepoints/${encodeURIComponent(name)}`, undefined, 0, true);
+    }
     // ============================================================================
     // Convenience Methods
     // ============================================================================
@@ -833,11 +915,18 @@ class EkoDBClient {
         const result = await this.makeRequest("GET", "/api/collections", undefined, 0, true);
         return result.collections;
     }
+    /**
+     * List collections, excluding internal chat/system collections.
+     */
+    async listUserCollections() {
+        const result = await this.makeRequest("GET", "/api/collections?exclude_internal=true", undefined, 0, true);
+        return result.collections;
+    }
     /**
      * Delete a collection
      */
     async deleteCollection(collection) {
-        await this.makeRequest("DELETE", `/api/collections/${collection}`, undefined, 0, true);
+        await this.makeRequest("DELETE", `/api/collections/${encodeURIComponent(collection)}`, undefined, 0, true);
     }
     /**
      * Restore a deleted record from trash
@@ -848,7 +937,7 @@ class EkoDBClient {
      * @returns true if restored successfully
      */
     async restoreRecord(collection, id) {
-        const result = await this.makeRequest("POST", `/api/trash/${collection}/${id}`, undefined, 0, true);
+        const result = await this.makeRequest("POST", `/api/trash/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`, undefined, 0, true);
         return result.status === "restored";
     }
     /**
@@ -859,7 +948,7 @@ class EkoDBClient {
      * @returns Number of records restored
      */
     async restoreCollection(collection) {
-        const result = await this.makeRequest("POST", `/api/trash/${collection}`, undefined, 0, true);
+        const result = await this.makeRequest("POST", `/api/trash/${encodeURIComponent(collection)}`, undefined, 0, true);
         return { recordsRestored: result.records_restored };
     }
     /**
@@ -880,7 +969,7 @@ class EkoDBClient {
      */
     async createCollection(collection, schema) {
         const schemaObj = schema instanceof schema_1.SchemaBuilder ? schema.build() : schema;
-        await this.makeRequest("POST", `/api/collections/${collection}`, schemaObj, 0, true);
+        await this.makeRequest("POST", `/api/collections/${encodeURIComponent(collection)}`, schemaObj, 0, true);
     }
     /**
      * Get collection metadata and schema
@@ -889,7 +978,7 @@ class EkoDBClient {
      * @returns Collection metadata including schema and analytics
      */
     async getCollection(collection) {
-        return this.makeRequest("GET", `/api/collections/${collection}`, undefined, 0, true);
+        return this.makeRequest("GET", `/api/collections/${encodeURIComponent(collection)}`, undefined, 0, true);
     }
     /**
      * Get collection schema
@@ -936,7 +1025,7 @@ class EkoDBClient {
      */
     async search(collection, query) {
         // Ensure all parameters from SearchQuery are sent to server
-        return this.makeRequest("POST", `/api/search/${collection}`, query, 0, true);
+        return this.makeRequest("POST", `/api/search/${encodeURIComponent(collection)}`, query, 0, true);
     }
     /**
      * Get distinct (unique) values for a field across all records in a collection.
@@ -966,7 +1055,7 @@ class EkoDBClient {
             body.bypass_ripple = options.bypassRipple;
         if (options.bypassCache !== undefined)
             body.bypass_cache = options.bypassCache;
-        return this.makeRequest("POST", `/api/distinct/${collection}/${field}`, body, 0, true);
+        return this.makeRequest("POST", `/api/distinct/${encodeURIComponent(collection)}/${encodeURIComponent(field)}`, body, 0, true);
     }
     /**
      * Health check - verify the ekoDB server is responding
@@ -1146,20 +1235,36 @@ class EkoDBClient {
      * Send a message in an existing chat session
      */
     async chatMessage(sessionId, request) {
-        return this.makeRequest("POST", `/api/chat/${sessionId}/messages`, request, 0, true);
+        return this.makeRequest("POST", `/api/chat/${encodeURIComponent(sessionId)}/messages`, request, 0, true);
     }
     /**
      * Submit a client tool result for an in-flight SSE chat stream.
      * Unblocks ekoDB's tool loop so it can feed the result to the LLM.
      */
     async submitChatToolResult(chatId, callId, success, result, error) {
-        await this.makeRequest("POST", `/api/chat/${chatId}/tool-result`, {
+        await this.makeRequest("POST", `/api/chat/${encodeURIComponent(chatId)}/tool-result`, {
             call_id: callId,
             success,
             ...(result !== undefined && { result }),
             ...(error !== undefined && { error }),
         }, 0, true);
     }
+    /**
+     * Send a client tool keepalive (liveness ping) for an in-flight SSE chat stream.
+     *
+     * This is NOT a result: it does not unblock the tool loop or feed anything to the
+     * LLM. It simply resets the server's per-tool wait deadline (governed by
+     * `client_tool_timeout_secs`, default 60s) so that slow user confirmations or
+     * long-running client tools don't get the turn timed out before
+     * {@link submitChatToolResult} arrives. Send it periodically while a client tool
+     * is still working. See ekoDB#530.
+     */
+    async submitChatToolKeepalive(chatId, callId) {
+        await this.makeRequest("POST", `/api/chat/${encodeURIComponent(chatId)}/tool-result`, {
+            call_id: callId,
+            keepalive: true,
+        }, 0, true);
+    }
     /**
      * Send a message in an existing chat session via SSE streaming.
      *
@@ -1180,7 +1285,7 @@ class EkoDBClient {
                     await this.refreshToken();
                     token = await this.getToken();
                 }
-                const url = `${this.baseURL}/api/chat/${chatId}/messages/stream`;
+                const url = `${this.baseURL}/api/chat/${encodeURIComponent(chatId)}/messages/stream`;
                 const response = await fetch(url, {
                     method: "POST",
                     headers: {
@@ -1277,7 +1382,7 @@ class EkoDBClient {
      * Get a chat session by ID
      */
     async getChatSession(sessionId) {
-        return this.makeRequest("GET", `/api/chat/${sessionId}`, undefined, 0, true);
+        return this.makeRequest("GET", `/api/chat/${encodeURIComponent(sessionId)}`, undefined, 0, true);
     }
     /**
      * List all chat sessions
@@ -1307,15 +1412,15 @@ class EkoDBClient {
             params.append("sort", query.sort);
         const queryString = params.toString();
         const path = queryString
-            ? `/api/chat/${sessionId}/messages?${queryString}`
-            : `/api/chat/${sessionId}/messages`;
+            ? `/api/chat/${encodeURIComponent(sessionId)}/messages?${queryString}`
+            : `/api/chat/${encodeURIComponent(sessionId)}/messages`;
         return this.makeRequest("GET", path, undefined, 0, true);
     }
     /**
      * Update a chat session
      */
     async updateChatSession(sessionId, request) {
-        return this.makeRequest("PUT", `/api/chat/${sessionId}`, request, 0, true);
+        return this.makeRequest("PUT", `/api/chat/${encodeURIComponent(sessionId)}`, request, 0, true);
     }
     /**
      * Branch a chat session
@@ -1327,31 +1432,31 @@ class EkoDBClient {
      * Delete a chat session
      */
     async deleteChatSession(sessionId) {
-        await this.makeRequest("DELETE", `/api/chat/${sessionId}`, undefined, 0, true);
+        await this.makeRequest("DELETE", `/api/chat/${encodeURIComponent(sessionId)}`, undefined, 0, true);
     }
     /**
      * Regenerate an AI response message
      */
     async regenerateMessage(sessionId, messageId) {
-        return this.makeRequest("POST", `/api/chat/${sessionId}/messages/${messageId}/regenerate`, undefined, 0, true);
+        return this.makeRequest("POST", `/api/chat/${encodeURIComponent(sessionId)}/messages/${encodeURIComponent(messageId)}/regenerate`, undefined, 0, true);
     }
     /**
      * Update a specific message
      */
     async updateChatMessage(sessionId, messageId, content) {
-        await this.makeRequest("PUT", `/api/chat/${sessionId}/messages/${messageId}`, { content }, 0, true);
+        await this.makeRequest("PUT", `/api/chat/${encodeURIComponent(sessionId)}/messages/${encodeURIComponent(messageId)}`, { content }, 0, true);
     }
     /**
      * Delete a specific message
      */
     async deleteChatMessage(sessionId, messageId) {
-        await this.makeRequest("DELETE", `/api/chat/${sessionId}/messages/${messageId}`, undefined, 0, true);
+        await this.makeRequest("DELETE", `/api/chat/${encodeURIComponent(sessionId)}/messages/${encodeURIComponent(messageId)}`, undefined, 0, true);
     }
     /**
      * Toggle the "forgotten" status of a message
      */
     async toggleForgottenMessage(sessionId, messageId, forgotten) {
-        await this.makeRequest("PATCH", `/api/chat/${sessionId}/messages/${messageId}/forgotten`, { forgotten }, 0, true);
+        await this.makeRequest("PATCH", `/api/chat/${encodeURIComponent(sessionId)}/messages/${encodeURIComponent(messageId)}/forgotten`, { forgotten }, 0, true);
     }
     /**
      * Compact a chat session's history on demand.
@@ -1368,7 +1473,7 @@ class EkoDBClient {
         if (keepRecent !== undefined) {
             body.keep_recent = keepRecent;
         }
-        return this.makeRequest("POST", `/api/chat/${chatId}/compact`, body, 0, true);
+        return this.makeRequest("POST", `/api/chat/${encodeURIComponent(chatId)}/compact`, body, 0, true);
     }
     /**
      * Merge multiple chat sessions into one
@@ -1406,7 +1511,7 @@ class EkoDBClient {
      * @returns The chat message record
      */
     async getChatMessage(sessionId, messageId) {
-        return this.makeRequest("GET", `/api/chat/${sessionId}/messages/${messageId}`, undefined, 0, true);
+        return this.makeRequest("GET", `/api/chat/${encodeURIComponent(sessionId)}/messages/${encodeURIComponent(messageId)}`, undefined, 0, true);
     }
     // ========================================================================
     // SCRIPTS API
@@ -1422,7 +1527,7 @@ class EkoDBClient {
      * Get a function by ID
      */
     async getFunction(id) {
-        return this.makeRequest("GET", `/api/functions/${id}`);
+        return this.makeRequest("GET", `/api/functions/${encodeURIComponent(id)}`);
     }
     /**
      * List all functions, optionally filtered by tags
@@ -1435,19 +1540,19 @@ class EkoDBClient {
      * Update an existing function by ID
      */
     async updateFunction(id, script) {
-        await this.makeRequest("PUT", `/api/functions/${id}`, script);
+        await this.makeRequest("PUT", `/api/functions/${encodeURIComponent(id)}`, script);
     }
     /**
      * Delete a function by ID
      */
     async deleteFunction(id) {
-        await this.makeRequest("DELETE", `/api/functions/${id}`);
+        await this.makeRequest("DELETE", `/api/functions/${encodeURIComponent(id)}`);
     }
     /**
      * Call a saved function by ID or label
      */
     async callFunction(idOrLabel, params) {
-        return this.makeRequest("POST", `/api/functions/${idOrLabel}`, params || {});
+        return this.makeRequest("POST", `/api/functions/${encodeURIComponent(idOrLabel)}`, params || {});
     }
     // ========================================================================
     // USER FUNCTIONS API
@@ -1556,15 +1661,15 @@ class EkoDBClient {
     }
     /** Start a goal step (status -> in_progress) */
     async goalStepStart(id, stepIndex) {
-        return this.makeRequest("POST", `/api/chat/goals/${encodeURIComponent(id)}/steps/${stepIndex}/start`, undefined, 0, true);
+        return this.makeRequest("POST", `/api/chat/goals/${encodeURIComponent(id)}/steps/${encodeURIComponent(String(stepIndex))}/start`, undefined, 0, true);
     }
     /** Complete a goal step with result */
     async goalStepComplete(id, stepIndex, data) {
-        return this.makeRequest("POST", `/api/chat/goals/${encodeURIComponent(id)}/steps/${stepIndex}/complete`, data, 0, true);
+        return this.makeRequest("POST", `/api/chat/goals/${encodeURIComponent(id)}/steps/${encodeURIComponent(String(stepIndex))}/complete`, data, 0, true);
     }
     /** Fail a goal step with error */
     async goalStepFail(id, stepIndex, data) {
-        return this.makeRequest("POST", `/api/chat/goals/${encodeURIComponent(id)}/steps/${stepIndex}/fail`, data, 0, true);
+        return this.makeRequest("POST", `/api/chat/goals/${encodeURIComponent(id)}/steps/${encodeURIComponent(String(stepIndex))}/fail`, data, 0, true);
     }
     // ========================================================================
     // TASK API
@@ -2099,6 +2204,13 @@ class WebSocketClient {
         this.ws = null;
         this.dispatcherRunning = false;
         this.schemaCache = null;
+        /**
+         * Per-connection wire format, set by negotiateFormat() on every (re)connect:
+         * true once the server has Welcomed msgpack, so frames are sent/received as
+         * binary msgpack; false (JSON text) otherwise, including against an older
+         * server that never Welcomes. Keeps the transport fully back-compatible.
+         */
+        this.binary = false;
         // Reconnect state
         /** Set while close() is in progress so the close handler doesn't reconnect. */
         this.closed = false;
@@ -2180,8 +2292,66 @@ class WebSocketClient {
             this.ws.on("open", () => resolve());
             this.ws.on("error", (err) => reject(err));
         });
+        // Negotiate the wire format before the dispatcher starts so the Welcome is
+        // consumed here (not by routeMessage), and before any real frame is sent
+        // (resubscribeAll runs only after this resolves).
+        await this.negotiateFormat(this.ws);
         this.spawnDispatcher();
     }
+    /**
+     * Additive capability handshake: offer msgpack and, if the server Welcomes
+     * it, switch this connection to binary msgpack frames; otherwise stay on JSON
+     * text. The Welcome (a text frame) is read with a one-shot listener and a
+     * timeout so an older server that never answers — or answers with an Error —
+     * simply leaves the connection on JSON. Best-effort and never throws: JSON
+     * always works.
+     */
+    async negotiateFormat(socket) {
+        this.binary = false;
+        const welcome = await new Promise((resolve) => {
+            const onMsg = (data) => {
+                clearTimeout(timer);
+                try {
+                    resolve(JSON.parse(data.toString()));
+                }
+                catch {
+                    resolve(null);
+                }
+            };
+            // Only caps the wait when no Welcome comes (a silent/old server); the
+            // listener resolves immediately when it does arrive. 2s comfortably exceeds
+            // the handshake round-trip even on high-latency links.
+            const timer = setTimeout(() => {
+                socket.off("message", onMsg);
+                resolve(null);
+            }, 2000);
+            socket.once("message", onMsg);
+            try {
+                socket.send(JSON.stringify({
+                    type: "Hello",
+                    payload: { formats: ["msgpack", "json"] },
+                }));
+            }
+            catch {
+                clearTimeout(timer);
+                socket.off("message", onMsg);
+                resolve(null);
+            }
+        });
+        if (welcome &&
+            welcome.type === "Welcome" &&
+            welcome.payload?.format === "msgpack") {
+            this.binary = true;
+        }
+    }
+    /**
+     * Send a request object on the active socket using the negotiated format:
+     * binary msgpack when the server Welcomed it, JSON text otherwise. The single
+     * write point so every request honors the negotiated transport.
+     */
+    sendFrame(obj) {
+        this.ws.send(this.binary ? (0, msgpack_1.encode)(obj) : JSON.stringify(obj));
+    }
     spawnDispatcher() {
         if (this.dispatcherRunning)
             return;
@@ -2190,11 +2360,16 @@ class WebSocketClient {
         // socket may still emit late close/error events; ignore them so they don't
         // tear down the replacement connection.
         const socket = this.ws;
-        socket.on("message", (data) => {
+        socket.on("message", (data, isBinary) => {
             if (this.ws !== socket)
                 return;
             try {
-                const msg = JSON.parse(data.toString());
+                // A binary frame is msgpack (the server only sends binary once it has
+                // Welcomed msgpack); a text frame is JSON. Decode by frame type so the
+                // routed value is identical regardless of negotiated transport.
+                const msg = isBinary
+                    ? (0, msgpack_1.decode)(data)
+                    : JSON.parse(data.toString());
                 this.routeMessage(msg);
             }
             catch {
@@ -2477,7 +2652,7 @@ class WebSocketClient {
             }
             this.pendingRequests.set(messageId, { resolve, reject, timer });
             try {
-                this.ws.send(JSON.stringify(request));
+                this.sendFrame(request);
             }
             catch (err) {
                 this.pendingRequests.delete(messageId);
@@ -2560,6 +2735,27 @@ class WebSocketClient {
         if (stream && !stream.closed) {
             stream.close();
         }
+        // Best-effort: tell the server to stop streaming this collection (the
+        // server already handles an Unsubscribe frame). If the socket isn't open
+        // the local teardown above suffices, since the server drops subscriptions
+        // when the connection closes. A unique messageId is attached so the
+        // server's Success ack carries a correlation id: it has no pending request
+        // to match, so it is simply ignored — and because the id is present, the
+        // single-pending fallback can't misroute it to an unrelated request.
+        if (this.ws && this.ws.readyState === 1 /* WebSocket.OPEN */) {
+            try {
+                this.sendFrame({
+                    type: "Unsubscribe",
+                    messageId: this.genMessageId(),
+                    payload: { collection },
+                });
+            }
+            catch {
+                // Best-effort: the socket can close between the readyState check and the
+                // send. Local teardown already happened, so swallow the failure rather
+                // than throw out of a void teardown call.
+            }
+        }
     }
     /**
      * Send a chat message and receive a streaming response.
@@ -2588,7 +2784,7 @@ class WebSocketClient {
                 ...(options?.excludeTools && { exclude_tools: options.excludeTools }),
             },
         };
-        this.ws.send(JSON.stringify(request));
+        this.sendFrame(request);
         return stream;
     }
     /**
@@ -2608,7 +2804,7 @@ class WebSocketClient {
                 resolve: () => resolve(),
                 reject: (err) => reject(err),
             };
-            this.ws.send(JSON.stringify(request));
+            this.sendFrame(request);
         });
     }
     /**
@@ -2626,7 +2822,24 @@ class WebSocketClient {
                 ...(error !== undefined && { error }),
             },
         };
-        this.ws.send(JSON.stringify(request));
+        this.sendFrame(request);
+    }
+    /**
+     * Cancel an in-flight streaming chat. Fire-and-forget: tells the server to
+     * stop generating tokens for the given chat.
+     */
+    async cancelChat(chatId) {
+        await this.ensureConnected();
+        // Attach a unique messageId (same generator as unsubscribe). Any Success ack
+        // from the server then carries a correlation id: it has no pending request to
+        // match, so it is ignored — and because the id is present, the dispatcher's
+        // single-pending fallback can't misroute the ack to an unrelated request.
+        const request = {
+            type: "CancelChat",
+            messageId: this.genMessageId(),
+            payload: { chat_id: chatId },
+        };
+        this.sendFrame(request);
     }
     /**
      * Stateless raw LLM completion via WebSocket.