@ekodb/ekodb-client 0.25.0 → 0.26.0

package/README.md

@@ -308,8 +308,11 @@ const joinResults = await client.find("users", multiQuery);
 
 #### Chat Models
 
-- `getChatModels(): Promise<Record<string, string[]>>` - Get all available chat
-  models by provider
+- `getChatModels(): Promise<ChatModels>` - Get all available chat models by
+  provider (`openai`, `anthropic`, `perplexity`, `gemini`), plus a per-provider
+  `providers` status map (`ok`, `not_configured`, `auth_failed`,
+  `permission_denied`, `billing`, `rate_limited`, `unavailable`, `unreachable`,
+  `request_error`) so a rejected key is distinguishable from a missing one
 - `getChatModel(provider: string): Promise<string[]>` - Get models for a
   specific provider
 

package/dist/client.d.ts

@@ -326,12 +326,45 @@ export interface MergeSessionsRequest {
     bypass_ripple?: boolean;
 }
 /**
- * Available chat models by provider
+ * A provider's state on `GET /api/chat_models`. The union lists the states
+ * this client knows; the `string` escape keeps a newer server's status from
+ * failing to type-check.
+ */
+export type ChatProviderState = "ok" | "not_configured" | "auth_failed" | "permission_denied" | "billing" | "rate_limited" | "unavailable" | "unreachable" | "request_error" | (string & {});
+/**
+ * One provider's row in `ChatModels.providers`.
+ */
+export interface ChatProviderStatus {
+    status: ChatProviderState;
+    /**
+     * True when the status is the provider's own answer about the configured
+     * key. A 5xx, a refused connection, or a missing key says nothing about it.
+     */
+    verified: boolean;
+    /** The provider's own HTTP status, when it answered. */
+    http_status?: number;
+    /** The provider's own message, when it answered. */
+    message?: string;
+    /** How many models were listed, when the status is `ok`. */
+    model_count?: number;
+}
+/**
+ * Available chat models by provider, and why each list looks the way it does.
  */
 export interface ChatModels {
     openai: string[];
     anthropic: string[];
     perplexity: string[];
+    /** Google Gemini models. Absent from a server that predates the field. */
+    gemini?: string[];
+    /**
+     * Per-provider status keyed by provider name. A rejected key reports
+     * `auth_failed` where a missing one reports `not_configured`, so an empty
+     * list is never ambiguous. Absent from a server that predates the map.
+     */
+    providers?: {
+        [provider: string]: ChatProviderStatus;
+    };
 }
 /**
  * Request to compact a chat session's history on demand.
@@ -1389,6 +1422,19 @@ export type ChatStreamEvent = {
 } | {
     type: "error";
     error: string;
+    /**
+     * The provider-failure classification (`provider_auth_failed`,
+     * `provider_permission_denied`, `provider_billing`,
+     * `provider_rate_limited`, `provider_unavailable`,
+     * `provider_unreachable`, `provider_not_configured`,
+     * `provider_request_error`), when the failure was the LLM provider's
+     * answer. Absent for a transport failure or a plain server error.
+     */
+    errorKind?: string;
+    provider?: string;
+    /** The provider's own HTTP status. */
+    providerStatus?: number;
+    retryAfterSecs?: number;
 };
 /** Definition for a client-side tool the LLM can call. */
 export interface ClientToolDefinition {

package/dist/client.js

@@ -2,39 +2,6 @@
 /**
  * ekoDB TypeScript Client
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebSocketClient = exports.SchemaCache = exports.EventStream = exports.EkoDBClient = exports.MergeStrategy = exports.HealthStatus = exports.HealthUnknown = exports.HealthDegraded = exports.HealthOK = exports.RateLimitError = exports.DEFAULT_REQUEST_TIMEOUT_MS = exports.SerializationFormat = void 0;
 exports.parseHealthStatus = parseHealthStatus;
@@ -1454,7 +1421,22 @@ class EkoDBClient {
                     stream.close();
                     return;
                 }
+                // The `event:` name applies to the data lines that follow it, until
+                // the blank line that ends the frame. An error frame ends the stream:
+                // nothing after it is surfaced and the body is not read to the end,
+                // so a server or proxy that keeps the connection open after an error
+                // cannot hang the caller (the Rust and Go clients stop the same way).
+                let eventName = "";
+                let stopped = false;
                 const emitLine = (line) => {
+                    if (line.startsWith("event:")) {
+                        eventName = line.slice(6).trim();
+                        return;
+                    }
+                    if (line.trim() === "") {
+                        eventName = "";
+                        return;
+                    }
                     if (!line.startsWith("data:"))
                         return;
                     const dataStr = line.slice(5).trim();
@@ -1462,10 +1444,16 @@ class EkoDBClient {
                         return;
                     try {
                         const eventData = JSON.parse(dataStr);
-                        if (eventData.error) {
+                        // An error frame is one the server names `error`, or whose
+                        // payload carries an `error`; a `message`-only payload is still
+                        // the error rather than a frame to skip, and the text is always a
+                        // string (`streamErrorText`).
+                        if (eventData.error != null || eventName === "error") {
+                            stopped = true;
                             stream.emit("event", {
                                 type: "error",
-                                error: eventData.error,
+                                error: streamErrorText(eventData),
+                                ...providerFailureFields(eventData),
                             });
                         }
                         else if (eventData.content && eventData.message_id) {
@@ -1501,20 +1489,29 @@ class EkoDBClient {
                             break;
                         buffer += decoder.decode(value, { stream: true });
                         let nl;
-                        while ((nl = buffer.indexOf("\n")) >= 0) {
+                        while (!stopped && (nl = buffer.indexOf("\n")) >= 0) {
                             emitLine(buffer.slice(0, nl));
                             buffer = buffer.slice(nl + 1);
                         }
+                        if (stopped) {
+                            await reader.cancel?.()?.catch?.(() => { });
+                            break;
+                        }
+                    }
+                    if (!stopped) {
+                        buffer += decoder.decode();
+                        if (buffer)
+                            emitLine(buffer);
                     }
-                    buffer += decoder.decode();
-                    if (buffer)
-                        emitLine(buffer);
                 }
                 else {
                     // Fallback for environments/tests without a readable body stream.
                     const body = await response.text();
-                    for (const line of body.split("\n"))
+                    for (const line of body.split("\n")) {
                         emitLine(line);
+                        if (stopped)
+                            break;
+                    }
                 }
                 stream.close();
             }
@@ -2216,6 +2213,32 @@ class EkoDBClient {
     }
 }
 exports.EkoDBClient = EkoDBClient;
+/**
+ * The text of a stream error frame: the first of `error` / `message` that is
+ * a non-empty string, else a fixed fallback — a structured `error` object is
+ * still an error, never a non-string `error` on the event. Shared by the SSE
+ * and WebSocket routes so the two cannot drift.
+ */
+function streamErrorText(payload) {
+    const text = (value) => typeof value === "string" && value ? value : undefined;
+    return text(payload.error) ?? text(payload.message) ?? "Unknown error";
+}
+/**
+ * The classification fields of a stream error frame, only those present, so
+ * a plain error stays `{ type, error }`.
+ */
+function providerFailureFields(eventData) {
+    const fields = {};
+    if (typeof eventData.error_kind === "string")
+        fields.errorKind = eventData.error_kind;
+    if (typeof eventData.provider === "string")
+        fields.provider = eventData.provider;
+    if (typeof eventData.provider_status === "number")
+        fields.providerStatus = eventData.provider_status;
+    if (typeof eventData.retry_after_secs === "number")
+        fields.retryAfterSecs = eventData.retry_after_secs;
+    return fields;
+}
 /** EventEmitter-like interface for subscriptions and chat streams. */
 class EventStream {
     constructor() {
@@ -2429,7 +2452,7 @@ class WebSocketClient {
         return this.connectPromise;
     }
     async openSocket() {
-        const WebSocket = (await Promise.resolve().then(() => __importStar(require("ws")))).default;
+        const WebSocket = (await import("ws")).default;
         let url = this.wsURL;
         if (!url.endsWith("/api/ws")) {
             url += "/api/ws";
@@ -2761,9 +2784,12 @@ class WebSocketClient {
                 const chatId = msg.payload?.chat_id || msg.payload?.chatId;
                 const stream = this.chatStreams.get(chatId);
                 if (stream) {
+                    // The text guard and the classification are the SSE route's,
+                    // so the two routes emit the same shape.
                     stream.emit("event", {
                         type: "error",
-                        error: msg.payload.error || msg.payload.message || "Unknown error",
+                        error: streamErrorText(msg.payload),
+                        ...providerFailureFields(msg.payload),
                     });
                     this.chatStreams.delete(chatId);
                     stream.close();

package/dist/client.test.js

@@ -1045,6 +1045,47 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(result.anthropic).toHaveLength(2);
         (0, vitest_1.expect)(result.perplexity).toHaveLength(1);
     });
+    (0, vitest_1.it)("carries gemini and the per-provider status from the server", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({
+            openai: [],
+            anthropic: ["claude-sonnet-4-5"],
+            perplexity: ["sonar"],
+            gemini: ["gemini-2.5-flash"],
+            providers: {
+                anthropic: { status: "ok", verified: true, model_count: 1 },
+                gemini: { status: "ok", verified: true, model_count: 1 },
+                openai: {
+                    status: "auth_failed",
+                    verified: true,
+                    http_status: 401,
+                    message: "Failed to fetch OpenAI models: 401 Unauthorized",
+                },
+                perplexity: {
+                    status: "ok",
+                    verified: false,
+                    message: "static model list; key not verified",
+                },
+            },
+        });
+        const result = await client.getChatModels();
+        (0, vitest_1.expect)(result.gemini).toEqual(["gemini-2.5-flash"]);
+        (0, vitest_1.expect)(result.providers?.openai.status).toBe("auth_failed");
+        (0, vitest_1.expect)(result.providers?.openai.http_status).toBe(401);
+        (0, vitest_1.expect)(result.providers?.openai.verified).toBe(true);
+        (0, vitest_1.expect)(result.providers?.perplexity.verified).toBe(false);
+        (0, vitest_1.expect)(result.providers?.anthropic.model_count).toBe(1);
+    });
+    (0, vitest_1.it)("tolerates a server that predates gemini and providers", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        mockJsonResponse({ openai: ["gpt-4o"], anthropic: [], perplexity: [] });
+        const result = await client.getChatModels();
+        (0, vitest_1.expect)(result.openai).toEqual(["gpt-4o"]);
+        (0, vitest_1.expect)(result.gemini).toBeUndefined();
+        (0, vitest_1.expect)(result.providers).toBeUndefined();
+    });
     (0, vitest_1.it)("gets models for specific provider", async () => {
         const client = createTestClient();
         mockTokenResponse();
@@ -1909,6 +1950,112 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(events[2].messageId).toBe("msg_1");
         (0, vitest_1.expect)(events[2].executionTimeMs).toBe(42);
     });
+    (0, vitest_1.it)("treats a frame named error as an error even when its payload says message", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        const sseBody = 'event: token\ndata: {"token":"Hel"}\n\nevent: error\ndata: {"message":"boom"}\n\n';
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            text: async () => sseBody,
+            headers: new Headers({ "content-type": "text/event-stream" }),
+        });
+        const events = [];
+        const stream = client.chatMessageStream("chat_123", {
+            message: "Hello",
+        });
+        stream.on("event", (evt) => events.push(evt));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        (0, vitest_1.expect)(events).toEqual([
+            { type: "chunk", content: "Hel" },
+            { type: "error", error: "boom" },
+        ]);
+    });
+    (0, vitest_1.it)("stops reading after an error frame and emits nothing that follows it", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        const sseBody = 'event: error\ndata: {"message":"boom"}\n\nevent: token\ndata: {"token":"late"}\n\n';
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            text: async () => sseBody,
+            headers: new Headers({ "content-type": "text/event-stream" }),
+        });
+        const events = [];
+        const stream = client.chatMessageStream("chat_123", {
+            message: "Hello",
+        });
+        stream.on("event", (evt) => events.push(evt));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        (0, vitest_1.expect)(events).toEqual([{ type: "error", error: "boom" }]);
+    });
+    (0, vitest_1.it)("cancels the body reader after an error frame instead of waiting for the server to close", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        const encoder = new TextEncoder();
+        const chunks = [
+            encoder.encode('event: error\ndata: {"message":"boom"}\n\n'),
+            encoder.encode('event: token\ndata: {"token":"late"}\n\n'),
+        ];
+        const cancel = vitest_1.vi.fn(async () => { });
+        let reads = 0;
+        const reader = {
+            read: vitest_1.vi.fn(async () => {
+                // A server (or proxy) that does not close after the error frame: it
+                // keeps sending frames. Bounded so a client that never stops fails
+                // the assertions below instead of looping forever.
+                if (reads >= 50)
+                    return { done: true, value: undefined };
+                const value = chunks[Math.min(reads, chunks.length - 1)];
+                reads += 1;
+                return { done: false, value };
+            }),
+            cancel,
+        };
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            body: { getReader: () => reader },
+            text: async () => "",
+            headers: new Headers({ "content-type": "text/event-stream" }),
+        });
+        const events = [];
+        const stream = client.chatMessageStream("chat_123", {
+            message: "Hello",
+        });
+        stream.on("event", (evt) => events.push(evt));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        (0, vitest_1.expect)(events).toEqual([{ type: "error", error: "boom" }]);
+        // One read delivered the error frame; the reader was cancelled rather
+        // than read until the server closed.
+        (0, vitest_1.expect)(reader.read).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(cancel).toHaveBeenCalledTimes(1);
+    });
+    (0, vitest_1.it)("keeps the error text a string when the server sends a structured error", async () => {
+        const client = createTestClient();
+        mockTokenResponse();
+        const sseBody = 'event: error\ndata: {"error":{"code":"upstream_down","status":503},"error_kind":"provider_unavailable","provider":"openai"}\n\n';
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            text: async () => sseBody,
+            headers: new Headers({ "content-type": "text/event-stream" }),
+        });
+        const events = [];
+        const stream = client.chatMessageStream("chat_123", {
+            message: "Hello",
+        });
+        stream.on("event", (evt) => events.push(evt));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        (0, vitest_1.expect)(events).toEqual([
+            {
+                type: "error",
+                error: "Unknown error",
+                errorKind: "provider_unavailable",
+                provider: "openai",
+            },
+        ]);
+    });
     (0, vitest_1.it)("emits error event on SSE error", async () => {
         const client = createTestClient();
         mockTokenResponse();
@@ -1928,6 +2075,36 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(events).toHaveLength(1);
         (0, vitest_1.expect)(events[0]).toEqual({ type: "error", error: "LLM timeout" });
     });
+    (0, vitest_1.it)("carries the provider failure classification on an error event", async () => {
+        // The deployment classifies a provider failure (`error_kind`, `provider`,
+        // `provider_status`, `retry_after_secs` on the wire); the event carries
+        // every one of them, in this shape's camelCase, so a consumer can act on
+        // it without string-matching.
+        const client = createTestClient();
+        mockTokenResponse();
+        const sseBody = 'data: {"error":"OpenAI API error: Incorrect API key provided","error_kind":"provider_auth_failed","provider":"openai","provider_status":401}\n';
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            text: async () => sseBody,
+            headers: new Headers({ "content-type": "text/event-stream" }),
+        });
+        const events = [];
+        const stream = client.chatMessageStream("chat_123", {
+            message: "Hello",
+        });
+        stream.on("event", (evt) => events.push(evt));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        (0, vitest_1.expect)(events).toEqual([
+            {
+                type: "error",
+                error: "OpenAI API error: Incorrect API key provided",
+                errorKind: "provider_auth_failed",
+                provider: "openai",
+                providerStatus: 401,
+            },
+        ]);
+    });
     (0, vitest_1.it)("emits error event on non-200 HTTP response", async () => {
         const client = createTestClient();
         mockTokenResponse();

package/dist/index.d.ts

@@ -13,4 +13,4 @@ export type { Schema, FieldTypeSchema, IndexConfig, CollectionMetadata, } from "
 export type { JoinConfig } from "./join";
 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, CompactChatRequest, CompactChatResponse, EmbedRequest, EmbedResponse, RawCompletionRequest, RawCompletionResponse, 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, ChatProviderState, ChatProviderStatus, CompactChatRequest, CompactChatResponse, EmbedRequest, EmbedResponse, RawCompletionRequest, RawCompletionResponse, ToolChoice, ToolConfig, } from "./client";

package/dist/websocket.test.js

@@ -300,6 +300,72 @@ function waitForMessage(ws) {
             (0, vitest_1.expect)(stream.closed).toBe(true);
             client.close();
         });
+        // The WebSocket route carries the provider-failure classification like
+        // the SSE route does, in the event's camelCase shape.
+        (0, vitest_1.it)("carries the provider failure classification on a chat stream error", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            const streamPromise = client.chatSend("chat-4", "test");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            await waitForMessage(ws);
+            const stream = await streamPromise;
+            const events = [];
+            stream.on("event", (e) => events.push(e));
+            ws.send(JSON.stringify({
+                type: "ChatStreamError",
+                payload: {
+                    chat_id: "chat-4",
+                    error: "OpenAI API error 429 Too Many Requests",
+                    error_kind: "provider_rate_limited",
+                    provider: "openai",
+                    provider_status: 429,
+                    retry_after_secs: 7,
+                },
+            }));
+            await new Promise((r) => stream.on("close", r));
+            (0, vitest_1.expect)(events).toEqual([
+                {
+                    type: "error",
+                    error: "OpenAI API error 429 Too Many Requests",
+                    errorKind: "provider_rate_limited",
+                    provider: "openai",
+                    providerStatus: 429,
+                    retryAfterSecs: 7,
+                },
+            ]);
+            client.close();
+        });
+        // A structured `error` value is still an error, with string text — the
+        // WebSocket route guards the shape exactly as the SSE route does.
+        (0, vitest_1.it)("keeps the error text a string when the payload's error is an object", async () => {
+            const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
+            const streamPromise = client.chatSend("chat-5", "test");
+            await new Promise((r) => wss.once("connection", r));
+            const ws = getLastConnection();
+            await waitForMessage(ws);
+            const stream = await streamPromise;
+            const events = [];
+            stream.on("event", (e) => events.push(e));
+            ws.send(JSON.stringify({
+                type: "ChatStreamError",
+                payload: {
+                    chat_id: "chat-5",
+                    error: { code: "upstream_down", status: 503 },
+                    error_kind: "provider_unavailable",
+                    provider: "gemini",
+                },
+            }));
+            await new Promise((r) => stream.on("close", r));
+            (0, vitest_1.expect)(events).toEqual([
+                {
+                    type: "error",
+                    error: "Unknown error",
+                    errorKind: "provider_unavailable",
+                    provider: "gemini",
+                },
+            ]);
+            client.close();
+        });
         (0, vitest_1.it)("sends options with ChatSend", async () => {
             const client = new client_1.WebSocketClient(`ws://localhost:${port}/api/ws`, "test-token");
             const streamPromise = client.chatSend("chat-3", "Hello", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Official TypeScript/JavaScript client for ekoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,7 +22,7 @@
   "devDependencies": {
     "@types/node": "^24.13.2",
     "@types/ws": "^8.18.1",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.3",
     "vitest": "^4.0.18"
   },
   "dependencies": {

package/src/client.test.ts

@@ -13,6 +13,7 @@ import {
   DEFAULT_REQUEST_TIMEOUT_MS,
   parseHealthStatus,
 } from "./client";
+import type { ChatModels } from "./client";
 import { SearchQueryBuilder } from "./search";
 
 // Mock fetch globally
@@ -1436,6 +1437,55 @@ describe("EkoDBClient chat models", () => {
     expect(result.perplexity).toHaveLength(1);
   });
 
+  it("carries gemini and the per-provider status from the server", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({
+      openai: [],
+      anthropic: ["claude-sonnet-4-5"],
+      perplexity: ["sonar"],
+      gemini: ["gemini-2.5-flash"],
+      providers: {
+        anthropic: { status: "ok", verified: true, model_count: 1 },
+        gemini: { status: "ok", verified: true, model_count: 1 },
+        openai: {
+          status: "auth_failed",
+          verified: true,
+          http_status: 401,
+          message: "Failed to fetch OpenAI models: 401 Unauthorized",
+        },
+        perplexity: {
+          status: "ok",
+          verified: false,
+          message: "static model list; key not verified",
+        },
+      },
+    });
+
+    const result: ChatModels = await client.getChatModels();
+
+    expect(result.gemini).toEqual(["gemini-2.5-flash"]);
+    expect(result.providers?.openai.status).toBe("auth_failed");
+    expect(result.providers?.openai.http_status).toBe(401);
+    expect(result.providers?.openai.verified).toBe(true);
+    expect(result.providers?.perplexity.verified).toBe(false);
+    expect(result.providers?.anthropic.model_count).toBe(1);
+  });
+
+  it("tolerates a server that predates gemini and providers", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ openai: ["gpt-4o"], anthropic: [], perplexity: [] });
+
+    const result: ChatModels = await client.getChatModels();
+
+    expect(result.openai).toEqual(["gpt-4o"]);
+    expect(result.gemini).toBeUndefined();
+    expect(result.providers).toBeUndefined();
+  });
+
   it("gets models for specific provider", async () => {
     const client = createTestClient();
 
@@ -2572,6 +2622,138 @@ describe("EkoDBClient chatMessageStream", () => {
     expect(events[2].executionTimeMs).toBe(42);
   });
 
+  it("treats a frame named error as an error even when its payload says message", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const sseBody =
+      'event: token\ndata: {"token":"Hel"}\n\nevent: error\ndata: {"message":"boom"}\n\n';
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toEqual([
+      { type: "chunk", content: "Hel" },
+      { type: "error", error: "boom" },
+    ]);
+  });
+
+  it("stops reading after an error frame and emits nothing that follows it", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const sseBody =
+      'event: error\ndata: {"message":"boom"}\n\nevent: token\ndata: {"token":"late"}\n\n';
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toEqual([{ type: "error", error: "boom" }]);
+  });
+
+  it("cancels the body reader after an error frame instead of waiting for the server to close", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const encoder = new TextEncoder();
+    const chunks = [
+      encoder.encode('event: error\ndata: {"message":"boom"}\n\n'),
+      encoder.encode('event: token\ndata: {"token":"late"}\n\n'),
+    ];
+    const cancel = vi.fn(async () => {});
+    let reads = 0;
+    const reader = {
+      read: vi.fn(async () => {
+        // A server (or proxy) that does not close after the error frame: it
+        // keeps sending frames. Bounded so a client that never stops fails
+        // the assertions below instead of looping forever.
+        if (reads >= 50) return { done: true, value: undefined };
+        const value = chunks[Math.min(reads, chunks.length - 1)];
+        reads += 1;
+        return { done: false, value };
+      }),
+      cancel,
+    };
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      body: { getReader: () => reader },
+      text: async () => "",
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toEqual([{ type: "error", error: "boom" }]);
+    // One read delivered the error frame; the reader was cancelled rather
+    // than read until the server closed.
+    expect(reader.read).toHaveBeenCalledTimes(1);
+    expect(cancel).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the error text a string when the server sends a structured error", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const sseBody =
+      'event: error\ndata: {"error":{"code":"upstream_down","status":503},"error_kind":"provider_unavailable","provider":"openai"}\n\n';
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toEqual([
+      {
+        type: "error",
+        error: "Unknown error",
+        errorKind: "provider_unavailable",
+        provider: "openai",
+      },
+    ]);
+  });
+
   it("emits error event on SSE error", async () => {
     const client = createTestClient();
     mockTokenResponse();
@@ -2597,6 +2779,43 @@ describe("EkoDBClient chatMessageStream", () => {
     expect(events[0]).toEqual({ type: "error", error: "LLM timeout" });
   });
 
+  it("carries the provider failure classification on an error event", async () => {
+    // The deployment classifies a provider failure (`error_kind`, `provider`,
+    // `provider_status`, `retry_after_secs` on the wire); the event carries
+    // every one of them, in this shape's camelCase, so a consumer can act on
+    // it without string-matching.
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const sseBody =
+      'data: {"error":"OpenAI API error: Incorrect API key provided","error_kind":"provider_auth_failed","provider":"openai","provider_status":401}\n';
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toEqual([
+      {
+        type: "error",
+        error: "OpenAI API error: Incorrect API key provided",
+        errorKind: "provider_auth_failed",
+        provider: "openai",
+        providerStatus: 401,
+      },
+    ]);
+  });
+
   it("emits error event on non-200 HTTP response", async () => {
     const client = createTestClient();
     mockTokenResponse();

package/src/client.ts

@@ -416,12 +416,55 @@ export interface MergeSessionsRequest {
 }
 
 /**
- * Available chat models by provider
+ * A provider's state on `GET /api/chat_models`. The union lists the states
+ * this client knows; the `string` escape keeps a newer server's status from
+ * failing to type-check.
+ */
+export type ChatProviderState =
+  | "ok"
+  | "not_configured"
+  | "auth_failed"
+  | "permission_denied"
+  | "billing"
+  | "rate_limited"
+  | "unavailable"
+  | "unreachable"
+  | "request_error"
+  | (string & {});
+
+/**
+ * One provider's row in `ChatModels.providers`.
+ */
+export interface ChatProviderStatus {
+  status: ChatProviderState;
+  /**
+   * True when the status is the provider's own answer about the configured
+   * key. A 5xx, a refused connection, or a missing key says nothing about it.
+   */
+  verified: boolean;
+  /** The provider's own HTTP status, when it answered. */
+  http_status?: number;
+  /** The provider's own message, when it answered. */
+  message?: string;
+  /** How many models were listed, when the status is `ok`. */
+  model_count?: number;
+}
+
+/**
+ * Available chat models by provider, and why each list looks the way it does.
  */
 export interface ChatModels {
   openai: string[];
   anthropic: string[];
   perplexity: string[];
+  /** Google Gemini models. Absent from a server that predates the field. */
+  gemini?: string[];
+  /**
+   * Per-provider status keyed by provider name. A rejected key reports
+   * `auth_failed` where a missing one reports `not_configured`, so an empty
+   * list is never ambiguous. Absent from a server that predates the map.
+   */
+  providers?: { [provider: string]: ChatProviderStatus };
 }
 
 /**
@@ -2263,16 +2306,37 @@ export class EkoDBClient {
           return;
         }
 
+        // The `event:` name applies to the data lines that follow it, until
+        // the blank line that ends the frame. An error frame ends the stream:
+        // nothing after it is surfaced and the body is not read to the end,
+        // so a server or proxy that keeps the connection open after an error
+        // cannot hang the caller (the Rust and Go clients stop the same way).
+        let eventName = "";
+        let stopped = false;
         const emitLine = (line: string) => {
+          if (line.startsWith("event:")) {
+            eventName = line.slice(6).trim();
+            return;
+          }
+          if (line.trim() === "") {
+            eventName = "";
+            return;
+          }
           if (!line.startsWith("data:")) return;
           const dataStr = line.slice(5).trim();
           if (!dataStr) return;
           try {
             const eventData = JSON.parse(dataStr);
-            if (eventData.error) {
+            // An error frame is one the server names `error`, or whose
+            // payload carries an `error`; a `message`-only payload is still
+            // the error rather than a frame to skip, and the text is always a
+            // string (`streamErrorText`).
+            if (eventData.error != null || eventName === "error") {
+              stopped = true;
               stream.emit("event", {
                 type: "error",
-                error: eventData.error,
+                error: streamErrorText(eventData),
+                ...providerFailureFields(eventData),
               } as ChatStreamEvent);
             } else if (eventData.content && eventData.message_id) {
               // Done event — has full content + message_id
@@ -2305,17 +2369,26 @@ export class EkoDBClient {
             if (done) break;
             buffer += decoder.decode(value, { stream: true });
             let nl: number;
-            while ((nl = buffer.indexOf("\n")) >= 0) {
+            while (!stopped && (nl = buffer.indexOf("\n")) >= 0) {
               emitLine(buffer.slice(0, nl));
               buffer = buffer.slice(nl + 1);
             }
+            if (stopped) {
+              await reader.cancel?.()?.catch?.(() => {});
+              break;
+            }
+          }
+          if (!stopped) {
+            buffer += decoder.decode();
+            if (buffer) emitLine(buffer);
           }
-          buffer += decoder.decode();
-          if (buffer) emitLine(buffer);
         } else {
           // Fallback for environments/tests without a readable body stream.
           const body = await response.text();
-          for (const line of body.split("\n")) emitLine(line);
+          for (const line of body.split("\n")) {
+            emitLine(line);
+            if (stopped) break;
+          }
         }
         stream.close();
       } catch (err: any) {
@@ -3601,7 +3674,65 @@ export type ChatStreamEvent =
       toolName: string;
       arguments: any;
     }
-  | { type: "error"; error: string };
+  | {
+      type: "error";
+      error: string;
+      /**
+       * The provider-failure classification (`provider_auth_failed`,
+       * `provider_permission_denied`, `provider_billing`,
+       * `provider_rate_limited`, `provider_unavailable`,
+       * `provider_unreachable`, `provider_not_configured`,
+       * `provider_request_error`), when the failure was the LLM provider's
+       * answer. Absent for a transport failure or a plain server error.
+       */
+      errorKind?: string;
+      provider?: string;
+      /** The provider's own HTTP status. */
+      providerStatus?: number;
+      retryAfterSecs?: number;
+    };
+
+/**
+ * The text of a stream error frame: the first of `error` / `message` that is
+ * a non-empty string, else a fixed fallback — a structured `error` object is
+ * still an error, never a non-string `error` on the event. Shared by the SSE
+ * and WebSocket routes so the two cannot drift.
+ */
+function streamErrorText(payload: {
+  error?: unknown;
+  message?: unknown;
+}): string {
+  const text = (value: unknown): string | undefined =>
+    typeof value === "string" && value ? value : undefined;
+  return text(payload.error) ?? text(payload.message) ?? "Unknown error";
+}
+
+/**
+ * The classification fields of a stream error frame, only those present, so
+ * a plain error stays `{ type, error }`.
+ */
+function providerFailureFields(eventData: {
+  error_kind?: unknown;
+  provider?: unknown;
+  provider_status?: unknown;
+  retry_after_secs?: unknown;
+}): {
+  errorKind?: string;
+  provider?: string;
+  providerStatus?: number;
+  retryAfterSecs?: number;
+} {
+  const fields: ReturnType<typeof providerFailureFields> = {};
+  if (typeof eventData.error_kind === "string")
+    fields.errorKind = eventData.error_kind;
+  if (typeof eventData.provider === "string")
+    fields.provider = eventData.provider;
+  if (typeof eventData.provider_status === "number")
+    fields.providerStatus = eventData.provider_status;
+  if (typeof eventData.retry_after_secs === "number")
+    fields.retryAfterSecs = eventData.retry_after_secs;
+  return fields;
+}
 
 /** Definition for a client-side tool the LLM can call. */
 export interface ClientToolDefinition {
@@ -4285,9 +4416,12 @@ export class WebSocketClient {
         const chatId = msg.payload?.chat_id || msg.payload?.chatId;
         const stream = this.chatStreams.get(chatId);
         if (stream) {
+          // The text guard and the classification are the SSE route's,
+          // so the two routes emit the same shape.
           stream.emit("event", {
             type: "error",
-            error: msg.payload.error || msg.payload.message || "Unknown error",
+            error: streamErrorText(msg.payload),
+            ...providerFailureFields(msg.payload),
           } as ChatStreamEvent);
           this.chatStreams.delete(chatId);
           stream.close();

package/src/index.ts

@@ -88,6 +88,8 @@ export type {
   UpdateSessionRequest,
   MergeSessionsRequest,
   ChatModels,
+  ChatProviderState,
+  ChatProviderStatus,
   CompactChatRequest,
   CompactChatResponse,
   EmbedRequest,

package/src/websocket.test.ts

@@ -432,6 +432,96 @@ describe("WebSocketClient", () => {
       client.close();
     });
 
+    // The WebSocket route carries the provider-failure classification like
+    // the SSE route does, in the event's camelCase shape.
+    it("carries the provider failure classification on a chat stream error", async () => {
+      const client = new WebSocketClient(
+        `ws://localhost:${port}/api/ws`,
+        "test-token",
+      );
+
+      const streamPromise = client.chatSend("chat-4", "test");
+
+      await new Promise((r) => wss.once("connection", r));
+      const ws = getLastConnection();
+      await waitForMessage(ws);
+
+      const stream = await streamPromise;
+      const events: any[] = [];
+      stream.on("event", (e) => events.push(e));
+
+      ws.send(
+        JSON.stringify({
+          type: "ChatStreamError",
+          payload: {
+            chat_id: "chat-4",
+            error: "OpenAI API error 429 Too Many Requests",
+            error_kind: "provider_rate_limited",
+            provider: "openai",
+            provider_status: 429,
+            retry_after_secs: 7,
+          },
+        }),
+      );
+
+      await new Promise((r) => stream.on("close", r));
+      expect(events).toEqual([
+        {
+          type: "error",
+          error: "OpenAI API error 429 Too Many Requests",
+          errorKind: "provider_rate_limited",
+          provider: "openai",
+          providerStatus: 429,
+          retryAfterSecs: 7,
+        },
+      ]);
+
+      client.close();
+    });
+
+    // A structured `error` value is still an error, with string text — the
+    // WebSocket route guards the shape exactly as the SSE route does.
+    it("keeps the error text a string when the payload's error is an object", async () => {
+      const client = new WebSocketClient(
+        `ws://localhost:${port}/api/ws`,
+        "test-token",
+      );
+
+      const streamPromise = client.chatSend("chat-5", "test");
+
+      await new Promise((r) => wss.once("connection", r));
+      const ws = getLastConnection();
+      await waitForMessage(ws);
+
+      const stream = await streamPromise;
+      const events: any[] = [];
+      stream.on("event", (e) => events.push(e));
+
+      ws.send(
+        JSON.stringify({
+          type: "ChatStreamError",
+          payload: {
+            chat_id: "chat-5",
+            error: { code: "upstream_down", status: 503 },
+            error_kind: "provider_unavailable",
+            provider: "gemini",
+          },
+        }),
+      );
+
+      await new Promise((r) => stream.on("close", r));
+      expect(events).toEqual([
+        {
+          type: "error",
+          error: "Unknown error",
+          errorKind: "provider_unavailable",
+          provider: "gemini",
+        },
+      ]);
+
+      client.close();
+    });
+
     it("sends options with ChatSend", async () => {
       const client = new WebSocketClient(
         `ws://localhost:${port}/api/ws`,

package/tsconfig.json

@@ -1,7 +1,7 @@
 {
   "compilerOptions": {
     "target": "ES2020",
-    "module": "commonjs",
+    "module": "nodenext",
     "lib": ["ES2020"],
     "declaration": true,
     "outDir": "./dist",
@@ -10,7 +10,7 @@
     "esModuleInterop": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
-    "moduleResolution": "node",
+    "moduleResolution": "nodenext",
     "resolveJsonModule": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true