@ekodb/ekodb-client 0.12.0 → 0.14.0

package/dist/client.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketClient = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = exports.SerializationFormat = void 0;
+exports.WebSocketClient = exports.EventStream = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = exports.SerializationFormat = void 0;
 const msgpack_1 = require("@msgpack/msgpack");
 const query_builder_1 = require("./query-builder");
 const schema_1 = require("./schema");
@@ -71,6 +71,7 @@ var MergeStrategy;
 class EkoDBClient {
     constructor(config, apiKey) {
         this.token = null;
+        this.tokenExpiry = 0;
         this.rateLimitInfo = null;
         // Support both old (baseURL, apiKey) and new (config object) signatures
         if (typeof config === "string") {
@@ -78,7 +79,6 @@ class EkoDBClient {
             this.apiKey = apiKey;
             this.shouldRetry = true;
             this.maxRetries = 3;
-            this.timeout = 30000;
             this.format = SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
         }
         else {
@@ -86,7 +86,6 @@ class EkoDBClient {
             this.apiKey = config.apiKey;
             this.shouldRetry = config.shouldRetry ?? true;
             this.maxRetries = config.maxRetries ?? 3;
-            this.timeout = config.timeout ?? 30000;
             this.format = config.format ?? SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
         }
     }
@@ -135,6 +134,68 @@ class EkoDBClient {
         }
         const result = (await response.json());
         this.token = result.token;
+        // Extract and cache JWT expiry for proactive refresh
+        const expiry = this.extractJWTExpiry(result.token);
+        this.tokenExpiry = expiry ?? Math.floor(Date.now() / 1000) + 3600; // fallback: 1 hour
+    }
+    /**
+     * Get a valid authentication token.
+     *
+     * Returns a cached token if it has more than 60s of validity remaining.
+     * Otherwise fetches a new one via refreshToken(). This means callers
+     * never need to handle token refresh themselves — every getToken() call
+     * returns a token that's valid for at least 60 more seconds.
+     */
+    async getToken() {
+        if (this.token) {
+            const now = Math.floor(Date.now() / 1000);
+            if (now + 60 >= this.tokenExpiry) {
+                // Token is about to expire or already expired — refresh proactively
+                await this.refreshToken();
+            }
+        }
+        else {
+            // No token yet — fetch one
+            await this.refreshToken();
+        }
+        return this.token;
+    }
+    /**
+     * Clear the cached authentication token and expiry.
+     * The next request will trigger a fresh token exchange.
+     */
+    clearTokenCache() {
+        this.token = null;
+        this.tokenExpiry = 0;
+    }
+    /**
+     * Extract the `exp` claim from a JWT without verifying the signature.
+     * Returns the Unix timestamp (seconds) of expiry, or null if parsing fails.
+     */
+    extractJWTExpiry(token) {
+        try {
+            const parts = token.split(".");
+            if (parts.length !== 3) {
+                return null;
+            }
+            // Convert base64url to standard base64
+            let payload = parts[1];
+            payload = payload.replace(/-/g, "+").replace(/_/g, "/");
+            // Pad to multiple of 4
+            const pad = payload.length % 4;
+            if (pad) {
+                payload += "=".repeat(4 - pad);
+            }
+            const decoded = atob(payload);
+            const claims = JSON.parse(decoded);
+            if (typeof claims.exp === "number") {
+                return claims.exp;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
     }
     /**
      * Extract rate limit information from response headers
@@ -326,6 +387,26 @@ class EkoDBClient {
     async findById(collection, id) {
         return this.makeRequest("GET", `/api/find/${collection}/${id}`);
     }
+    /**
+     * Find a document by ID with field projection
+     * @param collection - Collection name
+     * @param id - Document ID
+     * @param selectFields - Fields to include in the result
+     * @param excludeFields - Fields to exclude from the result
+     */
+    async findByIdWithProjection(collection, id, selectFields, excludeFields) {
+        const params = new URLSearchParams();
+        if (selectFields?.length) {
+            params.append("select_fields", selectFields.join(","));
+        }
+        if (excludeFields?.length) {
+            params.append("exclude_fields", excludeFields.join(","));
+        }
+        const url = params.toString()
+            ? `/api/find/${collection}/${id}?${params.toString()}`
+            : `/api/find/${collection}/${id}`;
+        return this.makeRequest("GET", url);
+    }
     /**
      * Update a document
      * @param collection - Collection name
@@ -346,6 +427,40 @@ class EkoDBClient {
             : `/api/update/${collection}/${id}`;
         return this.makeRequest("PUT", url, record);
     }
+    /**
+     * Apply an atomic field action to a single field of a record.
+     *
+     * Use this instead of `update()` for safe concurrent modifications like
+     * incrementing counters, pushing to arrays, or arithmetic operations.
+     *
+     * @param collection - Collection name
+     * @param id - Record ID
+     * @param action - The atomic action: increment, decrement, multiply, divide, modulo,
+     *                 push, pop, shift, unshift, remove, append, clear
+     * @param field - The field name to apply the action to
+     * @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}`;
+        return this.makeRequest("PUT", url, {
+            field,
+            value: value ?? null,
+        });
+    }
+    /**
+     * Apply a sequence of atomic field actions to a record in a single request.
+     *
+     * All actions are applied atomically — the record is fetched once, all actions
+     * run in order, and the result is persisted in a single update.
+     *
+     * @param collection - Collection name
+     * @param id - Record ID
+     * @param actions - Array of [action, field, value] tuples
+     */
+    async updateWithActionSequence(collection, id, actions) {
+        const url = `/api/update/sequence/${collection}/${id}`;
+        return this.makeRequest("PUT", url, actions);
+    }
     /**
      * Delete a document
      * @param collection - Collection name
@@ -772,6 +887,36 @@ class EkoDBClient {
         // Ensure all parameters from SearchQuery are sent to server
         return this.makeRequest("POST", `/api/search/${collection}`, query, 0, true);
     }
+    /**
+     * Get distinct (unique) values for a field across all records in a collection.
+     *
+     * Results are deduplicated and sorted alphabetically. Supports an optional filter
+     * to restrict which records are examined.
+     *
+     * @param collection - Collection name
+     * @param field - Field to get distinct values for
+     * @param options - Optional filter and bypass flags
+     *
+     * @example
+     * // All distinct statuses
+     * const resp = await client.distinctValues("orders", "status");
+     * console.log(resp.values); // ["active", "cancelled", "shipped"]
+     *
+     * // Only statuses for US orders
+     * const resp = await client.distinctValues("orders", "status", {
+     *   filter: { type: "Condition", content: { field: "region", operator: "Eq", value: "us" } }
+     * });
+     */
+    async distinctValues(collection, field, options = {}) {
+        const body = {};
+        if (options.filter !== undefined)
+            body.filter = options.filter;
+        if (options.bypassRipple !== undefined)
+            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);
+    }
     /**
      * Health check - verify the ekoDB server is responding
      */
@@ -791,12 +936,217 @@ class EkoDBClient {
     async createChatSession(request) {
         return this.makeRequest("POST", "/api/chat", request, 0, true);
     }
+    /**
+     * Stateless raw LLM completion — no session, no history, no RAG.
+     *
+     * Sends a system prompt and user message directly to the LLM via ekoDB
+     * and returns the raw text response without any context injection or
+     * conversation management. Use this for structured-output tasks such as
+     * planning where the response must be parsed programmatically.
+     *
+     * @example
+     * const resp = await client.rawCompletion({
+     *   system_prompt: "You are a helpful assistant.",
+     *   message: "Summarize this in JSON.",
+     *   max_tokens: 2048,
+     * });
+     * console.log(resp.content);
+     */
+    async rawCompletion(request) {
+        return this.makeRequest("POST", "/api/chat/complete", request, 0, true);
+    }
+    /**
+     * Stateless raw LLM completion via SSE streaming.
+     *
+     * Same as rawCompletion() but uses Server-Sent Events to keep the
+     * connection alive. Preferred for deployed instances where reverse proxies
+     * may kill idle HTTP connections before the LLM responds.
+     */
+    async rawCompletionStream(request) {
+        let token = await this.getToken();
+        const url = `${this.baseURL}/api/chat/complete/stream`;
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "text/event-stream",
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`SSE raw completion failed (${response.status}): ${body}`);
+        }
+        const body = await response.text();
+        let content = "";
+        let lastError = null;
+        for (const line of body.split("\n")) {
+            if (line.startsWith("data:")) {
+                const dataStr = line.slice(5).trim();
+                if (!dataStr)
+                    continue;
+                try {
+                    const eventData = JSON.parse(dataStr);
+                    if (eventData.token)
+                        content += eventData.token;
+                    if (eventData.content)
+                        content = eventData.content;
+                    if (eventData.error)
+                        lastError = eventData.error;
+                }
+                catch {
+                    // skip malformed SSE data
+                }
+            }
+        }
+        if (lastError)
+            throw new Error(lastError);
+        return { content };
+    }
+    /**
+     * Stateless raw LLM completion via SSE streaming with token-level progress.
+     *
+     * Same as rawCompletionStream() but invokes `onToken` with each token as it
+     * arrives, allowing callers to show real-time progress.
+     */
+    async rawCompletionStreamWithProgress(request, onToken) {
+        let token = await this.getToken();
+        const url = `${this.baseURL}/api/chat/complete/stream`;
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "text/event-stream",
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`SSE raw completion failed (${response.status}): ${body}`);
+        }
+        const body = await response.text();
+        let content = "";
+        let lastError = null;
+        for (const line of body.split("\n")) {
+            if (line.startsWith("data:")) {
+                const dataStr = line.slice(5).trim();
+                if (!dataStr)
+                    continue;
+                try {
+                    const eventData = JSON.parse(dataStr);
+                    if (eventData.token) {
+                        content += eventData.token;
+                        onToken(eventData.token);
+                    }
+                    if (eventData.content)
+                        content = eventData.content;
+                    if (eventData.error)
+                        lastError = eventData.error;
+                }
+                catch {
+                    // skip malformed SSE data
+                }
+            }
+        }
+        if (lastError)
+            throw new Error(lastError);
+        return { content };
+    }
     /**
      * Send a message in an existing chat session
      */
     async chatMessage(sessionId, request) {
         return this.makeRequest("POST", `/api/chat/${sessionId}/messages`, request, 0, true);
     }
+    /**
+     * Send a message in an existing chat session via SSE streaming.
+     *
+     * Returns an EventStream that emits ChatStreamEvent objects as they arrive:
+     * - `{ type: "chunk", content: "..." }` for each token
+     * - `{ type: "end", messageId, executionTimeMs, tokenUsage?, contextWindow? }` when complete
+     * - `{ type: "error", error: "..." }` on failure
+     *
+     * Preferred over chatMessage() for long-running responses where reverse
+     * proxies may kill idle HTTP connections before the LLM responds.
+     */
+    chatMessageStream(chatId, request) {
+        const stream = new EventStream();
+        (async () => {
+            try {
+                let token = this.getToken();
+                if (!token) {
+                    await this.refreshToken();
+                    token = this.getToken();
+                }
+                const url = `${this.baseURL}/api/chat/${chatId}/messages/stream`;
+                const response = await fetch(url, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Accept: "text/event-stream",
+                        Authorization: `Bearer ${token}`,
+                    },
+                    body: JSON.stringify(request),
+                });
+                if (!response.ok) {
+                    const body = await response.text();
+                    stream.emit("event", {
+                        type: "error",
+                        error: `SSE chat message stream failed (${response.status}): ${body}`,
+                    });
+                    stream.close();
+                    return;
+                }
+                const body = await response.text();
+                for (const line of body.split("\n")) {
+                    if (!line.startsWith("data:"))
+                        continue;
+                    const dataStr = line.slice(5).trim();
+                    if (!dataStr)
+                        continue;
+                    try {
+                        const eventData = JSON.parse(dataStr);
+                        if (eventData.error) {
+                            stream.emit("event", {
+                                type: "error",
+                                error: eventData.error,
+                            });
+                        }
+                        else if (eventData.content && eventData.message_id) {
+                            // Done event — has full content + message_id
+                            stream.emit("event", {
+                                type: "end",
+                                messageId: eventData.message_id,
+                                executionTimeMs: eventData.execution_time_ms ?? 0,
+                                tokenUsage: eventData.token_usage,
+                                contextWindow: eventData.context_window,
+                            });
+                        }
+                        else if (eventData.token) {
+                            stream.emit("event", {
+                                type: "chunk",
+                                content: eventData.token,
+                            });
+                        }
+                    }
+                    catch {
+                        // skip malformed SSE data
+                    }
+                }
+                stream.close();
+            }
+            catch (err) {
+                stream.emit("event", {
+                    type: "error",
+                    error: err.message ?? String(err),
+                });
+                stream.close();
+            }
+        })();
+        return stream;
+    }
     /**
      * Get a chat session by ID
      */
@@ -890,6 +1240,14 @@ class EkoDBClient {
     async getChatModels() {
         return this.makeRequest("GET", "/api/chat_models", undefined, 0, true);
     }
+    /**
+     * Get all built-in server-side chat tool definitions.
+     * Returns a list of tool objects with name, description, and parameters fields.
+     * Used by planning agents to discover available tools dynamically.
+     */
+    async getChatTools() {
+        return this.makeRequest("GET", "/api/chat/tools", undefined, 0, true);
+    }
     /**
      * Get available models for a specific provider
      * @param provider - Provider name (e.g., "openai", "anthropic", "perplexity")
@@ -993,6 +1351,204 @@ class EkoDBClient {
         await this.makeRequest("DELETE", `/api/functions/${encodeURIComponent(label)}`, undefined, 0, true);
     }
     // ========================================================================
+    // GOAL API
+    // ========================================================================
+    /** Create a new goal */
+    async goalCreate(data) {
+        return this.makeRequest("POST", "/api/chat/goals", data, 0, true);
+    }
+    /** List all goals */
+    async goalList() {
+        return this.makeRequest("GET", "/api/chat/goals", undefined, 0, true);
+    }
+    /** Get a goal by ID */
+    async goalGet(id) {
+        return this.makeRequest("GET", `/api/chat/goals/${encodeURIComponent(id)}`, undefined, 0, true);
+    }
+    /** Update a goal by ID */
+    async goalUpdate(id, data) {
+        return this.makeRequest("PUT", `/api/chat/goals/${encodeURIComponent(id)}`, data, 0, true);
+    }
+    /** Delete a goal by ID */
+    async goalDelete(id) {
+        await this.makeRequest("DELETE", `/api/chat/goals/${encodeURIComponent(id)}`, undefined, 0, true);
+    }
+    // ── Goal Templates ──
+    /** Create a new goal template */
+    async goalTemplateCreate(data) {
+        return this.makeRequest("POST", "/api/chat/goal-templates", data, 0, true);
+    }
+    /** List all goal templates */
+    async goalTemplateList() {
+        return this.makeRequest("GET", "/api/chat/goal-templates", undefined, 0, true);
+    }
+    /** Get a goal template by ID */
+    async goalTemplateGet(id) {
+        return this.makeRequest("GET", `/api/chat/goal-templates/${encodeURIComponent(id)}`, undefined, 0, true);
+    }
+    /** Update a goal template by ID */
+    async goalTemplateUpdate(id, data) {
+        return this.makeRequest("PUT", `/api/chat/goal-templates/${encodeURIComponent(id)}`, data, 0, true);
+    }
+    /** Delete a goal template by ID */
+    async goalTemplateDelete(id) {
+        await this.makeRequest("DELETE", `/api/chat/goal-templates/${encodeURIComponent(id)}`, undefined, 0, true);
+    }
+    /** Search goals */
+    async goalSearch(query) {
+        const params = new URLSearchParams({ q: query });
+        return this.makeRequest("GET", `/api/chat/goals/search?${params}`, undefined, 0, true);
+    }
+    /** Mark a goal as complete (status -> pending_review) */
+    async goalComplete(id, data) {
+        return this.makeRequest("POST", `/api/chat/goals/${encodeURIComponent(id)}/complete`, data, 0, true);
+    }
+    /** Approve a goal (status -> in_progress) */
+    async goalApprove(id) {
+        return this.makeRequest("POST", `/api/chat/goals/${encodeURIComponent(id)}/approve`, undefined, 0, true);
+    }
+    /** Reject a goal (status -> failed) */
+    async goalReject(id, data) {
+        return this.makeRequest("POST", `/api/chat/goals/${encodeURIComponent(id)}/reject`, data, 0, true);
+    }
+    /** 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);
+    }
+    /** 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);
+    }
+    /** 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);
+    }
+    // ========================================================================
+    // TASK API
+    // ========================================================================
+    /** Create a new scheduled task */
+    async taskCreate(data) {
+        return this.makeRequest("POST", "/api/chat/tasks", data, 0, true);
+    }
+    /** List all scheduled tasks */
+    async taskList() {
+        return this.makeRequest("GET", "/api/chat/tasks", undefined, 0, true);
+    }
+    /** Get a task by ID */
+    async taskGet(id) {
+        return this.makeRequest("GET", `/api/chat/tasks/${encodeURIComponent(id)}`, undefined, 0, true);
+    }
+    /** Update a task by ID */
+    async taskUpdate(id, data) {
+        return this.makeRequest("PUT", `/api/chat/tasks/${encodeURIComponent(id)}`, data, 0, true);
+    }
+    /** Delete a task by ID */
+    async taskDelete(id) {
+        await this.makeRequest("DELETE", `/api/chat/tasks/${encodeURIComponent(id)}`, undefined, 0, true);
+    }
+    /** Get tasks that are due at the given time */
+    async taskDue(now) {
+        const params = new URLSearchParams({ now });
+        return this.makeRequest("GET", `/api/chat/tasks/due?${params}`, undefined, 0, true);
+    }
+    /** Start a task (status -> running) */
+    async taskStart(id) {
+        return this.makeRequest("POST", `/api/chat/tasks/${encodeURIComponent(id)}/start`, undefined, 0, true);
+    }
+    /** Mark a task as succeeded */
+    async taskSucceed(id, data) {
+        return this.makeRequest("POST", `/api/chat/tasks/${encodeURIComponent(id)}/succeed`, data, 0, true);
+    }
+    /** Mark a task as failed */
+    async taskFail(id, data) {
+        return this.makeRequest("POST", `/api/chat/tasks/${encodeURIComponent(id)}/fail`, data, 0, true);
+    }
+    /** Pause a task */
+    async taskPause(id) {
+        return this.makeRequest("POST", `/api/chat/tasks/${encodeURIComponent(id)}/pause`, undefined, 0, true);
+    }
+    /** Resume a paused task */
+    async taskResume(id, data) {
+        return this.makeRequest("POST", `/api/chat/tasks/${encodeURIComponent(id)}/resume`, data, 0, true);
+    }
+    // ========================================================================
+    // AGENT API
+    // ========================================================================
+    /** Create a new agent */
+    async agentCreate(data) {
+        return this.makeRequest("POST", "/api/chat/agents", data, 0, true);
+    }
+    /** List all agents */
+    async agentList() {
+        return this.makeRequest("GET", "/api/chat/agents", undefined, 0, true);
+    }
+    /** Get an agent by ID */
+    async agentGet(id) {
+        return this.makeRequest("GET", `/api/chat/agents/${encodeURIComponent(id)}`, undefined, 0, true);
+    }
+    /** Get an agent by name */
+    async agentGetByName(name) {
+        return this.makeRequest("GET", `/api/chat/agents/by-name/${encodeURIComponent(name)}`, undefined, 0, true);
+    }
+    /** Update an agent by ID */
+    async agentUpdate(id, data) {
+        return this.makeRequest("PUT", `/api/chat/agents/${encodeURIComponent(id)}`, data, 0, true);
+    }
+    /** Delete an agent by ID */
+    async agentDelete(id) {
+        await this.makeRequest("DELETE", `/api/chat/agents/${encodeURIComponent(id)}`, undefined, 0, true);
+    }
+    /** Get agents by deployment ID */
+    async agentsByDeployment(deploymentId) {
+        return this.makeRequest("GET", `/api/chat/agents/by-deployment/${encodeURIComponent(deploymentId)}`, undefined, 0, true);
+    }
+    // ========================================================================
+    // KV DOCUMENT LINKING
+    // ========================================================================
+    /** Get documents linked to a KV key */
+    async kvGetLinks(key) {
+        return this.makeRequest("GET", `/api/kv/links/${encodeURIComponent(key)}`, undefined, 0, true);
+    }
+    /** Link a document to a KV key */
+    async kvLink(key, collection, documentId) {
+        return this.makeRequest("POST", `/api/kv/link`, { key, collection, document_id: documentId }, 0, true);
+    }
+    /** Unlink a document from a KV key */
+    async kvUnlink(key, collection, documentId) {
+        return this.makeRequest("POST", `/api/kv/unlink`, { key, collection, document_id: documentId }, 0, true);
+    }
+    // ========================================================================
+    // SCHEDULE MANAGEMENT
+    // ========================================================================
+    /** Create a new schedule */
+    async createSchedule(data) {
+        return this.makeRequest("POST", `/api/schedules`, data, 0, true);
+    }
+    /** List all schedules */
+    async listSchedules() {
+        return this.makeRequest("GET", `/api/schedules`, undefined, 0, true);
+    }
+    /** Get a schedule by ID */
+    async getSchedule(id) {
+        return this.makeRequest("GET", `/api/schedules/${encodeURIComponent(id)}`, undefined, 0, true);
+    }
+    /** Update a schedule */
+    async updateSchedule(id, data) {
+        return this.makeRequest("PUT", `/api/schedules/${encodeURIComponent(id)}`, data, 0, true);
+    }
+    /** Delete a schedule */
+    async deleteSchedule(id) {
+        await this.makeRequest("DELETE", `/api/schedules/${encodeURIComponent(id)}`, undefined, 0, true);
+    }
+    /** Pause a schedule */
+    async pauseSchedule(id) {
+        return this.makeRequest("POST", `/api/schedules/${encodeURIComponent(id)}/pause`, undefined, 0, true);
+    }
+    /** Resume a schedule */
+    async resumeSchedule(id) {
+        return this.makeRequest("POST", `/api/schedules/${encodeURIComponent(id)}/resume`, undefined, 0, true);
+    }
+    // ========================================================================
     // COLLECTION UTILITIES
     // ========================================================================
     /**
@@ -1150,22 +1706,64 @@ class EkoDBClient {
     }
 }
 exports.EkoDBClient = EkoDBClient;
+/** EventEmitter-like interface for subscriptions and chat streams. */
+class EventStream {
+    constructor() {
+        this.listeners = new Map();
+        this._closed = false;
+    }
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, []);
+        }
+        this.listeners.get(event).push(listener);
+        return this;
+    }
+    /** @internal */
+    emit(event, data) {
+        const handlers = this.listeners.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                handler(data);
+            }
+        }
+    }
+    get closed() {
+        return this._closed;
+    }
+    /** @internal */
+    close() {
+        this._closed = true;
+        this.emit("close");
+    }
+}
+exports.EventStream = EventStream;
 /**
- * WebSocket client for real-time queries
+ * WebSocket client for real-time queries, subscriptions, and chat streaming.
  */
 class WebSocketClient {
     constructor(wsURL, token) {
         this.ws = null;
+        this.dispatcherRunning = false;
+        // Dispatcher state
+        this.pendingRequests = new Map();
+        this.subscriptions = new Map();
+        this.chatStreams = new Map();
+        this.registerToolsAck = null;
+        this.messageCounter = 0;
         this.wsURL = wsURL;
         this.token = token;
     }
+    genMessageId() {
+        const counter = this.messageCounter++;
+        return `${Date.now()}-${counter}-${Math.random().toString(36).slice(2, 8)}`;
+    }
     /**
-     * Connect to WebSocket
+     * Connect and start the dispatcher.
      */
-    async connect() {
-        if (this.ws)
+    async ensureConnected() {
+        if (this.ws && this.dispatcherRunning)
             return;
-        // Dynamic import for Node.js WebSocket
         const WebSocket = (await Promise.resolve().then(() => __importStar(require("ws")))).default;
         let url = this.wsURL;
         if (!url.endsWith("/api/ws")) {
@@ -1176,43 +1774,323 @@ class WebSocketClient {
                 Authorization: `Bearer ${this.token}`,
             },
         });
-        return new Promise((resolve, reject) => {
+        await new Promise((resolve, reject) => {
             this.ws.on("open", () => resolve());
             this.ws.on("error", (err) => reject(err));
         });
+        this.spawnDispatcher();
+    }
+    spawnDispatcher() {
+        if (this.dispatcherRunning)
+            return;
+        this.dispatcherRunning = true;
+        this.ws.on("message", (data) => {
+            try {
+                const msg = 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
+            for (const [, stream] of this.subscriptions) {
+                stream.close();
+            }
+            this.subscriptions.clear();
+            this.ws = null;
+        });
+    }
+    routeMessage(msg) {
+        switch (msg.type) {
+            case "Success":
+            case "Error": {
+                // Try messageId from top-level, then from payload
+                const messageId = msg.messageId ||
+                    msg.message_id ||
+                    msg.payload?.message_id ||
+                    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;
+                }
+                if (!matched && this.registerToolsAck) {
+                    const ack = this.registerToolsAck;
+                    this.registerToolsAck = null;
+                    if (msg.type === "Error") {
+                        ack.reject(new Error(msg.message || "Tool registration failed"));
+                    }
+                    else {
+                        ack.resolve(msg.payload);
+                    }
+                    matched = true;
+                }
+                // Server doesn't echo messageId — 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);
+                    }
+                }
+                break;
+            }
+            case "MutationNotification": {
+                const payload = msg.payload;
+                const notification = {
+                    collection: payload.collection,
+                    event: payload.event,
+                    recordIds: payload.record_ids || payload.recordIds || [],
+                    records: payload.records,
+                    timestamp: payload.timestamp,
+                };
+                for (const [collection, stream] of this.subscriptions) {
+                    if (collection === notification.collection) {
+                        stream.emit("mutation", notification);
+                    }
+                }
+                break;
+            }
+            case "ChatStreamChunk": {
+                const chatId = msg.payload?.chat_id || msg.payload?.chatId;
+                const stream = this.chatStreams.get(chatId);
+                if (stream) {
+                    stream.emit("event", {
+                        type: "chunk",
+                        content: msg.payload.content,
+                    });
+                }
+                break;
+            }
+            case "ChatStreamEnd": {
+                const chatId = msg.payload?.chat_id || msg.payload?.chatId;
+                const stream = this.chatStreams.get(chatId);
+                if (stream) {
+                    stream.emit("event", {
+                        type: "end",
+                        messageId: msg.payload.message_id || msg.payload.messageId || "",
+                        tokenUsage: msg.payload.token_usage || msg.payload.tokenUsage,
+                        toolCallHistory: msg.payload.tool_call_history || msg.payload.toolCallHistory,
+                        executionTimeMs: msg.payload.execution_time_ms || msg.payload.executionTimeMs || 0,
+                        contextWindow: msg.payload.context_window || msg.payload.contextWindow,
+                    });
+                    this.chatStreams.delete(chatId);
+                    stream.close();
+                }
+                break;
+            }
+            case "ChatStreamError": {
+                const chatId = msg.payload?.chat_id || msg.payload?.chatId;
+                const stream = this.chatStreams.get(chatId);
+                if (stream) {
+                    stream.emit("event", {
+                        type: "error",
+                        error: msg.payload.error || msg.payload.message || "Unknown error",
+                    });
+                    this.chatStreams.delete(chatId);
+                    stream.close();
+                }
+                break;
+            }
+            case "ClientToolCall": {
+                const chatId = msg.payload?.chat_id || msg.payload?.chatId;
+                const stream = this.chatStreams.get(chatId);
+                if (stream) {
+                    stream.emit("event", {
+                        type: "toolCall",
+                        chatId,
+                        callId: msg.payload.call_id || msg.payload.callId,
+                        toolName: msg.payload.tool_name || msg.payload.toolName,
+                        arguments: msg.payload.arguments,
+                    });
+                }
+                break;
+            }
+        }
+    }
+    async sendRequest(request) {
+        await this.ensureConnected();
+        const messageId = request.messageId || request.message_id;
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(messageId, { resolve, reject });
+            try {
+                this.ws.send(JSON.stringify(request));
+            }
+            catch (err) {
+                this.pendingRequests.delete(messageId);
+                reject(err);
+            }
+        });
     }
     /**
-     * Find all records in a collection via WebSocket
+     * Find all records in a collection via WebSocket.
      */
     async findAll(collection) {
-        await this.connect();
-        const messageId = Date.now().toString();
-        const request = {
+        const messageId = this.genMessageId();
+        const payload = await this.sendRequest({
             type: "FindAll",
             messageId,
             payload: { collection },
+        });
+        return payload?.data || [];
+    }
+    /**
+     * Subscribe to mutation notifications on a collection.
+     * Returns an EventStream that emits "mutation" events.
+     */
+    async subscribe(collection, options) {
+        await this.ensureConnected();
+        if (this.subscriptions.has(collection)) {
+            throw new Error(`Already subscribed to collection "${collection}"`);
+        }
+        const messageId = this.genMessageId();
+        const stream = new EventStream();
+        this.subscriptions.set(collection, stream);
+        const request = {
+            type: "Subscribe",
+            messageId,
+            payload: {
+                collection,
+                ...(options?.filterField && { filter_field: options.filterField }),
+                ...(options?.filterValue && { filter_value: options.filterValue }),
+            },
         };
-        return new Promise((resolve, reject) => {
+        // Send subscribe request and wait for ack
+        try {
+            await this.sendRequest(request);
+        }
+        catch (err) {
+            this.subscriptions.delete(collection);
+            throw err;
+        }
+        return stream;
+    }
+    /**
+     * Send a chat message and receive a streaming response.
+     * Returns an EventStream that emits "event" with ChatStreamEvent objects.
+     */
+    async chatSend(chatId, message, options) {
+        await this.ensureConnected();
+        if (this.chatStreams.has(chatId)) {
+            throw new Error(`Chat stream already active for chatId "${chatId}"`);
+        }
+        const stream = new EventStream();
+        this.chatStreams.set(chatId, stream);
+        const request = {
+            type: "ChatSend",
+            payload: {
+                chat_id: chatId,
+                message,
+                ...(options?.bypassRipple != null && {
+                    bypass_ripple: options.bypassRipple,
+                }),
+                ...(options?.clientTools && { client_tools: options.clientTools }),
+                ...(options?.maxIterations != null && {
+                    max_iterations: options.maxIterations,
+                }),
+                ...(options?.confirmTools && { confirm_tools: options.confirmTools }),
+                ...(options?.excludeTools && { exclude_tools: options.excludeTools }),
+            },
+        };
+        this.ws.send(JSON.stringify(request));
+        return stream;
+    }
+    /**
+     * Register client-side tools for a chat session.
+     */
+    async registerClientTools(chatId, tools) {
+        await this.ensureConnected();
+        const request = {
+            type: "RegisterClientTools",
+            payload: {
+                chat_id: chatId,
+                tools,
+            },
+        };
+        await new Promise((resolve, reject) => {
+            this.registerToolsAck = {
+                resolve: () => resolve(),
+                reject: (err) => reject(err),
+            };
             this.ws.send(JSON.stringify(request));
-            this.ws.once("message", (data) => {
-                const response = JSON.parse(data.toString());
-                if (response.type === "Error") {
-                    reject(new Error(response.message));
-                }
-                else {
-                    resolve(response.payload?.data || []);
-                }
-            });
-            this.ws.once("error", reject);
         });
     }
     /**
-     * Close the WebSocket connection
+     * Send a tool result back to the server during a chat stream.
+     */
+    async sendToolResult(chatId, callId, success, result, error) {
+        await this.ensureConnected();
+        const request = {
+            type: "ClientToolResult",
+            payload: {
+                chat_id: chatId,
+                call_id: callId,
+                success,
+                ...(result !== undefined && { result }),
+                ...(error !== undefined && { error }),
+            },
+        };
+        this.ws.send(JSON.stringify(request));
+    }
+    /**
+     * Stateless raw LLM completion via WebSocket.
+     *
+     * Sends a RawComplete message and waits for the Success response.
+     * Preferred over HTTP for deployed instances: the persistent WSS
+     * connection is already authenticated and won't be killed by reverse
+     * proxy timeouts.
+     */
+    async rawCompletion(request) {
+        await this.ensureConnected();
+        const messageId = this.genMessageId();
+        const payload = await this.sendRequest({
+            type: "RawComplete",
+            messageId,
+            payload: {
+                system_prompt: request.system_prompt,
+                message: request.message,
+                ...(request.provider && { provider: request.provider }),
+                ...(request.model && { model: request.model }),
+                ...(request.max_tokens != null && { max_tokens: request.max_tokens }),
+            },
+        });
+        return { content: payload?.data?.content || "" };
+    }
+    /**
+     * Close the WebSocket connection.
      */
     close() {
         if (this.ws) {
             this.ws.close();
             this.ws = null;
+            this.dispatcherRunning = false;
         }
     }
 }