@ekodb/ekodb-client 0.19.0 → 0.21.0

package/dist/client.js

@@ -69,6 +69,19 @@ var MergeStrategy;
     MergeStrategy["LatestOnly"] = "LatestOnly";
     MergeStrategy["Interleaved"] = "Interleaved";
 })(MergeStrategy || (exports.MergeStrategy = MergeStrategy = {}));
+/**
+ * Strip trailing slashes from a base URL so path concatenation
+ * (`${base}/api/...`) never yields a double-slash path. Uses a linear scan
+ * rather than a regex like `/\/+$/`, which CodeQL flags as polynomial-time
+ * backtracking on caller-supplied input.
+ */
+function stripTrailingSlashes(url) {
+    let end = url.length;
+    while (end > 0 && url.charCodeAt(end - 1) === 47 /* "/" */) {
+        end--;
+    }
+    return end === url.length ? url : url.slice(0, end);
+}
 class EkoDBClient {
     constructor(config, apiKey) {
         this.token = null;
@@ -76,14 +89,16 @@ class EkoDBClient {
         this.rateLimitInfo = null;
         // Support both old (baseURL, apiKey) and new (config object) signatures
         if (typeof config === "string") {
-            this.baseURL = config;
+            // Strip trailing slashes so `${baseURL}/api/...` never produces a
+            // double-slash path (some servers/proxies reject `//api/...`).
+            this.baseURL = stripTrailingSlashes(config);
             this.apiKey = apiKey;
             this.shouldRetry = true;
             this.maxRetries = 3;
             this.format = SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
         }
         else {
-            this.baseURL = config.baseURL;
+            this.baseURL = stripTrailingSlashes(config.baseURL);
             this.apiKey = config.apiKey;
             this.shouldRetry = config.shouldRetry ?? true;
             this.maxRetries = config.maxRetries ?? 3;
@@ -223,6 +238,38 @@ class EkoDBClient {
     sleep(seconds) {
         return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
     }
+    /**
+     * Parse a `Retry-After` header into a non-negative delay in seconds.
+     *
+     * Per RFC 9110 the value is either delay-seconds (an integer) or an
+     * HTTP-date. Anything that doesn't resolve to a finite, non-negative number
+     * (missing header, garbage, a past date) falls back to `defaultSecs`.
+     */
+    parseRetryAfter(header, defaultSecs = 60) {
+        if (!header)
+            return defaultSecs;
+        // delay-seconds form: a bare integer.
+        const secs = Number(header.trim());
+        if (Number.isFinite(secs))
+            return Math.max(0, secs);
+        // HTTP-date form: compute the delay from now.
+        const dateMs = Date.parse(header);
+        if (Number.isFinite(dateMs)) {
+            return Math.max(0, (dateMs - Date.now()) / 1000);
+        }
+        return defaultSecs;
+    }
+    /**
+     * Backoff delay (in seconds) for a 0-indexed retry attempt: a capped
+     * exponential schedule (0.2s → 5s) with full jitter, so concurrent clients
+     * don't retry in lockstep. Returns a value in [d/2, d].
+     */
+    backoffSeconds(attempt) {
+        const base = 0.2;
+        const max = 5;
+        const d = Math.min(base * Math.pow(2, Math.max(0, attempt)), max);
+        return d / 2 + Math.random() * (d / 2);
+    }
     /**
      * Helper to determine if a path should use JSON
      * Only CRUD operations (insert/update/delete/batch) use MessagePack
@@ -292,10 +339,13 @@ class EkoDBClient {
             }
             // Handle rate limiting (429)
             if (response.status === 429) {
-                const retryAfter = parseInt(response.headers.get("retry-after") || "60", 10);
+                const retryAfter = this.parseRetryAfter(response.headers.get("retry-after"));
                 if (this.shouldRetry && attempt < this.maxRetries) {
-                    console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
-                    await this.sleep(retryAfter);
+                    // Honor the server's Retry-After, but cap it so a hostile/large value
+                    // can't pin the client for minutes.
+                    const wait = Math.min(retryAfter, 60);
+                    console.log(`Rate limited. Retrying after ${wait} seconds...`);
+                    await this.sleep(wait);
                     return this.makeRequest(method, path, data, attempt + 1, forceJson);
                 }
                 throw new RateLimitError(retryAfter);
@@ -311,8 +361,8 @@ class EkoDBClient {
             if (response.status === 503 &&
                 this.shouldRetry &&
                 attempt < this.maxRetries) {
-                const retryDelay = 10;
-                console.log(`Service unavailable. Retrying after ${retryDelay} seconds...`);
+                const retryDelay = this.backoffSeconds(attempt);
+                console.log(`Service unavailable. Retrying after ${retryDelay.toFixed(2)}s...`);
                 await this.sleep(retryDelay);
                 return this.makeRequest(method, path, data, attempt + 1, forceJson);
             }
@@ -325,8 +375,8 @@ class EkoDBClient {
             if (error instanceof TypeError &&
                 this.shouldRetry &&
                 attempt < this.maxRetries) {
-                const retryDelay = 3;
-                console.log(`Network error. Retrying after ${retryDelay} seconds...`);
+                const retryDelay = this.backoffSeconds(attempt);
+                console.log(`Network error. Retrying after ${retryDelay.toFixed(2)}s...`);
                 await this.sleep(retryDelay);
                 return this.makeRequest(method, path, data, attempt + 1, forceJson);
             }
@@ -352,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);
     }
     /**
@@ -378,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
@@ -394,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(","));
@@ -403,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);
     }
     /**
@@ -424,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);
     }
     /**
@@ -442,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,
@@ -459,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);
     }
     /**
@@ -477,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);
     }
     /**
@@ -497,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 });
     }
     /**
@@ -510,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
@@ -520,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
@@ -548,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
@@ -613,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
      */
@@ -637,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
     // ============================================================================
@@ -783,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
@@ -798,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";
     }
     /**
@@ -809,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 };
     }
     /**
@@ -830,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
@@ -839,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
@@ -886,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.
@@ -916,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
@@ -1096,14 +1235,14 @@ 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 }),
@@ -1125,12 +1264,12 @@ class EkoDBClient {
         const stream = new EventStream();
         (async () => {
             try {
-                let token = this.getToken();
+                let token = await this.getToken();
                 if (!token) {
                     await this.refreshToken();
-                    token = this.getToken();
+                    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: {
@@ -1149,13 +1288,12 @@ class EkoDBClient {
                     stream.close();
                     return;
                 }
-                const body = await response.text();
-                for (const line of body.split("\n")) {
+                const emitLine = (line) => {
                     if (!line.startsWith("data:"))
-                        continue;
+                        return;
                     const dataStr = line.slice(5).trim();
                     if (!dataStr)
-                        continue;
+                        return;
                     try {
                         const eventData = JSON.parse(dataStr);
                         if (eventData.error) {
@@ -1184,6 +1322,33 @@ class EkoDBClient {
                     catch {
                         // skip malformed SSE data
                     }
+                };
+                const reader = response.body?.getReader?.();
+                if (reader) {
+                    // True incremental streaming: decode and emit each SSE line as soon as
+                    // it arrives, rather than buffering the entire response body first.
+                    const decoder = new TextDecoder();
+                    let buffer = "";
+                    for (;;) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        buffer += decoder.decode(value, { stream: true });
+                        let nl;
+                        while ((nl = buffer.indexOf("\n")) >= 0) {
+                            emitLine(buffer.slice(0, nl));
+                            buffer = buffer.slice(nl + 1);
+                        }
+                    }
+                    buffer += decoder.decode();
+                    if (buffer)
+                        emitLine(buffer);
+                }
+                else {
+                    // Fallback for environments/tests without a readable body stream.
+                    const body = await response.text();
+                    for (const line of body.split("\n"))
+                        emitLine(line);
                 }
                 stream.close();
             }
@@ -1201,7 +1366,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
@@ -1231,15 +1396,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
@@ -1251,31 +1416,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.
@@ -1292,7 +1457,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
@@ -1330,7 +1495,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
@@ -1346,7 +1511,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
@@ -1359,19 +1524,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
@@ -1480,15 +1645,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
@@ -1736,10 +1901,18 @@ class EkoDBClient {
         return stream;
     }
     /**
-     * Create a WebSocket client
+     * Create a WebSocket client.
+     *
+     * The token is supplied as a provider bound to this client's
+     * {@link getToken}, so every (re)connect re-evaluates (and proactively
+     * refreshes) the auth token instead of snapshotting it once. This means a
+     * reconnect after a token rotation uses the current token.
+     *
+     * @param wsURL - The WebSocket URL (e.g. `wss://host`); `/api/ws` is appended if absent.
+     * @param options - Optional reconnect/timeout tunables.
      */
-    websocket(wsURL) {
-        return new WebSocketClient(wsURL, this.token);
+    websocket(wsURL, options) {
+        return new WebSocketClient(wsURL, () => this.getToken(), options);
     }
     // ========== RAG Helper Methods ==========
     /**
@@ -1988,91 +2161,348 @@ function extractRecordId(record, extraCandidates = []) {
         const val = record[key];
         if (typeof val === "string")
             return val;
-        if (val && typeof val === "object" && "value" in val)
+        // Unwrap only a genuine typed wrapper (both "type" and "value"), matching
+        // getValue's rule so a user object like { value: 1 } isn't mistaken for one.
+        if (val && typeof val === "object" && "type" in val && "value" in val)
             return String(val.value);
     }
     for (const key of ["id", "_id"]) {
         const val = record[key];
         if (typeof val === "string")
             return val;
-        if (val && typeof val === "object" && "value" in val)
+        // Unwrap only a genuine typed wrapper (both "type" and "value"), matching
+        // getValue's rule so a user object like { value: 1 } isn't mistaken for one.
+        if (val && typeof val === "object" && "type" in val && "value" in val)
             return String(val.value);
     }
     return undefined;
 }
 class WebSocketClient {
-    constructor(wsURL, token) {
+    /**
+     * @param wsURL - WebSocket URL; `/api/ws` is appended if absent.
+     * @param token - A static token string OR a {@link TokenProvider} function
+     *   re-evaluated on every (re)connect (so a refreshed token is used after a drop).
+     * @param options - Optional reconnect/timeout tunables.
+     */
+    constructor(wsURL, token, options = {}) {
         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;
+        this.reconnectAttempts = 0;
+        this.reconnecting = false;
+        this.connectPromise = null;
         // Dispatcher state
         this.pendingRequests = new Map();
         this.subscriptions = new Map();
+        /** Bookkeeping so subscriptions can be replayed on reconnect. */
+        this.subscriptionParams = new Map();
         this.chatStreams = new Map();
         this.registerToolsAck = null;
         this.messageCounter = 0;
-        this.wsURL = wsURL;
-        this.token = token;
+        // Strip trailing slashes so appending `/api/ws` can't yield `//api/ws`,
+        // which warp's exact path match (`api / ws`) would reject.
+        this.wsURL = stripTrailingSlashes(wsURL);
+        this.tokenProvider = typeof token === "function" ? token : () => token;
+        this.autoReconnect = options.autoReconnect ?? true;
+        this.reconnectInitialDelayMs = options.reconnectInitialDelayMs ?? 200;
+        this.reconnectMaxDelayMs = options.reconnectMaxDelayMs ?? 5000;
+        this.reconnectMaxAttempts = options.reconnectMaxAttempts ?? 0;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30000;
     }
     genMessageId() {
         const counter = this.messageCounter++;
         return `${Date.now()}-${counter}-${Math.random().toString(36).slice(2, 8)}`;
     }
     /**
-     * Connect and start the dispatcher.
+     * Compute the capped exponential backoff (with jitter) for a reconnect
+     * attempt. attempt 0 -> ~initial, growing x2 each time up to the max cap.
+     * Jitter is +/-25% to avoid thundering-herd reconnect storms.
+     * @internal exposed for testing
+     */
+    computeBackoff(attempt) {
+        const base = Math.min(this.reconnectInitialDelayMs * 2 ** attempt, this.reconnectMaxDelayMs);
+        const jitter = base * 0.25 * (Math.random() * 2 - 1);
+        return Math.max(0, Math.round(base + jitter));
+    }
+    /**
+     * Connect and start the dispatcher. Re-evaluates the token provider so the
+     * current/refreshed token is used for this socket.
      */
     async ensureConnected() {
         if (this.ws && this.dispatcherRunning)
             return;
+        // Coalesce concurrent connect attempts onto a single in-flight promise.
+        if (this.connectPromise)
+            return this.connectPromise;
+        // Clear the intentional-close flag only for user-initiated connects. During
+        // a reconnect cycle this stays untouched so a concurrent close() can't be
+        // undone and have the reconnect proceed against the user's intent.
+        if (!this.reconnecting)
+            this.closed = false;
+        this.connectPromise = this.openSocket().finally(() => {
+            this.connectPromise = null;
+        });
+        return this.connectPromise;
+    }
+    async openSocket() {
         const WebSocket = (await Promise.resolve().then(() => __importStar(require("ws")))).default;
         let url = this.wsURL;
         if (!url.endsWith("/api/ws")) {
             url += "/api/ws";
         }
+        // Re-evaluate the token on every (re)connect — never a stale snapshot.
+        const token = await this.tokenProvider();
+        if (!token) {
+            // Fail fast with a clear error instead of sending `Bearer null`, which
+            // would surface as a confusing 401 from the server.
+            throw new Error("WebSocket auth token is unavailable (the token provider returned null/empty)");
+        }
         this.ws = new WebSocket(url, {
             headers: {
-                Authorization: `Bearer ${this.token}`,
+                Authorization: `Bearer ${token}`,
             },
         });
         await new Promise((resolve, reject) => {
             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;
         this.dispatcherRunning = true;
-        this.ws.on("message", (data) => {
+        // Capture the socket this dispatcher is bound to. After a reconnect, the old
+        // 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, 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 {
                 // Ignore malformed messages
             }
         });
-        this.ws.on("close", () => {
-            this.dispatcherRunning = false;
-            // Notify all pending requests
-            for (const [, pending] of this.pendingRequests) {
-                pending.reject(new Error("WebSocket connection closed"));
-            }
-            this.pendingRequests.clear();
-            // Close all chat streams
-            for (const [, stream] of this.chatStreams) {
-                stream.emit("event", { type: "error", error: "Connection closed" });
-                stream.close();
-            }
-            this.chatStreams.clear();
-            // Close all subscriptions
+        // Both "close" and "error" mean this socket is dead. ws typically emits
+        // "error" followed by "close", so route both through one handler and let the
+        // identity check dedupe: the first to fire nulls this.ws, the second no-ops.
+        const onDown = () => {
+            if (this.ws !== socket)
+                return;
+            this.handleDisconnect();
+        };
+        socket.on("close", onDown);
+        socket.on("error", onDown);
+    }
+    /**
+     * Reject in-flight requests and tear down the dead socket. If the close was
+     * unexpected (not an explicit `close()`) and auto-reconnect is enabled,
+     * schedule a reconnect that re-sends the active subscriptions.
+     */
+    handleDisconnect() {
+        this.dispatcherRunning = false;
+        this.ws = null;
+        // Reject all in-flight pending requests so callers don't hang forever.
+        for (const [, pending] of this.pendingRequests) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(new Error("WebSocket connection closed"));
+        }
+        this.pendingRequests.clear();
+        if (this.registerToolsAck) {
+            this.registerToolsAck.reject(new Error("WebSocket connection closed"));
+            this.registerToolsAck = null;
+        }
+        // Close all chat streams (they are one-shot; not replayed on reconnect).
+        for (const [, stream] of this.chatStreams) {
+            stream.emit("event", { type: "error", error: "Connection closed" });
+            stream.close();
+        }
+        this.chatStreams.clear();
+        const shouldReconnect = this.autoReconnect && !this.closed && this.subscriptionParams.size > 0;
+        if (shouldReconnect) {
+            this.scheduleReconnect();
+        }
+        else {
+            // No reconnect: tear down subscriptions too.
             for (const [, stream] of this.subscriptions) {
                 stream.close();
             }
             this.subscriptions.clear();
-            this.ws = null;
-        });
+            this.subscriptionParams.clear();
+        }
+    }
+    /**
+     * Reconnect with capped exponential backoff + jitter, then re-send the
+     * subscribe messages for every active subscription so the SAME EventStream
+     * keeps delivering mutations after a transient drop.
+     */
+    scheduleReconnect() {
+        if (this.reconnecting)
+            return;
+        this.reconnecting = true;
+        const attempt = async () => {
+            // Bail if the client was closed, or if every subscription was torn down
+            // (e.g. unsubscribed) while a reconnect was in-flight — reconnect was only
+            // opted into because subscriptions existed, so there's nothing to restore.
+            if (this.closed || this.subscriptionParams.size === 0) {
+                this.reconnecting = false;
+                return;
+            }
+            if (this.reconnectMaxAttempts > 0 &&
+                this.reconnectAttempts >= this.reconnectMaxAttempts) {
+                // Give up: tear down subscriptions and notify consumers.
+                this.reconnecting = false;
+                for (const [, stream] of this.subscriptions) {
+                    stream.emit("error", "WebSocket reconnect failed");
+                    stream.close();
+                }
+                this.subscriptions.clear();
+                this.subscriptionParams.clear();
+                return;
+            }
+            const delay = this.computeBackoff(this.reconnectAttempts);
+            this.reconnectAttempts++;
+            await new Promise((r) => setTimeout(r, delay));
+            // Re-check after the backoff delay: close() or a full unsubscribe may have
+            // happened while we were waiting, in which case skip reopening the socket.
+            if (this.closed || this.subscriptionParams.size === 0) {
+                this.reconnecting = false;
+                return;
+            }
+            try {
+                // Route through ensureConnected() so a request-driven connect and this
+                // reconnect share one in-flight connectPromise/socket — opening two live
+                // sockets would misroute responses.
+                await this.ensureConnected();
+                // close() may have been called while the connect was in-flight; if so,
+                // tear down the freshly-opened socket instead of leaving it orphaned.
+                if (this.closed) {
+                    try {
+                        this.ws?.close?.();
+                    }
+                    catch {
+                        /* already closing */
+                    }
+                    this.ws = null;
+                    this.dispatcherRunning = false;
+                    this.reconnecting = false;
+                    return;
+                }
+                // Success — reset backoff and replay subscriptions.
+                this.reconnectAttempts = 0;
+                this.reconnecting = false;
+                await this.resubscribeAll();
+            }
+            catch {
+                // Connect failed — schedule the next attempt WITHOUT recursive await so
+                // a prolonged outage can't build an unbounded promise chain.
+                setTimeout(() => void attempt(), 0);
+            }
+        };
+        void attempt();
+    }
+    /** Re-send Subscribe frames for every tracked subscription after a reconnect. */
+    async resubscribeAll() {
+        for (const [collection, options] of this.subscriptionParams) {
+            const stream = this.subscriptions.get(collection);
+            if (!stream || stream.closed)
+                continue;
+            const messageId = this.genMessageId();
+            const request = {
+                type: "Subscribe",
+                messageId,
+                payload: {
+                    collection,
+                    ...(options?.filterField && { filter_field: options.filterField }),
+                    ...(options?.filterValue && { filter_value: options.filterValue }),
+                },
+            };
+            try {
+                await this.sendRequest(request);
+            }
+            catch {
+                // If the re-subscribe ack fails, leave it tracked; the next
+                // disconnect/reconnect cycle will attempt it again.
+            }
+        }
     }
     routeMessage(msg) {
         switch (msg.type) {
@@ -2085,15 +2515,7 @@ class WebSocketClient {
                     msg.payload?.messageId;
                 let matched = false;
                 if (messageId && this.pendingRequests.has(messageId)) {
-                    const pending = this.pendingRequests.get(messageId);
-                    this.pendingRequests.delete(messageId);
-                    if (msg.type === "Error") {
-                        pending.reject(new Error(msg.message || "Unknown error"));
-                    }
-                    else {
-                        pending.resolve(msg.payload);
-                    }
-                    matched = true;
+                    matched = this.settlePending(messageId, msg.type === "Error", msg);
                 }
                 if (!matched && this.registerToolsAck) {
                     const ack = this.registerToolsAck;
@@ -2106,19 +2528,14 @@ class WebSocketClient {
                     }
                     matched = true;
                 }
-                // Server doesn't echo messageId — if there's exactly one pending
+                // Server doesn't echo messageId at all — if there's exactly one pending
                 // request, deliver the response to it (sequential request/response).
-                if (!matched && this.pendingRequests.size === 1) {
-                    const entry = this.pendingRequests.entries().next().value;
-                    const key = entry[0];
-                    const pending = entry[1];
-                    this.pendingRequests.delete(key);
-                    if (msg.type === "Error") {
-                        pending.reject(new Error(msg.message || "Unknown error"));
-                    }
-                    else {
-                        pending.resolve(msg.payload);
-                    }
+                // Only when messageId is absent: a present-but-unmatched id means a late
+                // response for an already-settled/timed-out request, which must NOT be
+                // misrouted to whatever request happens to still be pending.
+                if (!matched && !messageId && this.pendingRequests.size === 1) {
+                    const key = this.pendingRequests.keys().next().value;
+                    this.settlePending(key, msg.type === "Error", msg);
                 }
                 break;
             }
@@ -2205,16 +2622,46 @@ class WebSocketClient {
         await this.ensureConnected();
         const messageId = request.messageId || request.message_id;
         return new Promise((resolve, reject) => {
-            this.pendingRequests.set(messageId, { resolve, reject });
+            // Per-request timeout: reject if no response arrives in the window so a
+            // dropped/never-answered response can't leave the promise pending forever.
+            let timer;
+            if (this.requestTimeoutMs > 0) {
+                timer = setTimeout(() => {
+                    if (this.pendingRequests.delete(messageId)) {
+                        reject(new Error(`WebSocket request "${request.type}" timed out after ${this.requestTimeoutMs}ms`));
+                    }
+                }, this.requestTimeoutMs);
+                // Don't keep the process alive just for this timer.
+                timer?.unref?.();
+            }
+            this.pendingRequests.set(messageId, { resolve, reject, timer });
             try {
-                this.ws.send(JSON.stringify(request));
+                this.sendFrame(request);
             }
             catch (err) {
                 this.pendingRequests.delete(messageId);
+                if (timer)
+                    clearTimeout(timer);
                 reject(err);
             }
         });
     }
+    /** Resolve/reject a pending request, clearing its timeout timer. */
+    settlePending(messageId, isError, msg) {
+        const pending = this.pendingRequests.get(messageId);
+        if (!pending)
+            return false;
+        this.pendingRequests.delete(messageId);
+        if (pending.timer)
+            clearTimeout(pending.timer);
+        if (isError) {
+            pending.reject(new Error(msg.message || "Unknown error"));
+        }
+        else {
+            pending.resolve(msg.payload);
+        }
+        return true;
+    }
     /**
      * Find all records in a collection via WebSocket.
      */
@@ -2239,6 +2686,8 @@ class WebSocketClient {
         const messageId = this.genMessageId();
         const stream = new EventStream();
         this.subscriptions.set(collection, stream);
+        // Track params so the subscription can be replayed on reconnect.
+        this.subscriptionParams.set(collection, options);
         const request = {
             type: "Subscribe",
             messageId,
@@ -2254,10 +2703,44 @@ class WebSocketClient {
         }
         catch (err) {
             this.subscriptions.delete(collection);
+            this.subscriptionParams.delete(collection);
             throw err;
         }
         return stream;
     }
+    /**
+     * Unsubscribe from a collection's mutation notifications. This is an
+     * intentional teardown, so the subscription is NOT replayed on reconnect.
+     */
+    unsubscribe(collection) {
+        const stream = this.subscriptions.get(collection);
+        this.subscriptions.delete(collection);
+        this.subscriptionParams.delete(collection);
+        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.
      * Returns an EventStream that emits "event" with ChatStreamEvent objects.
@@ -2285,7 +2768,7 @@ class WebSocketClient {
                 ...(options?.excludeTools && { exclude_tools: options.excludeTools }),
             },
         };
-        this.ws.send(JSON.stringify(request));
+        this.sendFrame(request);
         return stream;
     }
     /**
@@ -2305,7 +2788,7 @@ class WebSocketClient {
                 resolve: () => resolve(),
                 reject: (err) => reject(err),
             };
-            this.ws.send(JSON.stringify(request));
+            this.sendFrame(request);
         });
     }
     /**
@@ -2323,7 +2806,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.
@@ -2481,8 +2981,42 @@ class WebSocketClient {
     }
     /**
      * Close the WebSocket connection.
+     *
+     * This is an INTENTIONAL close: it disables auto-reconnect, rejects any
+     * in-flight requests, and tears down all subscriptions/chat streams so
+     * nothing is replayed afterward.
      */
     close() {
+        // Mark intentional so the close handler doesn't trigger a reconnect.
+        this.closed = true;
+        this.reconnecting = false;
+        // Reject any in-flight requests and clear their timers.
+        for (const [, pending] of this.pendingRequests) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(new Error("WebSocket connection closed"));
+        }
+        this.pendingRequests.clear();
+        // Tear down subscriptions + their replay bookkeeping.
+        for (const [, stream] of this.subscriptions) {
+            if (!stream.closed)
+                stream.close();
+        }
+        this.subscriptions.clear();
+        this.subscriptionParams.clear();
+        // Reject any in-flight tool registration ack. Done here (not just in the
+        // ws "close" handler) so it's cleaned up even when this.ws is already null.
+        if (this.registerToolsAck) {
+            this.registerToolsAck.reject(new Error("WebSocket connection closed"));
+            this.registerToolsAck = null;
+        }
+        // Tear down chat streams immediately; they are one-shot and not replayed,
+        // and we can't rely on the underlying ws "close" event having fired.
+        for (const [, stream] of this.chatStreams) {
+            stream.emit("event", { type: "error", error: "Connection closed" });
+            stream.close();
+        }
+        this.chatStreams.clear();
         if (this.ws) {
             this.ws.close();
             this.ws = null;