@ekodb/ekodb-client 0.20.0 → 0.21.0

package/src/client.ts

@@ -3,7 +3,7 @@
  */
 
 import { encode, decode } from "@msgpack/msgpack";
-import { QueryBuilder, Query as QueryBuilderQuery } from "./query-builder";
+import { QueryBuilder, Query } from "./query-builder";
 import { SearchQuery, SearchResponse } from "./search";
 import { Schema, SchemaBuilder, CollectionMetadata } from "./schema";
 import { UserFunction, FunctionResult } from "./functions";
@@ -65,11 +65,11 @@ export class RateLimitError extends Error {
   }
 }
 
-export interface Query {
-  limit?: number;
-  offset?: number;
-  filter?: Record;
-}
+// `Query` is the canonical find/query body shape — the server's FindBody —
+// re-exported from the query builder so the whole client shares a single type
+// (`filter`, `sort`, `limit`, `skip`, `join`, `select_fields`, `exclude_fields`,
+// matching the server exactly). `QueryBuilder.build()` returns this same type.
+export type { Query };
 
 export interface BatchOperationResult {
   successful: string[];
@@ -115,6 +115,24 @@ export interface FindOptions {
   bypassCache?: boolean;
   selectFields?: string[];
   excludeFields?: string[];
+  /**
+   * Read within a transaction (read-your-writes). When set, the read is served
+   * from the transaction's own view — its uncommitted staged writes, else the
+   * committed store — and recorded in the transaction's read set for
+   * commit-time conflict detection. Omit for an ordinary committed read.
+   */
+  transactionId?: string;
+}
+
+/**
+ * Options for a point read by id. `transactionId` enables read-your-writes
+ * within a transaction (see {@link FindOptions.transactionId}).
+ */
+export interface FindByIdOptions {
+  selectFields?: string[];
+  excludeFields?: string[];
+  bypassRipple?: boolean;
+  transactionId?: string;
 }
 
 export interface BatchInsertOptions {
@@ -782,8 +800,8 @@ export class EkoDBClient {
     }
 
     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<Record>("POST", url, data);
   }
@@ -813,20 +831,64 @@ export class EkoDBClient {
   async find(
     collection: string,
     query: Query | QueryBuilder = {},
+    options?: { bypassRipple?: boolean; transactionId?: string },
   ): Promise<Record[]> {
     const queryObj = query instanceof QueryBuilder ? query.build() : query;
-    return this.makeRequest<Record[]>(
-      "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: unknown = queryObj;
+    let bypassRipple = options?.bypassRipple;
+    if (body && typeof body === "object" && "bypass_ripple" in body) {
+      const { bypass_ripple, ...rest } = body as Record & {
+        bypass_ripple?: boolean;
+      };
+      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<Record[]>("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: string, id: string): Promise<Record> {
-    return this.makeRequest<Record>("GET", `/api/find/${collection}/${id}`);
+  async findById(
+    collection: string,
+    id: string,
+    options?: FindByIdOptions,
+  ): Promise<Record> {
+    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<Record>("GET", url);
   }
 
   /**
@@ -835,12 +897,14 @@ export 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: string,
     id: string,
     selectFields?: string[],
     excludeFields?: string[],
+    transactionId?: string,
   ): Promise<Record> {
     const params = new URLSearchParams();
     if (selectFields?.length) {
@@ -849,9 +913,12 @@ export 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<Record>("GET", url);
   }
 
@@ -877,8 +944,8 @@ export class EkoDBClient {
     }
 
     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<Record>("PUT", url, record);
   }
@@ -903,7 +970,7 @@ export class EkoDBClient {
     field: string,
     value?: any,
   ): Promise<Record> {
-    const url = `/api/update/${collection}/${id}/action/${action}`;
+    const url = `/api/update/${encodeURIComponent(collection)}/${encodeURIComponent(id)}/action/${encodeURIComponent(action)}`;
     return this.makeRequest<Record>("PUT", url, {
       field,
       value: value ?? null,
@@ -925,7 +992,7 @@ export class EkoDBClient {
     id: string,
     actions: [string, string, any][],
   ): Promise<Record> {
-    const url = `/api/update/sequence/${collection}/${id}`;
+    const url = `/api/update/sequence/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`;
     return this.makeRequest<Record>("PUT", url, actions);
   }
 
@@ -949,8 +1016,8 @@ export class EkoDBClient {
     }
 
     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<void>("DELETE", url);
   }
@@ -976,8 +1043,8 @@ export 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<BatchOperationResult>("POST", url, { inserts });
   }
@@ -996,7 +1063,7 @@ export class EkoDBClient {
     }));
     return this.makeRequest<BatchOperationResult>(
       "PUT",
-      `/api/batch/update/${collection}`,
+      `/api/batch/update/${encodeURIComponent(collection)}`,
       { updates: formattedUpdates },
     );
   }
@@ -1015,7 +1082,7 @@ export class EkoDBClient {
     }));
     return this.makeRequest<BatchOperationResult>(
       "DELETE",
-      `/api/batch/delete/${collection}`,
+      `/api/batch/delete/${encodeURIComponent(collection)}`,
       { deletes },
     );
   }
@@ -1067,6 +1134,19 @@ export class EkoDBClient {
     );
   }
 
+  /**
+   * Clear the entire KV store (all keys in the namespace).
+   */
+  async kvClear(): Promise<void> {
+    await this.makeRequest<void>(
+      "DELETE",
+      "/api/kv/clear",
+      undefined,
+      0,
+      true, // Force JSON for KV operations
+    );
+  }
+
   /**
    * Batch get multiple keys
    * @param keys - Array of keys to retrieve
@@ -1171,7 +1251,18 @@ export class EkoDBClient {
   // ============================================================================
 
   /**
-   * 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
    */
@@ -1220,7 +1311,7 @@ export class EkoDBClient {
   }
 
   /**
-   * Rollback a transaction
+   * Rollback a transaction (discards all staged writes; nothing was applied).
    * @param transactionId - The transaction ID to rollback
    */
   async rollbackTransaction(transactionId: string): Promise<void> {
@@ -1233,6 +1324,49 @@ export class EkoDBClient {
     );
   }
 
+  /**
+   * Create a savepoint within a transaction. A later
+   * {@link rollbackToSavepoint} discards everything staged after it.
+   */
+  async createSavepoint(transactionId: string, name: string): Promise<void> {
+    await this.makeRequest<void>(
+      "POST",
+      `/api/transactions/${encodeURIComponent(transactionId)}/savepoints`,
+      { name },
+      0,
+      true,
+    );
+  }
+
+  /**
+   * Roll the transaction back to a savepoint, discarding writes staged after it.
+   */
+  async rollbackToSavepoint(
+    transactionId: string,
+    name: string,
+  ): Promise<void> {
+    await this.makeRequest<void>(
+      "POST",
+      `/api/transactions/${encodeURIComponent(transactionId)}/savepoints/${encodeURIComponent(name)}/rollback`,
+      undefined,
+      0,
+      true,
+    );
+  }
+
+  /**
+   * Release (forget) a savepoint. Staged work is unaffected.
+   */
+  async releaseSavepoint(transactionId: string, name: string): Promise<void> {
+    await this.makeRequest<void>(
+      "DELETE",
+      `/api/transactions/${encodeURIComponent(transactionId)}/savepoints/${encodeURIComponent(name)}`,
+      undefined,
+      0,
+      true,
+    );
+  }
+
   // ============================================================================
   // Convenience Methods
   // ============================================================================
@@ -1379,7 +1513,7 @@ export class EkoDBClient {
   ): Promise<Record[]> {
     // Page 1 = skip 0, Page 2 = skip pageSize, etc.
     const skip = page > 0 ? (page - 1) * pageSize : 0;
-    const query: QueryBuilderQuery = {
+    const query: Query = {
       limit: pageSize,
       skip: skip,
     };
@@ -1400,13 +1534,27 @@ export class EkoDBClient {
     return result.collections;
   }
 
+  /**
+   * List collections, excluding internal chat/system collections.
+   */
+  async listUserCollections(): Promise<string[]> {
+    const result = await this.makeRequest<{ collections: string[] }>(
+      "GET",
+      "/api/collections?exclude_internal=true",
+      undefined,
+      0,
+      true, // Force JSON for metadata operations
+    );
+    return result.collections;
+  }
+
   /**
    * Delete a collection
    */
   async deleteCollection(collection: string): Promise<void> {
     await this.makeRequest<void>(
       "DELETE",
-      `/api/collections/${collection}`,
+      `/api/collections/${encodeURIComponent(collection)}`,
       undefined,
       0,
       true, // Force JSON for metadata operations
@@ -1424,7 +1572,7 @@ export class EkoDBClient {
   async restoreRecord(collection: string, id: string): Promise<boolean> {
     const result = await this.makeRequest<{ status: string }>(
       "POST",
-      `/api/trash/${collection}/${id}`,
+      `/api/trash/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`,
       undefined,
       0,
       true,
@@ -1446,7 +1594,13 @@ export class EkoDBClient {
       status: string;
       collection: string;
       records_restored: number;
-    }>("POST", `/api/trash/${collection}`, undefined, 0, true);
+    }>(
+      "POST",
+      `/api/trash/${encodeURIComponent(collection)}`,
+      undefined,
+      0,
+      true,
+    );
     return { recordsRestored: result.records_restored };
   }
 
@@ -1473,7 +1627,7 @@ export class EkoDBClient {
     const schemaObj = schema instanceof SchemaBuilder ? schema.build() : schema;
     await this.makeRequest<void>(
       "POST",
-      `/api/collections/${collection}`,
+      `/api/collections/${encodeURIComponent(collection)}`,
       schemaObj,
       0,
       true, // Force JSON for metadata operations
@@ -1489,7 +1643,7 @@ export class EkoDBClient {
   async getCollection(collection: string): Promise<CollectionMetadata> {
     return this.makeRequest<CollectionMetadata>(
       "GET",
-      `/api/collections/${collection}`,
+      `/api/collections/${encodeURIComponent(collection)}`,
       undefined,
       0,
       true, // Force JSON for metadata operations
@@ -1547,7 +1701,7 @@ export class EkoDBClient {
     // Ensure all parameters from SearchQuery are sent to server
     return this.makeRequest<SearchResponse>(
       "POST",
-      `/api/search/${collection}`,
+      `/api/search/${encodeURIComponent(collection)}`,
       query,
       0,
       true, // Force JSON for search operations
@@ -1592,7 +1746,7 @@ export class EkoDBClient {
 
     return this.makeRequest<DistinctValuesResponse>(
       "POST",
-      `/api/distinct/${collection}/${field}`,
+      `/api/distinct/${encodeURIComponent(collection)}/${encodeURIComponent(field)}`,
       body,
       0,
       true, // Force JSON
@@ -1828,7 +1982,7 @@ export class EkoDBClient {
   ): Promise<ChatResponse> {
     return this.makeRequest<ChatResponse>(
       "POST",
-      `/api/chat/${sessionId}/messages`,
+      `/api/chat/${encodeURIComponent(sessionId)}/messages`,
       request,
       0,
       true, // Force JSON for chat operations
@@ -1848,7 +2002,7 @@ export class EkoDBClient {
   ): Promise<void> {
     await this.makeRequest(
       "POST",
-      `/api/chat/${chatId}/tool-result`,
+      `/api/chat/${encodeURIComponent(chatId)}/tool-result`,
       {
         call_id: callId,
         success,
@@ -1884,7 +2038,7 @@ export 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",
@@ -1979,7 +2133,7 @@ export class EkoDBClient {
   async getChatSession(sessionId: string): Promise<ChatSessionResponse> {
     return this.makeRequest<ChatSessionResponse>(
       "GET",
-      `/api/chat/${sessionId}`,
+      `/api/chat/${encodeURIComponent(sessionId)}`,
       undefined,
       0,
       true, // Force JSON for chat operations
@@ -2022,8 +2176,8 @@ export class EkoDBClient {
 
     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<GetMessagesResponse>(
       "GET",
       path,
@@ -2042,7 +2196,7 @@ export class EkoDBClient {
   ): Promise<ChatSessionResponse> {
     return this.makeRequest<ChatSessionResponse>(
       "PUT",
-      `/api/chat/${sessionId}`,
+      `/api/chat/${encodeURIComponent(sessionId)}`,
       request,
       0,
       true, // Force JSON for chat operations
@@ -2070,7 +2224,7 @@ export class EkoDBClient {
   async deleteChatSession(sessionId: string): Promise<void> {
     await this.makeRequest<void>(
       "DELETE",
-      `/api/chat/${sessionId}`,
+      `/api/chat/${encodeURIComponent(sessionId)}`,
       undefined,
       0,
       true, // Force JSON for chat operations
@@ -2086,7 +2240,7 @@ export class EkoDBClient {
   ): Promise<ChatResponse> {
     return this.makeRequest<ChatResponse>(
       "POST",
-      `/api/chat/${sessionId}/messages/${messageId}/regenerate`,
+      `/api/chat/${encodeURIComponent(sessionId)}/messages/${encodeURIComponent(messageId)}/regenerate`,
       undefined,
       0,
       true, // Force JSON for chat operations
@@ -2103,7 +2257,7 @@ export class EkoDBClient {
   ): Promise<void> {
     await this.makeRequest<void>(
       "PUT",
-      `/api/chat/${sessionId}/messages/${messageId}`,
+      `/api/chat/${encodeURIComponent(sessionId)}/messages/${encodeURIComponent(messageId)}`,
       { content },
       0,
       true, // Force JSON for chat operations
@@ -2116,7 +2270,7 @@ export class EkoDBClient {
   async deleteChatMessage(sessionId: string, messageId: string): Promise<void> {
     await this.makeRequest<void>(
       "DELETE",
-      `/api/chat/${sessionId}/messages/${messageId}`,
+      `/api/chat/${encodeURIComponent(sessionId)}/messages/${encodeURIComponent(messageId)}`,
       undefined,
       0,
       true, // Force JSON for chat operations
@@ -2133,7 +2287,7 @@ export class EkoDBClient {
   ): Promise<void> {
     await this.makeRequest<void>(
       "PATCH",
-      `/api/chat/${sessionId}/messages/${messageId}/forgotten`,
+      `/api/chat/${encodeURIComponent(sessionId)}/messages/${encodeURIComponent(messageId)}/forgotten`,
       { forgotten },
       0,
       true, // Force JSON for chat operations
@@ -2160,7 +2314,7 @@ export class EkoDBClient {
     }
     return this.makeRequest<CompactChatResponse>(
       "POST",
-      `/api/chat/${chatId}/compact`,
+      `/api/chat/${encodeURIComponent(chatId)}/compact`,
       body,
       0,
       true, // Force JSON for chat operations
@@ -2235,7 +2389,7 @@ export class EkoDBClient {
   async getChatMessage(sessionId: string, messageId: string): Promise<Record> {
     return this.makeRequest<Record>(
       "GET",
-      `/api/chat/${sessionId}/messages/${messageId}`,
+      `/api/chat/${encodeURIComponent(sessionId)}/messages/${encodeURIComponent(messageId)}`,
       undefined,
       0,
       true, // Force JSON for chat operations
@@ -2262,7 +2416,10 @@ export class EkoDBClient {
    * Get a function by ID
    */
   async getFunction(id: string): Promise<UserFunction> {
-    return this.makeRequest<UserFunction>("GET", `/api/functions/${id}`);
+    return this.makeRequest<UserFunction>(
+      "GET",
+      `/api/functions/${encodeURIComponent(id)}`,
+    );
   }
 
   /**
@@ -2277,14 +2434,21 @@ export class EkoDBClient {
    * Update an existing function by ID
    */
   async updateFunction(id: string, script: UserFunction): Promise<void> {
-    await this.makeRequest<void>("PUT", `/api/functions/${id}`, script);
+    await this.makeRequest<void>(
+      "PUT",
+      `/api/functions/${encodeURIComponent(id)}`,
+      script,
+    );
   }
 
   /**
    * Delete a function by ID
    */
   async deleteFunction(id: string): Promise<void> {
-    await this.makeRequest<void>("DELETE", `/api/functions/${id}`);
+    await this.makeRequest<void>(
+      "DELETE",
+      `/api/functions/${encodeURIComponent(id)}`,
+    );
   }
 
   /**
@@ -2296,7 +2460,7 @@ export class EkoDBClient {
   ): Promise<FunctionResult> {
     return this.makeRequest<FunctionResult>(
       "POST",
-      `/api/functions/${idOrLabel}`,
+      `/api/functions/${encodeURIComponent(idOrLabel)}`,
       params || {},
     );
   }
@@ -2543,7 +2707,7 @@ export class EkoDBClient {
   async goalStepStart(id: string, stepIndex: number): Promise<Record> {
     return this.makeRequest<Record>(
       "POST",
-      `/api/chat/goals/${encodeURIComponent(id)}/steps/${stepIndex}/start`,
+      `/api/chat/goals/${encodeURIComponent(id)}/steps/${encodeURIComponent(String(stepIndex))}/start`,
       undefined,
       0,
       true,
@@ -2558,7 +2722,7 @@ export class EkoDBClient {
   ): Promise<Record> {
     return this.makeRequest<Record>(
       "POST",
-      `/api/chat/goals/${encodeURIComponent(id)}/steps/${stepIndex}/complete`,
+      `/api/chat/goals/${encodeURIComponent(id)}/steps/${encodeURIComponent(String(stepIndex))}/complete`,
       data,
       0,
       true,
@@ -2573,7 +2737,7 @@ export class EkoDBClient {
   ): Promise<Record> {
     return this.makeRequest<Record>(
       "POST",
-      `/api/chat/goals/${encodeURIComponent(id)}/steps/${stepIndex}/fail`,
+      `/api/chat/goals/${encodeURIComponent(id)}/steps/${encodeURIComponent(String(stepIndex))}/fail`,
       data,
       0,
       true,
@@ -3446,6 +3610,13 @@ export class WebSocketClient {
   private ws: any = null;
   private dispatcherRunning = false;
   private schemaCache: SchemaCache | null = 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.
+   */
+  private binary = false;
 
   // Reconnect config
   private autoReconnect: boolean;
@@ -3572,9 +3743,72 @@ export class WebSocketClient {
       this.ws.on("error", (err: Error) => 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.
+   */
+  private async negotiateFormat(socket: any): Promise<void> {
+    this.binary = false;
+    const welcome = await new Promise<any | null>((resolve) => {
+      const onMsg = (data: Buffer) => {
+        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.
+   */
+  private sendFrame(obj: any): void {
+    this.ws.send(this.binary ? encode(obj) : JSON.stringify(obj));
+  }
+
   private spawnDispatcher(): void {
     if (this.dispatcherRunning) return;
     this.dispatcherRunning = true;
@@ -3584,10 +3818,15 @@ export class WebSocketClient {
     // tear down the replacement connection.
     const socket = this.ws;
 
-    socket.on("message", (data: Buffer) => {
+    socket.on("message", (data: Buffer, isBinary: boolean) => {
       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
+          ? (decode(data) as any)
+          : JSON.parse(data.toString());
         this.routeMessage(msg);
       } catch {
         // Ignore malformed messages
@@ -3897,7 +4136,7 @@ export 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);
         if (timer) clearTimeout(timer);
@@ -3989,6 +4228,26 @@ export 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.
+      }
+    }
   }
 
   /**
@@ -4026,7 +4285,7 @@ export class WebSocketClient {
       },
     };
 
-    this.ws.send(JSON.stringify(request));
+    this.sendFrame(request);
     return stream;
   }
 
@@ -4052,7 +4311,7 @@ export class WebSocketClient {
         resolve: () => resolve(),
         reject: (err) => reject(err),
       };
-      this.ws.send(JSON.stringify(request));
+      this.sendFrame(request);
     });
   }
 
@@ -4079,7 +4338,27 @@ export class WebSocketClient {
       },
     };
 
-    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: string): Promise<void> {
+    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);
   }
 
   /**