@ekodb/ekodb-client 0.15.1 → 0.16.0

package/dist/client.d.ts

@@ -4,7 +4,7 @@
 import { QueryBuilder } from "./query-builder";
 import { SearchQuery, SearchResponse } from "./search";
 import { Schema, SchemaBuilder, CollectionMetadata } from "./schema";
-import { Script, FunctionResult } from "./functions";
+import { UserFunction, FunctionResult } from "./functions";
 export interface Record {
     [key: string]: any;
 }
@@ -156,6 +156,7 @@ export interface CreateChatSessionRequest {
     llm_provider: string;
     llm_model?: string;
     system_prompt?: string;
+    agent_id?: string;
     bypass_ripple?: boolean;
     parent_id?: string;
     branch_point_idx?: number;
@@ -171,6 +172,9 @@ export interface ChatMessageRequest {
     max_iterations?: number;
     tool_config?: ToolConfig;
     llm_model?: string;
+    client_tools?: ClientToolDefinition[];
+    confirm_tools?: string[];
+    exclude_tools?: string[];
 }
 export interface TokenUsage {
     prompt_tokens: number;
@@ -193,6 +197,7 @@ export interface ChatSession {
     llm_model: string;
     collections: CollectionConfig[];
     system_prompt?: string;
+    agent_id?: string;
     title?: string;
     message_count: number;
 }
@@ -285,23 +290,6 @@ export interface RawCompletionRequest {
 export interface RawCompletionResponse {
     content: string;
 }
-/**
- * User function definition - reusable sequence of Functions that can be called by Scripts
- */
-export interface UserFunction {
-    label: string;
-    name: string;
-    description?: string;
-    version?: string;
-    parameters: {
-        [key: string]: ParameterDefinition;
-    };
-    functions: FunctionStageConfig[];
-    tags?: string[];
-    id?: string;
-    created_at?: string;
-    updated_at?: string;
-}
 /**
  * Parameter definition for functions
  */
@@ -821,6 +809,11 @@ export declare class EkoDBClient {
      * Send a message in an existing chat session
      */
     chatMessage(sessionId: string, request: ChatMessageRequest): Promise<ChatResponse>;
+    /**
+     * 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.
+     */
+    submitChatToolResult(chatId: string, callId: string, success: boolean, result?: any, error?: string): Promise<void>;
     /**
      * Send a message in an existing chat session via SSE streaming.
      *
@@ -902,29 +895,29 @@ export declare class EkoDBClient {
      */
     getChatMessage(sessionId: string, messageId: string): Promise<Record>;
     /**
-     * Save a new script definition
+     * Save a new function definition
      */
-    saveScript(script: Script): Promise<string>;
+    saveFunction(script: UserFunction): Promise<string>;
     /**
-     * Get a script by ID
+     * Get a function by ID
      */
-    getScript(id: string): Promise<Script>;
+    getFunction(id: string): Promise<UserFunction>;
     /**
-     * List all scripts, optionally filtered by tags
+     * List all functions, optionally filtered by tags
      */
-    listScripts(tags?: string[]): Promise<Script[]>;
+    listFunctions(tags?: string[]): Promise<UserFunction[]>;
     /**
-     * Update an existing script by ID
+     * Update an existing function by ID
      */
-    updateScript(id: string, script: Script): Promise<void>;
+    updateFunction(id: string, script: UserFunction): Promise<void>;
     /**
-     * Delete a script by ID
+     * Delete a function by ID
      */
-    deleteScript(id: string): Promise<void>;
+    deleteFunction(id: string): Promise<void>;
     /**
-     * Call a saved script by ID or label
+     * Call a saved function by ID or label
      */
-    callScript(idOrLabel: string, params?: {
+    callFunction(idOrLabel: string, params?: {
         [key: string]: any;
     }): Promise<FunctionResult>;
     /**
@@ -1058,6 +1051,17 @@ export declare class EkoDBClient {
      * @returns Number of documents in the collection
      */
     countDocuments(collection: string): Promise<number>;
+    /**
+     * Subscribe to collection mutations via SSE (Server-Sent Events).
+     *
+     * Returns an EventStream that emits MutationNotification events.
+     * Use this when WebSocket connections aren't available (e.g. behind
+     * reverse proxies that block WS upgrades).
+     */
+    subscribeSSE(collection: string, options?: {
+        filterField?: string;
+        filterValue?: string;
+    }): EventStream<MutationNotification>;
     /**
      * Create a WebSocket client
      */

package/dist/client.js

@@ -1098,6 +1098,18 @@ class EkoDBClient {
     async chatMessage(sessionId, request) {
         return this.makeRequest("POST", `/api/chat/${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`, {
+            call_id: callId,
+            success,
+            ...(result !== undefined && { result }),
+            ...(error !== undefined && { error }),
+        }, 0, true);
+    }
     /**
      * Send a message in an existing chat session via SSE streaming.
      *
@@ -1307,41 +1319,41 @@ class EkoDBClient {
     // SCRIPTS API
     // ========================================================================
     /**
-     * Save a new script definition
+     * Save a new function definition
      */
-    async saveScript(script) {
+    async saveFunction(script) {
         const result = await this.makeRequest("POST", "/api/functions", script);
         return result.id;
     }
     /**
-     * Get a script by ID
+     * Get a function by ID
      */
-    async getScript(id) {
+    async getFunction(id) {
         return this.makeRequest("GET", `/api/functions/${id}`);
     }
     /**
-     * List all scripts, optionally filtered by tags
+     * List all functions, optionally filtered by tags
      */
-    async listScripts(tags) {
+    async listFunctions(tags) {
         const params = tags ? `?tags=${tags.join(",")}` : "";
         return this.makeRequest("GET", `/api/functions${params}`);
     }
     /**
-     * Update an existing script by ID
+     * Update an existing function by ID
      */
-    async updateScript(id, script) {
+    async updateFunction(id, script) {
         await this.makeRequest("PUT", `/api/functions/${id}`, script);
     }
     /**
-     * Delete a script by ID
+     * Delete a function by ID
      */
-    async deleteScript(id) {
+    async deleteFunction(id) {
         await this.makeRequest("DELETE", `/api/functions/${id}`);
     }
     /**
-     * Call a saved script by ID or label
+     * Call a saved function by ID or label
      */
-    async callScript(idOrLabel, params) {
+    async callFunction(idOrLabel, params) {
         return this.makeRequest("POST", `/api/functions/${idOrLabel}`, params || {});
     }
     // ========================================================================
@@ -1613,6 +1625,99 @@ class EkoDBClient {
         const records = await this.find(collection, query);
         return records.length;
     }
+    /**
+     * Subscribe to collection mutations via SSE (Server-Sent Events).
+     *
+     * Returns an EventStream that emits MutationNotification events.
+     * Use this when WebSocket connections aren't available (e.g. behind
+     * reverse proxies that block WS upgrades).
+     */
+    subscribeSSE(collection, options) {
+        const stream = new EventStream();
+        (async () => {
+            try {
+                let token = await this.getToken();
+                if (!token) {
+                    await this.refreshToken();
+                    token = await this.getToken();
+                }
+                let url = `${this.baseURL}/api/subscribe/${encodeURIComponent(collection)}`;
+                const params = [];
+                if (options?.filterField)
+                    params.push(`filter_field=${encodeURIComponent(options.filterField)}`);
+                if (options?.filterValue)
+                    params.push(`filter_value=${encodeURIComponent(options.filterValue)}`);
+                if (params.length > 0)
+                    url += `?${params.join("&")}`;
+                const response = await fetch(url, {
+                    method: "GET",
+                    headers: {
+                        Accept: "text/event-stream",
+                        Authorization: `Bearer ${token}`,
+                    },
+                });
+                if (!response.ok) {
+                    const body = await response.text();
+                    stream.emit("error", `SSE subscribe failed (${response.status}): ${body}`);
+                    stream.close();
+                    return;
+                }
+                const reader = response.body?.getReader();
+                if (!reader) {
+                    stream.emit("error", "SSE subscribe failed: streaming not supported");
+                    stream.close();
+                    return;
+                }
+                const decoder = new TextDecoder("utf-8");
+                let buffer = "";
+                let eventType = "";
+                let dataLines = [];
+                while (!stream.closed) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split("\n");
+                    buffer = lines.pop() ?? "";
+                    for (const line of lines) {
+                        if (line === "") {
+                            // End of event block
+                            if (eventType === "mutation" && dataLines.length > 0) {
+                                try {
+                                    const payload = JSON.parse(dataLines.join("\n"));
+                                    stream.emit("event", {
+                                        collection: payload.collection,
+                                        event: payload.event,
+                                        recordIds: payload.record_ids,
+                                        records: payload.records,
+                                        timestamp: payload.timestamp,
+                                    });
+                                }
+                                catch {
+                                    // skip malformed data
+                                }
+                            }
+                            eventType = "";
+                            dataLines = [];
+                            continue;
+                        }
+                        if (line.startsWith("event: ")) {
+                            eventType = line.slice(7).trim();
+                        }
+                        else if (line.startsWith("data: ")) {
+                            dataLines.push(line.slice(6).trim());
+                        }
+                    }
+                }
+                stream.close();
+            }
+            catch (err) {
+                stream.emit("error", err.message ?? String(err));
+                stream.close();
+            }
+        })();
+        return stream;
+    }
     /**
      * Create a WebSocket client
      */
@@ -1720,7 +1825,10 @@ class EkoDBClient {
             limit,
         };
         const response = await this.search(collection, searchQuery);
-        return response.results.map((r) => r.record);
+        return response.results.map((r) => ({
+            ...r.record,
+            _score: r.score,
+        }));
     }
     /**
      * Find all records in a collection with a limit

package/dist/client.test.js

@@ -590,14 +590,14 @@ function mockErrorResponse(status, message) {
             parameters: {},
             functions: [],
         };
-        const result = await client.saveScript(script);
+        const result = await client.saveFunction(script);
         (0, vitest_1.expect)(result).toBeDefined();
     });
     (0, vitest_1.it)("gets script by ID", async () => {
         const client = createTestClient();
         mockTokenResponse();
         mockJsonResponse({ id: "func_123", label: "my_function" });
-        const result = await client.getScript("func_123");
+        const result = await client.getFunction("func_123");
         (0, vitest_1.expect)(result).toBeDefined();
     });
     (0, vitest_1.it)("updates script", async () => {
@@ -610,7 +610,7 @@ function mockErrorResponse(status, message) {
             parameters: {},
             functions: [],
         };
-        await (0, vitest_1.expect)(client.updateScript("func_123", script)).resolves.not.toThrow();
+        await (0, vitest_1.expect)(client.updateFunction("func_123", script)).resolves.not.toThrow();
     });
 });
 (0, vitest_1.describe)("EkoDBClient chat advanced", () => {
@@ -1944,6 +1944,7 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(result).toHaveLength(1);
         (0, vitest_1.expect)(result[0]).toHaveProperty("id", "doc_1");
         (0, vitest_1.expect)(result[0]).toHaveProperty("title", "ML Guide");
+        (0, vitest_1.expect)(result[0]).toHaveProperty("_score", 0.95);
     });
 });
 // ============================================================================
@@ -2022,3 +2023,204 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(mockFetch).toHaveBeenCalledTimes(2);
     });
 });
+// ============================================================================
+// agent_id Tests
+// ============================================================================
+(0, vitest_1.describe)("agent_id on chat types", () => {
+    (0, vitest_1.it)("CreateChatSessionRequest includes agent_id", () => {
+        const req = {
+            collections: [{ collection_name: "docs" }],
+            llm_provider: "openai",
+            agent_id: "my-agent",
+        };
+        (0, vitest_1.expect)(req.agent_id).toBe("my-agent");
+    });
+    (0, vitest_1.it)("CreateChatSessionRequest omits agent_id when undefined", () => {
+        const req = {
+            collections: [],
+            llm_provider: "openai",
+        };
+        (0, vitest_1.expect)(req.agent_id).toBeUndefined();
+    });
+    (0, vitest_1.it)("ChatSession includes agent_id", () => {
+        const session = {
+            chat_id: "c1",
+            created_at: "2026-01-01",
+            updated_at: "2026-01-01",
+            llm_provider: "openai",
+            llm_model: "gpt-4",
+            collections: [],
+            agent_id: "bot-1",
+            message_count: 0,
+        };
+        (0, vitest_1.expect)(session.agent_id).toBe("bot-1");
+    });
+    (0, vitest_1.it)("ChatSession allows missing agent_id", () => {
+        const session = {
+            chat_id: "c1",
+            created_at: "2026-01-01",
+            updated_at: "2026-01-01",
+            llm_provider: "openai",
+            llm_model: "gpt-4",
+            collections: [],
+            message_count: 0,
+        };
+        (0, vitest_1.expect)(session.agent_id).toBeUndefined();
+    });
+});
+// ============================================================================
+// client_tools / confirm_tools / exclude_tools Tests
+// ============================================================================
+(0, vitest_1.describe)("ChatMessageRequest tool fields", () => {
+    (0, vitest_1.it)("includes client_tools, confirm_tools, exclude_tools", () => {
+        const req = {
+            message: "hello",
+            client_tools: [
+                {
+                    name: "weather",
+                    description: "Get weather",
+                    parameters: { type: "object" },
+                },
+            ],
+            confirm_tools: ["shell_exec"],
+            exclude_tools: ["file_delete"],
+        };
+        (0, vitest_1.expect)(req.client_tools).toHaveLength(1);
+        (0, vitest_1.expect)(req.client_tools[0].name).toBe("weather");
+        (0, vitest_1.expect)(req.confirm_tools).toEqual(["shell_exec"]);
+        (0, vitest_1.expect)(req.exclude_tools).toEqual(["file_delete"]);
+    });
+    (0, vitest_1.it)("tool fields are optional", () => {
+        const req = { message: "hi" };
+        (0, vitest_1.expect)(req.client_tools).toBeUndefined();
+        (0, vitest_1.expect)(req.confirm_tools).toBeUndefined();
+        (0, vitest_1.expect)(req.exclude_tools).toBeUndefined();
+    });
+    (0, vitest_1.it)("ClientToolDefinition has correct shape", () => {
+        const tool = {
+            name: "calc",
+            description: "Calculator",
+            parameters: { type: "object", properties: {} },
+        };
+        (0, vitest_1.expect)(tool.name).toBe("calc");
+        (0, vitest_1.expect)(tool.description).toBe("Calculator");
+        (0, vitest_1.expect)(tool.parameters.type).toBe("object");
+    });
+});
+// ============================================================================
+// submitChatToolResult Tests
+// ============================================================================
+(0, vitest_1.describe)("submitChatToolResult", () => {
+    (0, vitest_1.it)("sends tool result to correct endpoint", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({});
+        await client.submitChatToolResult("chat-123", "call-456", true, {
+            temp: "72F",
+        });
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledTimes(2);
+        const call = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(call[0]).toContain("/api/chat/chat-123/tool-result");
+        const body = JSON.parse(call[1].body);
+        (0, vitest_1.expect)(body.call_id).toBe("call-456");
+        (0, vitest_1.expect)(body.success).toBe(true);
+        (0, vitest_1.expect)(body.result.temp).toBe("72F");
+    });
+    (0, vitest_1.it)("sends error result", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({});
+        await client.submitChatToolResult("chat-123", "call-456", false, undefined, "tool crashed");
+        const call = mockFetch.mock.calls[1];
+        const body = JSON.parse(call[1].body);
+        (0, vitest_1.expect)(body.success).toBe(false);
+        (0, vitest_1.expect)(body.error).toBe("tool crashed");
+        (0, vitest_1.expect)(body.result).toBeUndefined();
+    });
+});
+// ============================================================================
+// subscribeSSE Tests
+// ============================================================================
+(0, vitest_1.describe)("subscribeSSE", () => {
+    /** Create a mock ReadableStream from a string */
+    function mockReadableStream(data) {
+        const encoder = new TextEncoder();
+        const bytes = encoder.encode(data);
+        let sent = false;
+        return {
+            getReader: () => ({
+                read: async () => {
+                    if (!sent) {
+                        sent = true;
+                        return { value: bytes, done: false };
+                    }
+                    return { value: undefined, done: true };
+                },
+            }),
+        };
+    }
+    (0, vitest_1.it)("parses mutation events from SSE stream", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        const sseBody = "event: subscribed\ndata: {}\n\n" +
+            'event: mutation\ndata: {"collection":"orders","event":"insert","record_ids":["r1"],"timestamp":"t1"}\n\n' +
+            'event: mutation\ndata: {"collection":"orders","event":"update","record_ids":["r2"],"timestamp":"t2"}\n\n';
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            body: mockReadableStream(sseBody),
+            headers: new Headers({ "content-type": "text/event-stream" }),
+        });
+        const stream = client.subscribeSSE("orders");
+        const events = [];
+        await new Promise((resolve) => {
+            stream.on("event", (e) => events.push(e));
+            stream.on("close", resolve);
+            setTimeout(resolve, 100);
+        });
+        (0, vitest_1.expect)(events).toHaveLength(2);
+        (0, vitest_1.expect)(events[0].event).toBe("insert");
+        (0, vitest_1.expect)(events[0].recordIds).toEqual(["r1"]);
+        (0, vitest_1.expect)(events[1].event).toBe("update");
+        (0, vitest_1.expect)(events[1].recordIds).toEqual(["r2"]);
+    });
+    (0, vitest_1.it)("passes filter params in URL", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            body: mockReadableStream(""),
+            headers: new Headers({ "content-type": "text/event-stream" }),
+        });
+        client.subscribeSSE("orders", {
+            filterField: "status",
+            filterValue: "active",
+        });
+        // Wait for async fetch
+        await new Promise((r) => setTimeout(r, 50));
+        const call = mockFetch.mock.calls[1];
+        (0, vitest_1.expect)(call[0]).toContain("/api/subscribe/orders");
+        (0, vitest_1.expect)(call[0]).toContain("filter_field=status");
+        (0, vitest_1.expect)(call[0]).toContain("filter_value=active");
+    });
+    (0, vitest_1.it)("emits error on HTTP failure", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            status: 401,
+            text: async () => "Unauthorized",
+            headers: new Headers(),
+        });
+        const stream = client.subscribeSSE("orders");
+        const errors = [];
+        await new Promise((resolve) => {
+            stream.on("error", (e) => errors.push(e));
+            stream.on("close", resolve);
+            setTimeout(resolve, 100);
+        });
+        (0, vitest_1.expect)(errors).toHaveLength(1);
+        (0, vitest_1.expect)(errors[0]).toContain("401");
+    });
+});

package/dist/functions.d.ts

@@ -1,7 +1,9 @@
 /**
- * Scripts API for ekoDB TypeScript client
+ * Functions API for ekoDB TypeScript client
  */
-export interface Script {
+/** A reusable sequence of Functions stored in ekoDB. */
+export interface UserFunction {
+    id?: string;
     label: string;
     name: string;
     description?: string;
@@ -140,7 +142,7 @@ export type FunctionStageConfig = {
     value: any;
 } | {
     type: "If";
-    condition: ScriptCondition;
+    condition: FunctionCondition;
     then_functions: FunctionStageConfig[];
     else_functions?: FunctionStageConfig[];
 } | {
@@ -224,7 +226,7 @@ export interface SortFieldConfig {
     field: string;
     ascending: boolean;
 }
-export type ScriptCondition = {
+export type FunctionCondition = {
     type: "FieldEquals";
     value: {
         field: string;
@@ -255,17 +257,17 @@ export type ScriptCondition = {
 } | {
     type: "And";
     value: {
-        conditions: ScriptCondition[];
+        conditions: FunctionCondition[];
     };
 } | {
     type: "Or";
     value: {
-        conditions: ScriptCondition[];
+        conditions: FunctionCondition[];
     };
 } | {
     type: "Not";
     value: {
-        condition: ScriptCondition;
+        condition: FunctionCondition;
     };
 };
 export interface FunctionResult {
@@ -314,7 +316,7 @@ export declare const Stage: {
     embed: (input_field: string, output_field: string, model?: string) => FunctionStageConfig;
     findById: (collection: string, record_id: string) => FunctionStageConfig;
     findOne: (collection: string, key: string, value: any) => FunctionStageConfig;
-    if: (condition: ScriptCondition, thenFunctions: FunctionStageConfig[], elseFunctions?: FunctionStageConfig[]) => FunctionStageConfig;
+    if: (condition: FunctionCondition, thenFunctions: FunctionStageConfig[], elseFunctions?: FunctionStageConfig[]) => FunctionStageConfig;
     forEach: (functions: FunctionStageConfig[]) => FunctionStageConfig;
     callFunction: (function_label: string, params?: Record<string, any>) => FunctionStageConfig;
     findOneAndUpdate: (collection: string, record_id: string, updates: Record<string, any>, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;

package/dist/functions.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Scripts API for ekoDB TypeScript client
+ * Functions API for ekoDB TypeScript client
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Stage = exports.ChatMessage = void 0;

package/dist/index.d.ts

@@ -9,6 +9,6 @@ export type { WrappedFieldValue } from "./utils";
 export type { SearchQuery, SearchResult, SearchResponse } from "./search";
 export type { Schema, FieldTypeSchema, IndexConfig, CollectionMetadata, } from "./schema";
 export type { JoinConfig } from "./join";
-export type { Script, ParameterDefinition, FunctionStageConfig, GroupFunctionConfig, SortFieldConfig, FunctionResult, FunctionStats, StageStats, } from "./functions";
+export type { UserFunction, ParameterDefinition, FunctionStageConfig, GroupFunctionConfig, SortFieldConfig, FunctionResult, FunctionStats, StageStats, } from "./functions";
 export type { MutationNotification, ChatStreamEvent, ClientToolDefinition, ChatSendOptions, SubscribeOptions, } from "./client";
-export type { Record, Query, BatchOperationResult, ClientConfig, RateLimitInfo, CollectionConfig, ChatRequest, CreateChatSessionRequest, ChatMessageRequest, TokenUsage, ChatResponse, ChatSession, ChatSessionResponse, ListSessionsQuery, ListSessionsResponse, GetMessagesQuery, GetMessagesResponse, UpdateSessionRequest, MergeSessionsRequest, ChatModels, EmbedRequest, EmbedResponse, RawCompletionRequest, RawCompletionResponse, UserFunction, ToolChoice, ToolConfig, } from "./client";
+export type { Record, Query, BatchOperationResult, ClientConfig, RateLimitInfo, CollectionConfig, ChatRequest, CreateChatSessionRequest, ChatMessageRequest, TokenUsage, ChatResponse, ChatSession, ChatSessionResponse, ListSessionsQuery, ListSessionsResponse, GetMessagesQuery, GetMessagesResponse, UpdateSessionRequest, MergeSessionsRequest, ChatModels, EmbedRequest, EmbedResponse, RawCompletionRequest, RawCompletionResponse, ToolChoice, ToolConfig, } from "./client";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "Official TypeScript/JavaScript client for ekoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/client.test.ts

@@ -800,7 +800,7 @@ describe("EkoDBClient scripts advanced", () => {
       parameters: {},
       functions: [],
     };
-    const result = await client.saveScript(script);
+    const result = await client.saveFunction(script);
 
     expect(result).toBeDefined();
   });
@@ -811,7 +811,7 @@ describe("EkoDBClient scripts advanced", () => {
     mockTokenResponse();
     mockJsonResponse({ id: "func_123", label: "my_function" });
 
-    const result = await client.getScript("func_123");
+    const result = await client.getFunction("func_123");
 
     expect(result).toBeDefined();
   });
@@ -829,7 +829,7 @@ describe("EkoDBClient scripts advanced", () => {
       functions: [],
     };
     await expect(
-      client.updateScript("func_123", script),
+      client.updateFunction("func_123", script),
     ).resolves.not.toThrow();
   });
 });
@@ -2584,6 +2584,7 @@ describe("EkoDBClient text and hybrid search", () => {
     expect(result).toHaveLength(1);
     expect(result[0]).toHaveProperty("id", "doc_1");
     expect(result[0]).toHaveProperty("title", "ML Guide");
+    expect(result[0]).toHaveProperty("_score", 0.95);
   });
 });
 
@@ -2673,3 +2674,243 @@ describe("EkoDBClient auth token management", () => {
     expect(mockFetch).toHaveBeenCalledTimes(2);
   });
 });
+
+// ============================================================================
+// agent_id Tests
+// ============================================================================
+
+describe("agent_id on chat types", () => {
+  it("CreateChatSessionRequest includes agent_id", () => {
+    const req: any = {
+      collections: [{ collection_name: "docs" }],
+      llm_provider: "openai",
+      agent_id: "my-agent",
+    };
+    expect(req.agent_id).toBe("my-agent");
+  });
+
+  it("CreateChatSessionRequest omits agent_id when undefined", () => {
+    const req: any = {
+      collections: [],
+      llm_provider: "openai",
+    };
+    expect(req.agent_id).toBeUndefined();
+  });
+
+  it("ChatSession includes agent_id", () => {
+    const session: any = {
+      chat_id: "c1",
+      created_at: "2026-01-01",
+      updated_at: "2026-01-01",
+      llm_provider: "openai",
+      llm_model: "gpt-4",
+      collections: [],
+      agent_id: "bot-1",
+      message_count: 0,
+    };
+    expect(session.agent_id).toBe("bot-1");
+  });
+
+  it("ChatSession allows missing agent_id", () => {
+    const session: any = {
+      chat_id: "c1",
+      created_at: "2026-01-01",
+      updated_at: "2026-01-01",
+      llm_provider: "openai",
+      llm_model: "gpt-4",
+      collections: [],
+      message_count: 0,
+    };
+    expect(session.agent_id).toBeUndefined();
+  });
+});
+
+// ============================================================================
+// client_tools / confirm_tools / exclude_tools Tests
+// ============================================================================
+
+describe("ChatMessageRequest tool fields", () => {
+  it("includes client_tools, confirm_tools, exclude_tools", () => {
+    const req: any = {
+      message: "hello",
+      client_tools: [
+        {
+          name: "weather",
+          description: "Get weather",
+          parameters: { type: "object" },
+        },
+      ],
+      confirm_tools: ["shell_exec"],
+      exclude_tools: ["file_delete"],
+    };
+    expect(req.client_tools).toHaveLength(1);
+    expect(req.client_tools[0].name).toBe("weather");
+    expect(req.confirm_tools).toEqual(["shell_exec"]);
+    expect(req.exclude_tools).toEqual(["file_delete"]);
+  });
+
+  it("tool fields are optional", () => {
+    const req: any = { message: "hi" };
+    expect(req.client_tools).toBeUndefined();
+    expect(req.confirm_tools).toBeUndefined();
+    expect(req.exclude_tools).toBeUndefined();
+  });
+
+  it("ClientToolDefinition has correct shape", () => {
+    const tool: any = {
+      name: "calc",
+      description: "Calculator",
+      parameters: { type: "object", properties: {} },
+    };
+    expect(tool.name).toBe("calc");
+    expect(tool.description).toBe("Calculator");
+    expect(tool.parameters.type).toBe("object");
+  });
+});
+
+// ============================================================================
+// submitChatToolResult Tests
+// ============================================================================
+
+describe("submitChatToolResult", () => {
+  it("sends tool result to correct endpoint", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({});
+
+    await client.submitChatToolResult("chat-123", "call-456", true, {
+      temp: "72F",
+    });
+
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    const call = mockFetch.mock.calls[1];
+    expect(call[0]).toContain("/api/chat/chat-123/tool-result");
+    const body = JSON.parse(call[1].body);
+    expect(body.call_id).toBe("call-456");
+    expect(body.success).toBe(true);
+    expect(body.result.temp).toBe("72F");
+  });
+
+  it("sends error result", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({});
+
+    await client.submitChatToolResult(
+      "chat-123",
+      "call-456",
+      false,
+      undefined,
+      "tool crashed",
+    );
+
+    const call = mockFetch.mock.calls[1];
+    const body = JSON.parse(call[1].body);
+    expect(body.success).toBe(false);
+    expect(body.error).toBe("tool crashed");
+    expect(body.result).toBeUndefined();
+  });
+});
+
+// ============================================================================
+// subscribeSSE Tests
+// ============================================================================
+
+describe("subscribeSSE", () => {
+  /** Create a mock ReadableStream from a string */
+  function mockReadableStream(data: string) {
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(data);
+    let sent = false;
+    return {
+      getReader: () => ({
+        read: async () => {
+          if (!sent) {
+            sent = true;
+            return { value: bytes, done: false };
+          }
+          return { value: undefined, done: true };
+        },
+      }),
+    };
+  }
+
+  it("parses mutation events from SSE stream", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const sseBody =
+      "event: subscribed\ndata: {}\n\n" +
+      'event: mutation\ndata: {"collection":"orders","event":"insert","record_ids":["r1"],"timestamp":"t1"}\n\n' +
+      'event: mutation\ndata: {"collection":"orders","event":"update","record_ids":["r2"],"timestamp":"t2"}\n\n';
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      body: mockReadableStream(sseBody),
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const stream = client.subscribeSSE("orders");
+    const events: any[] = [];
+    await new Promise<void>((resolve) => {
+      stream.on("event", (e: any) => events.push(e));
+      stream.on("close", resolve);
+      setTimeout(resolve, 100);
+    });
+
+    expect(events).toHaveLength(2);
+    expect(events[0].event).toBe("insert");
+    expect(events[0].recordIds).toEqual(["r1"]);
+    expect(events[1].event).toBe("update");
+    expect(events[1].recordIds).toEqual(["r2"]);
+  });
+
+  it("passes filter params in URL", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      body: mockReadableStream(""),
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    client.subscribeSSE("orders", {
+      filterField: "status",
+      filterValue: "active",
+    });
+
+    // Wait for async fetch
+    await new Promise((r) => setTimeout(r, 50));
+
+    const call = mockFetch.mock.calls[1];
+    expect(call[0]).toContain("/api/subscribe/orders");
+    expect(call[0]).toContain("filter_field=status");
+    expect(call[0]).toContain("filter_value=active");
+  });
+
+  it("emits error on HTTP failure", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 401,
+      text: async () => "Unauthorized",
+      headers: new Headers(),
+    });
+
+    const stream = client.subscribeSSE("orders");
+    const errors: string[] = [];
+    await new Promise<void>((resolve) => {
+      stream.on("error", (e: string) => errors.push(e));
+      stream.on("close", resolve);
+      setTimeout(resolve, 100);
+    });
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toContain("401");
+  });
+});

package/src/client.ts

@@ -6,7 +6,7 @@ import { encode, decode } from "@msgpack/msgpack";
 import { QueryBuilder, Query as QueryBuilderQuery } from "./query-builder";
 import { SearchQuery, SearchResponse } from "./search";
 import { Schema, SchemaBuilder, CollectionMetadata } from "./schema";
-import { Script, FunctionResult } from "./functions";
+import { UserFunction, FunctionResult } from "./functions";
 
 export interface Record {
   [key: string]: any;
@@ -188,6 +188,7 @@ export interface CreateChatSessionRequest {
   llm_provider: string;
   llm_model?: string;
   system_prompt?: string;
+  agent_id?: string;
   bypass_ripple?: boolean;
   parent_id?: string;
   branch_point_idx?: number;
@@ -204,6 +205,9 @@ export interface ChatMessageRequest {
   max_iterations?: number;
   tool_config?: ToolConfig;
   llm_model?: string;
+  client_tools?: ClientToolDefinition[];
+  confirm_tools?: string[];
+  exclude_tools?: string[];
 }
 
 export interface TokenUsage {
@@ -229,6 +233,7 @@ export interface ChatSession {
   llm_model: string;
   collections: CollectionConfig[];
   system_prompt?: string;
+  agent_id?: string;
   title?: string;
   message_count: number;
 }
@@ -335,21 +340,7 @@ export interface RawCompletionResponse {
   content: string;
 }
 
-/**
- * User function definition - reusable sequence of Functions that can be called by Scripts
- */
-export interface UserFunction {
-  label: string;
-  name: string;
-  description?: string;
-  version?: string;
-  parameters: { [key: string]: ParameterDefinition };
-  functions: FunctionStageConfig[];
-  tags?: string[];
-  id?: string;
-  created_at?: string;
-  updated_at?: string;
-}
+// UserFunction is defined in functions.ts and re-exported from there.
 
 /**
  * Parameter definition for functions
@@ -1769,6 +1760,31 @@ export class EkoDBClient {
     );
   }
 
+  /**
+   * 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: string,
+    callId: string,
+    success: boolean,
+    result?: any,
+    error?: string,
+  ): Promise<void> {
+    await this.makeRequest(
+      "POST",
+      `/api/chat/${chatId}/tool-result`,
+      {
+        call_id: callId,
+        success,
+        ...(result !== undefined && { result }),
+        ...(error !== undefined && { error }),
+      },
+      0,
+      true,
+    );
+  }
+
   /**
    * Send a message in an existing chat session via SSE streaming.
    *
@@ -2106,9 +2122,9 @@ export class EkoDBClient {
   // ========================================================================
 
   /**
-   * Save a new script definition
+   * Save a new function definition
    */
-  async saveScript(script: Script): Promise<string> {
+  async saveFunction(script: UserFunction): Promise<string> {
     const result = await this.makeRequest<{ id: string }>(
       "POST",
       "/api/functions",
@@ -2118,38 +2134,38 @@ export class EkoDBClient {
   }
 
   /**
-   * Get a script by ID
+   * Get a function by ID
    */
-  async getScript(id: string): Promise<Script> {
-    return this.makeRequest<Script>("GET", `/api/functions/${id}`);
+  async getFunction(id: string): Promise<UserFunction> {
+    return this.makeRequest<UserFunction>("GET", `/api/functions/${id}`);
   }
 
   /**
-   * List all scripts, optionally filtered by tags
+   * List all functions, optionally filtered by tags
    */
-  async listScripts(tags?: string[]): Promise<Script[]> {
+  async listFunctions(tags?: string[]): Promise<UserFunction[]> {
     const params = tags ? `?tags=${tags.join(",")}` : "";
-    return this.makeRequest<Script[]>("GET", `/api/functions${params}`);
+    return this.makeRequest<UserFunction[]>("GET", `/api/functions${params}`);
   }
 
   /**
-   * Update an existing script by ID
+   * Update an existing function by ID
    */
-  async updateScript(id: string, script: Script): Promise<void> {
+  async updateFunction(id: string, script: UserFunction): Promise<void> {
     await this.makeRequest<void>("PUT", `/api/functions/${id}`, script);
   }
 
   /**
-   * Delete a script by ID
+   * Delete a function by ID
    */
-  async deleteScript(id: string): Promise<void> {
+  async deleteFunction(id: string): Promise<void> {
     await this.makeRequest<void>("DELETE", `/api/functions/${id}`);
   }
 
   /**
-   * Call a saved script by ID or label
+   * Call a saved function by ID or label
    */
-  async callScript(
+  async callFunction(
     idOrLabel: string,
     params?: { [key: string]: any },
   ): Promise<FunctionResult> {
@@ -2783,6 +2799,115 @@ export class EkoDBClient {
     return records.length;
   }
 
+  /**
+   * Subscribe to collection mutations via SSE (Server-Sent Events).
+   *
+   * Returns an EventStream that emits MutationNotification events.
+   * Use this when WebSocket connections aren't available (e.g. behind
+   * reverse proxies that block WS upgrades).
+   */
+  subscribeSSE(
+    collection: string,
+    options?: { filterField?: string; filterValue?: string },
+  ): EventStream<MutationNotification> {
+    const stream = new EventStream<MutationNotification>();
+
+    (async () => {
+      try {
+        let token = await this.getToken();
+        if (!token) {
+          await this.refreshToken();
+          token = await this.getToken();
+        }
+
+        let url = `${this.baseURL}/api/subscribe/${encodeURIComponent(collection)}`;
+        const params: string[] = [];
+        if (options?.filterField)
+          params.push(
+            `filter_field=${encodeURIComponent(options.filterField)}`,
+          );
+        if (options?.filterValue)
+          params.push(
+            `filter_value=${encodeURIComponent(options.filterValue)}`,
+          );
+        if (params.length > 0) url += `?${params.join("&")}`;
+
+        const response = await fetch(url, {
+          method: "GET",
+          headers: {
+            Accept: "text/event-stream",
+            Authorization: `Bearer ${token}`,
+          },
+        });
+
+        if (!response.ok) {
+          const body = await response.text();
+          stream.emit(
+            "error",
+            `SSE subscribe failed (${response.status}): ${body}`,
+          );
+          stream.close();
+          return;
+        }
+
+        const reader = response.body?.getReader();
+        if (!reader) {
+          stream.emit("error", "SSE subscribe failed: streaming not supported");
+          stream.close();
+          return;
+        }
+
+        const decoder = new TextDecoder("utf-8");
+        let buffer = "";
+        let eventType = "";
+        let dataLines: string[] = [];
+
+        while (!stream.closed) {
+          const { value, done } = await reader.read();
+          if (done) break;
+
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split("\n");
+          buffer = lines.pop() ?? "";
+
+          for (const line of lines) {
+            if (line === "") {
+              // End of event block
+              if (eventType === "mutation" && dataLines.length > 0) {
+                try {
+                  const payload = JSON.parse(dataLines.join("\n"));
+                  stream.emit("event", {
+                    collection: payload.collection,
+                    event: payload.event,
+                    recordIds: payload.record_ids,
+                    records: payload.records,
+                    timestamp: payload.timestamp,
+                  } as MutationNotification);
+                } catch {
+                  // skip malformed data
+                }
+              }
+              eventType = "";
+              dataLines = [];
+              continue;
+            }
+            if (line.startsWith("event: ")) {
+              eventType = line.slice(7).trim();
+            } else if (line.startsWith("data: ")) {
+              dataLines.push(line.slice(6).trim());
+            }
+          }
+        }
+        stream.close();
+      } catch (err: any) {
+        stream.emit("error", err.message ?? String(err));
+        stream.close();
+      }
+    })();
+
+    return stream;
+  }
+
   /**
    * Create a WebSocket client
    */
@@ -2912,7 +3037,10 @@ export class EkoDBClient {
     };
 
     const response = await this.search(collection, searchQuery);
-    return response.results.map((r) => r.record);
+    return response.results.map((r) => ({
+      ...r.record,
+      _score: r.score,
+    }));
   }
 
   /**

package/src/functions.ts

@@ -1,8 +1,10 @@
 /**
- * Scripts API for ekoDB TypeScript client
+ * Functions API for ekoDB TypeScript client
  */
 
-export interface Script {
+/** A reusable sequence of Functions stored in ekoDB. */
+export interface UserFunction {
+  id?: string;
   label: string;
   name: string;
   description?: string;
@@ -146,7 +148,7 @@ export type FunctionStageConfig =
     }
   | {
       type: "If";
-      condition: ScriptCondition;
+      condition: FunctionCondition;
       then_functions: FunctionStageConfig[];
       else_functions?: FunctionStageConfig[];
     }
@@ -265,18 +267,18 @@ export interface SortFieldConfig {
   ascending: boolean;
 }
 
-// ScriptCondition uses adjacently-tagged format: { type: "...", value: { ...data } }
+// FunctionCondition uses adjacently-tagged format: { type: "...", value: { ...data } }
 // Unit variants (HasRecords) have no value field
-export type ScriptCondition =
+export type FunctionCondition =
   | { type: "FieldEquals"; value: { field: string; value: any } }
   | { type: "FieldExists"; value: { field: string } }
   | { type: "HasRecords" }
   | { type: "CountEquals"; value: { count: number } }
   | { type: "CountGreaterThan"; value: { count: number } }
   | { type: "CountLessThan"; value: { count: number } }
-  | { type: "And"; value: { conditions: ScriptCondition[] } }
-  | { type: "Or"; value: { conditions: ScriptCondition[] } }
-  | { type: "Not"; value: { condition: ScriptCondition } };
+  | { type: "And"; value: { conditions: FunctionCondition[] } }
+  | { type: "Or"; value: { conditions: FunctionCondition[] } }
+  | { type: "Not"; value: { condition: FunctionCondition } };
 
 export interface FunctionResult {
   records: Record<string, any>[];
@@ -541,7 +543,7 @@ export const Stage = {
   }),
 
   if: (
-    condition: ScriptCondition,
+    condition: FunctionCondition,
     thenFunctions: FunctionStageConfig[],
     elseFunctions?: FunctionStageConfig[],
   ): FunctionStageConfig => ({

package/src/index.ts

@@ -44,7 +44,7 @@ export type {
 } from "./schema";
 export type { JoinConfig } from "./join";
 export type {
-  Script,
+  UserFunction,
   ParameterDefinition,
   FunctionStageConfig,
   GroupFunctionConfig,
@@ -85,7 +85,6 @@ export type {
   EmbedResponse,
   RawCompletionRequest,
   RawCompletionResponse,
-  UserFunction,
   ToolChoice,
   ToolConfig,
 } from "./client";