@ekodb/ekodb-client 0.15.2 → 0.17.0

package/dist/functions.test.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * Unit tests for the stored-function builder helpers (Stage + parameterRef).
+ *
+ * These tests cover the pure-data construction helpers and the structural
+ * parameter placeholder. They don't hit a running ekoDB — server-side
+ * behavior is covered by the Rust integration tests in
+ * `ekodb/ekodb_server/tests/function_parameters_tests.rs`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const functions_1 = require("./functions");
+(0, vitest_1.describe)("parameterRef", () => {
+    (0, vitest_1.it)("produces the structural placeholder shape ekoDB's resolver expects", () => {
+        (0, vitest_1.expect)((0, functions_1.parameterRef)("record")).toEqual({
+            type: "Parameter",
+            name: "record",
+        });
+    });
+    (0, vitest_1.it)("preserves an arbitrary parameter name verbatim", () => {
+        (0, vitest_1.expect)((0, functions_1.parameterRef)("user_id").name).toBe("user_id");
+    });
+});
+(0, vitest_1.describe)("Stage.param", () => {
+    (0, vitest_1.it)("is an alias for parameterRef(name)", () => {
+        (0, vitest_1.expect)(functions_1.Stage.param("x")).toEqual((0, functions_1.parameterRef)("x"));
+    });
+});
+(0, vitest_1.describe)("Stage.insert with a structural parameter placeholder", () => {
+    (0, vitest_1.it)("embeds the whole-record placeholder into Insert.record", () => {
+        const stage = functions_1.Stage.insert("users", functions_1.Stage.param("record"));
+        (0, vitest_1.expect)(stage.type).toBe("Insert");
+        (0, vitest_1.expect)(stage.collection).toBe("users");
+        (0, vitest_1.expect)(stage.record).toEqual({ type: "Parameter", name: "record" });
+    });
+    (0, vitest_1.it)("also accepts per-field placeholders mixed with literal values", () => {
+        const stage = functions_1.Stage.insert("items", {
+            label: "{{label}}",
+            parent_id: functions_1.Stage.param("parent_id"),
+            kind: "item",
+            tags: functions_1.Stage.param("tags"),
+        });
+        (0, vitest_1.expect)(stage.record.label).toBe("{{label}}");
+        (0, vitest_1.expect)(stage.record.parent_id).toEqual({
+            type: "Parameter",
+            name: "parent_id",
+        });
+        (0, vitest_1.expect)(stage.record.kind).toBe("item");
+        (0, vitest_1.expect)(stage.record.tags).toEqual({ type: "Parameter", name: "tags" });
+    });
+});
+(0, vitest_1.describe)("Stage.updateById with a structural parameter placeholder", () => {
+    (0, vitest_1.it)("embeds the whole-updates placeholder into UpdateById.updates", () => {
+        const stage = functions_1.Stage.updateById("items", "{{id}}", functions_1.Stage.param("updates"));
+        (0, vitest_1.expect)(stage.type).toBe("UpdateById");
+        (0, vitest_1.expect)(stage.collection).toBe("items");
+        (0, vitest_1.expect)(stage.record_id).toBe("{{id}}");
+        (0, vitest_1.expect)(stage.updates).toEqual({ type: "Parameter", name: "updates" });
+    });
+    (0, vitest_1.it)("accepts per-field placeholders for partial fine-grained updates", () => {
+        const stage = functions_1.Stage.updateById("items", "{{id}}", {
+            label: "{{label}}",
+            updated_at: "{{updated_at}}",
+        });
+        (0, vitest_1.expect)(stage.updates.label).toBe("{{label}}");
+        (0, vitest_1.expect)(stage.updates.updated_at).toBe("{{updated_at}}");
+    });
+});
+(0, vitest_1.describe)("Stage.update (filter-based) with structural updates", () => {
+    (0, vitest_1.it)("accepts a Parameter placeholder in both filter values and the updates body", () => {
+        const stage = functions_1.Stage.update("items", {
+            type: "Condition",
+            content: {
+                field: "id",
+                operator: "Eq",
+                value: functions_1.Stage.param("id"),
+            },
+        }, functions_1.Stage.param("updates"));
+        (0, vitest_1.expect)(stage.type).toBe("Update");
+        (0, vitest_1.expect)(stage.filter).toEqual({
+            type: "Condition",
+            content: {
+                field: "id",
+                operator: "Eq",
+                value: { type: "Parameter", name: "id" },
+            },
+        });
+        (0, vitest_1.expect)(stage.updates).toEqual({ type: "Parameter", name: "updates" });
+    });
+});
+(0, vitest_1.describe)("Stage.batchInsert with structural placeholders inside each record", () => {
+    (0, vitest_1.it)("lets callers template each record's record-body from params", () => {
+        const stage = functions_1.Stage.batchInsert("audit_log", [
+            { actor: functions_1.Stage.param("user_id"), at: "{{now}}", message: "created" },
+            { actor: functions_1.Stage.param("user_id"), at: "{{now}}", message: "initialized" },
+        ]);
+        (0, vitest_1.expect)(stage.type).toBe("BatchInsert");
+        (0, vitest_1.expect)(stage.records).toHaveLength(2);
+        (0, vitest_1.expect)(stage.records[0].actor).toEqual({
+            type: "Parameter",
+            name: "user_id",
+        });
+        (0, vitest_1.expect)(stage.records[0].at).toBe("{{now}}");
+        (0, vitest_1.expect)(stage.records[1].message).toBe("initialized");
+    });
+});
+(0, vitest_1.describe)("JSON serialization round-trip (what actually goes on the wire)", () => {
+    (0, vitest_1.it)("serializes a structural placeholder exactly as ekoDB expects", () => {
+        const stage = functions_1.Stage.insert("users", functions_1.Stage.param("record"));
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(stage.ttl).toBeUndefined();
+        (0, vitest_1.expect)("ttl" in wire).toBe(false);
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "Insert",
+            collection: "users",
+            record: { type: "Parameter", name: "record" },
+            bypass_ripple: false,
+        });
+    });
+});
+// ============================================================================
+// Crypto primitives: BcryptHash, BcryptVerify, RandomToken (ekoDB >= 0.41.0)
+// ============================================================================
+(0, vitest_1.describe)("Stage.bcryptHash", () => {
+    (0, vitest_1.it)("produces a BcryptHash stage with text placeholder + explicit cost", () => {
+        const stage = functions_1.Stage.bcryptHash("{{password}}", "password_hash", 12);
+        (0, vitest_1.expect)(stage.type).toBe("BcryptHash");
+        (0, vitest_1.expect)(stage.plain).toBe("{{password}}");
+        (0, vitest_1.expect)(stage.cost).toBe(12);
+        (0, vitest_1.expect)(stage.output_field).toBe("password_hash");
+    });
+    (0, vitest_1.it)("leaves cost undefined when the caller omits it", () => {
+        const stage = functions_1.Stage.bcryptHash("{{password}}", "pw_hash");
+        (0, vitest_1.expect)(stage.cost).toBeUndefined();
+    });
+});
+(0, vitest_1.describe)("Stage.bcryptVerify", () => {
+    (0, vitest_1.it)("produces a BcryptVerify stage wiring hash_field and output_field", () => {
+        const stage = functions_1.Stage.bcryptVerify("{{password}}", "password_hash", "valid");
+        (0, vitest_1.expect)(stage.type).toBe("BcryptVerify");
+        (0, vitest_1.expect)(stage.plain).toBe("{{password}}");
+        (0, vitest_1.expect)(stage.hash_field).toBe("password_hash");
+        (0, vitest_1.expect)(stage.output_field).toBe("valid");
+    });
+});
+(0, vitest_1.describe)("Stage.randomToken", () => {
+    (0, vitest_1.it)("produces a RandomToken stage with explicit encoding", () => {
+        const stage = functions_1.Stage.randomToken(32, "session_token", "hex");
+        (0, vitest_1.expect)(stage.type).toBe("RandomToken");
+        (0, vitest_1.expect)(stage.bytes).toBe(32);
+        (0, vitest_1.expect)(stage.encoding).toBe("hex");
+        (0, vitest_1.expect)(stage.output_field).toBe("session_token");
+    });
+    (0, vitest_1.it)("leaves encoding undefined by default (server treats as hex)", () => {
+        const stage = functions_1.Stage.randomToken(16, "token");
+        (0, vitest_1.expect)(stage.encoding).toBeUndefined();
+    });
+    (0, vitest_1.it)("accepts base64 and base64url encodings", () => {
+        const a = functions_1.Stage.randomToken(16, "t", "base64");
+        const b = functions_1.Stage.randomToken(16, "t", "base64url");
+        (0, vitest_1.expect)(a.encoding).toBe("base64");
+        (0, vitest_1.expect)(b.encoding).toBe("base64url");
+    });
+});
+(0, vitest_1.describe)("Crypto stages JSON wire format", () => {
+    (0, vitest_1.it)("BcryptHash round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.bcryptHash("{{password}}", "password_hash", 12);
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "BcryptHash",
+            plain: "{{password}}",
+            cost: 12,
+            output_field: "password_hash",
+        });
+    });
+    (0, vitest_1.it)("BcryptVerify round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.bcryptVerify("{{password}}", "password_hash", "valid");
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "BcryptVerify",
+            plain: "{{password}}",
+            hash_field: "password_hash",
+            output_field: "valid",
+        });
+    });
+    (0, vitest_1.it)("RandomToken round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.randomToken(32, "token", "hex");
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "RandomToken",
+            bytes: 32,
+            encoding: "hex",
+            output_field: "token",
+        });
+    });
+});
+// ============================================================================
+// Error Handling & Control Flow: TryCatch, Parallel, Sleep (ekoDB >= 0.42.0)
+// ============================================================================
+(0, vitest_1.describe)("Stage.tryCatch", () => {
+    (0, vitest_1.it)("produces a TryCatch stage with try/catch function lists", () => {
+        const stage = functions_1.Stage.tryCatch([functions_1.Stage.httpRequest("https://api.example.com/data")], [functions_1.Stage.insert("fallback_log", { error: "{{error}}" })], "api_error");
+        (0, vitest_1.expect)(stage.type).toBe("TryCatch");
+        (0, vitest_1.expect)(stage.try_functions).toHaveLength(1);
+        (0, vitest_1.expect)(stage.catch_functions).toHaveLength(1);
+        (0, vitest_1.expect)(stage.output_error_field).toBe("api_error");
+    });
+    (0, vitest_1.it)("leaves output_error_field undefined when omitted", () => {
+        const stage = functions_1.Stage.tryCatch([functions_1.Stage.findAll("users")], [functions_1.Stage.insert("errors", { msg: "failed" })]);
+        (0, vitest_1.expect)(stage.output_error_field).toBeUndefined();
+    });
+});
+(0, vitest_1.describe)("Stage.parallel", () => {
+    (0, vitest_1.it)("produces a Parallel stage with functions and wait_for_all", () => {
+        const stage = functions_1.Stage.parallel([functions_1.Stage.findAll("users"), functions_1.Stage.findAll("orders")], true);
+        (0, vitest_1.expect)(stage.type).toBe("Parallel");
+        (0, vitest_1.expect)(stage.functions).toHaveLength(2);
+        (0, vitest_1.expect)(stage.wait_for_all).toBe(true);
+    });
+    (0, vitest_1.it)("defaults wait_for_all to true", () => {
+        const stage = functions_1.Stage.parallel([functions_1.Stage.findAll("users")]);
+        (0, vitest_1.expect)(stage.wait_for_all).toBe(true);
+    });
+    (0, vitest_1.it)("accepts wait_for_all = false for race semantics", () => {
+        const stage = functions_1.Stage.parallel([functions_1.Stage.findAll("users"), functions_1.Stage.findAll("cache")], false);
+        (0, vitest_1.expect)(stage.wait_for_all).toBe(false);
+    });
+});
+(0, vitest_1.describe)("Stage.sleep", () => {
+    (0, vitest_1.it)("produces a Sleep stage with numeric duration", () => {
+        const stage = functions_1.Stage.sleep(1000);
+        (0, vitest_1.expect)(stage.type).toBe("Sleep");
+        (0, vitest_1.expect)(stage.duration_ms).toBe(1000);
+    });
+    (0, vitest_1.it)("accepts a text placeholder for parameter substitution", () => {
+        const stage = functions_1.Stage.sleep("{{delay}}");
+        (0, vitest_1.expect)(stage.duration_ms).toBe("{{delay}}");
+    });
+});
+// ============================================================================
+// Response Formatting: Return (ekoDB >= 0.42.0)
+// ============================================================================
+(0, vitest_1.describe)("Stage.returnResponse", () => {
+    (0, vitest_1.it)("produces a Return stage with fields and status_code", () => {
+        const stage = functions_1.Stage.returnResponse({ message: "ok", user_id: "{{id}}" }, 201);
+        (0, vitest_1.expect)(stage.type).toBe("Return");
+        (0, vitest_1.expect)(stage.fields).toEqual({ message: "ok", user_id: "{{id}}" });
+        (0, vitest_1.expect)(stage.status_code).toBe(201);
+    });
+    (0, vitest_1.it)("leaves status_code undefined when omitted (server defaults to 200)", () => {
+        const stage = functions_1.Stage.returnResponse({ success: true });
+        (0, vitest_1.expect)(stage.status_code).toBeUndefined();
+    });
+});
+// ============================================================================
+// Data Validation: Validate (ekoDB >= 0.42.0)
+// ============================================================================
+(0, vitest_1.describe)("Stage.validate", () => {
+    (0, vitest_1.it)("produces a Validate stage with schema, data_field, and on_error", () => {
+        const schema = {
+            type: "object",
+            required: ["name", "email"],
+            properties: {
+                name: { type: "string" },
+                email: { type: "string", format: "email" },
+            },
+        };
+        const stage = functions_1.Stage.validate(schema, "{{input}}", [
+            functions_1.Stage.returnResponse({ error: "validation failed" }, 400),
+        ]);
+        (0, vitest_1.expect)(stage.type).toBe("Validate");
+        (0, vitest_1.expect)(stage.schema).toEqual(schema);
+        (0, vitest_1.expect)(stage.data_field).toBe("{{input}}");
+        (0, vitest_1.expect)(stage.on_error).toHaveLength(1);
+    });
+    (0, vitest_1.it)("leaves on_error undefined when omitted", () => {
+        const stage = functions_1.Stage.validate({ type: "object" }, "record");
+        (0, vitest_1.expect)(stage.on_error).toBeUndefined();
+    });
+});
+// ============================================================================
+// New stages JSON wire format
+// ============================================================================
+(0, vitest_1.describe)("New stages JSON wire format", () => {
+    (0, vitest_1.it)("TryCatch round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.tryCatch([functions_1.Stage.findAll("users")], [functions_1.Stage.insert("errors", { msg: "failed" })], "err");
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire.type).toBe("TryCatch");
+        (0, vitest_1.expect)(wire.try_functions).toHaveLength(1);
+        (0, vitest_1.expect)(wire.catch_functions).toHaveLength(1);
+        (0, vitest_1.expect)(wire.output_error_field).toBe("err");
+    });
+    (0, vitest_1.it)("Parallel round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.parallel([functions_1.Stage.findAll("a"), functions_1.Stage.findAll("b")], false);
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "Parallel",
+            functions: [
+                { type: "FindAll", collection: "a" },
+                { type: "FindAll", collection: "b" },
+            ],
+            wait_for_all: false,
+        });
+    });
+    (0, vitest_1.it)("Sleep round-trips through JSON unchanged", () => {
+        const wire = JSON.parse(JSON.stringify(functions_1.Stage.sleep(500)));
+        (0, vitest_1.expect)(wire).toEqual({ type: "Sleep", duration_ms: 500 });
+    });
+    (0, vitest_1.it)("Return round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.returnResponse({ ok: true }, 201);
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "Return",
+            fields: { ok: true },
+            status_code: 201,
+        });
+    });
+    (0, vitest_1.it)("Validate round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.validate({ type: "object" }, "data");
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "Validate",
+            schema: { type: "object" },
+            data_field: "data",
+        });
+    });
+});

package/dist/index.d.ts

@@ -3,12 +3,13 @@ export { QueryBuilder, SortOrder } from "./query-builder";
 export { SearchQueryBuilder } from "./search";
 export { SchemaBuilder, FieldTypeSchemaBuilder, VectorIndexAlgorithm, DistanceMetric, } from "./schema";
 export { JoinBuilder } from "./join";
-export { Stage, ChatMessage } from "./functions";
+export { Stage, ChatMessage, parameterRef } from "./functions";
+export type { ParameterRef } from "./functions";
 export { getValue, getValues, extractRecord, getDateTimeValue, getUUIDValue, getDecimalValue, getDurationValue, getBytesValue, getBinaryValue, getArrayValue, getSetValue, getVectorValue, getObjectValue, Field, } from "./utils";
 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/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Field = exports.getObjectValue = exports.getVectorValue = exports.getSetValue = exports.getArrayValue = exports.getBinaryValue = exports.getBytesValue = exports.getDurationValue = exports.getDecimalValue = exports.getUUIDValue = exports.getDateTimeValue = exports.extractRecord = exports.getValues = exports.getValue = exports.ChatMessage = exports.Stage = exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.extractRecordId = exports.SchemaCache = exports.RateLimitError = exports.MergeStrategy = exports.SerializationFormat = exports.EventStream = exports.WebSocketClient = exports.EkoDBClient = void 0;
+exports.Field = exports.getObjectValue = exports.getVectorValue = exports.getSetValue = exports.getArrayValue = exports.getBinaryValue = exports.getBytesValue = exports.getDurationValue = exports.getDecimalValue = exports.getUUIDValue = exports.getDateTimeValue = exports.extractRecord = exports.getValues = exports.getValue = exports.parameterRef = exports.ChatMessage = exports.Stage = exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.extractRecordId = exports.SchemaCache = exports.RateLimitError = exports.MergeStrategy = exports.SerializationFormat = exports.EventStream = exports.WebSocketClient = exports.EkoDBClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "EkoDBClient", { enumerable: true, get: function () { return client_1.EkoDBClient; } });
 Object.defineProperty(exports, "WebSocketClient", { enumerable: true, get: function () { return client_1.WebSocketClient; } });
@@ -25,6 +25,7 @@ Object.defineProperty(exports, "JoinBuilder", { enumerable: true, get: function
 var functions_1 = require("./functions");
 Object.defineProperty(exports, "Stage", { enumerable: true, get: function () { return functions_1.Stage; } });
 Object.defineProperty(exports, "ChatMessage", { enumerable: true, get: function () { return functions_1.ChatMessage; } });
+Object.defineProperty(exports, "parameterRef", { enumerable: true, get: function () { return functions_1.parameterRef; } });
 var utils_1 = require("./utils");
 Object.defineProperty(exports, "getValue", { enumerable: true, get: function () { return utils_1.getValue; } });
 Object.defineProperty(exports, "getValues", { enumerable: true, get: function () { return utils_1.getValues; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.15.2",
+  "version": "0.17.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();
   });
 });
@@ -2674,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");
+  });
+});