@jxsuite/ai 0.37.0 → 0.37.2

package/README.md

@@ -1,25 +1,17 @@
 # @jxsuite/ai
 
-The provider-agnostic substrate Jx Studio's assistant is built on: a streaming LLM client
-abstraction that normalizes provider SSE into six event shapes, a tool registry that speaks OpenAI
-function-calling, and a reactive chat store. It has no Jx-domain dependencies (just a type-only
-import of `ProblemDetails` from `@jxsuite/protocol`, plus `@vue/reactivity`), and its only platform
-APIs are `fetch`, `TextDecoder` and `AbortSignal`, so the same modules run in the browser and in
-Bun/Node.
+The provider-agnostic substrate Jx Studio's assistant is built on: a streaming LLM client abstraction that normalizes provider SSE into seven event shapes, a tool registry that speaks OpenAI function-calling, and a reactive chat store. It has no Jx-domain dependencies (just a type-only import of `ProblemDetails` from `@jxsuite/protocol`, plus `@vue/reactivity`), and its only platform APIs are `fetch`, `TextDecoder` and `AbortSignal`, so the same modules run in the browser and in Bun/Node.
 
-Governing spec: [`specs/ai.md`](../../specs/ai.md) §1-§2 (Status: Partial). User-facing
-documentation for the Studio feature lives at [`docs/studio/ai.md`](../../docs/studio/ai.md).
+Governing spec: [`specs/ai.md`](../../specs/ai.md) §1-§2 (Status: Partial). User-facing documentation for the Studio feature lives at [`docs/studio/ai.md`](../../docs/studio/ai.md).
 
 | Entrypoint                     | Exports                                                                                                                                     |
 | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@jxsuite/ai`                  | Barrel: the three factories, `createToolDefinition`, `createToolRegistry`, `createChatState`, `STREAM_EVENT_TYPES`, and the streaming types |
-| `@jxsuite/ai/streaming-client` | `StreamingClient`, `StreamEvent` and its six members, the three factories and their option types, `STREAM_EVENT_TYPES`                      |
+| `@jxsuite/ai/streaming-client` | `StreamingClient`, `StreamEvent` and its seven members, the three factories and their option types, `STREAM_EVENT_TYPES`                    |
 | `@jxsuite/ai/tools`            | `createToolDefinition`, `createToolRegistry`, `toolSuccess`, `toolError`, and their types                                                   |
 | `@jxsuite/ai/chat-state`       | `createChatState`, `ChatStore`, `Message`, `ToolCallRecord`, `ChatState`, `MessageRole`                                                     |
 
-`toolSuccess` / `toolError` are **not** re-exported by the barrel. Import them from
-`@jxsuite/ai/tools`. Importing the subpaths instead of the root is also what makes the package
-tree-shakeable.
+`toolSuccess` / `toolError` are **not** re-exported by the barrel. Import them from `@jxsuite/ai/tools`. Importing the subpaths instead of the root is also what makes the package tree-shakeable.
 
 ## The streaming client
 
@@ -30,13 +22,7 @@ streamChat(messages: object[], tools: object[], systemPrompt: string, signal: Ab
   : AsyncGenerator<StreamEvent>;
 ```
 
-Every implementation yields the same discriminated union, whose type strings are also published as
-`STREAM_EVENT_TYPES`: `delta {content}`, `tool_call_start {id, name}`, `tool_call_delta {id, args}`,
-`tool_call_end {id}`, `done {stopReason}`, `error {message, code?, problem?}`. This union is the
-contract a third-party Studio backend must satisfy for the `ai/chat` route (see
-[`packages/protocol/README.md`](../protocol/README.md)); `@jxsuite/server` emits the same format
-without depending on this package. `StreamEvent` and each member are exported, so an implementer can
-import the type instead of reconstructing it.
+Every implementation yields the same discriminated union, whose type strings are also published as `STREAM_EVENT_TYPES`: `delta {content}`, `tool_call_start {id, name}`, `tool_call_delta {id, args}`, `tool_call_end {id}`, `done {stopReason}`, `error {message, code?, problem?}`. This union is the contract a third-party Studio backend must satisfy for the `ai/chat` route (see [`packages/protocol/README.md`](../protocol/README.md)); `@jxsuite/server` emits the same format without depending on this package. `StreamEvent` and each member are exported, so an implementer can import the type instead of reconstructing it.
 
 ```ts
 import { createProxyStreamingClient } from "@jxsuite/ai";
@@ -52,48 +38,19 @@ for await (const event of client.streamChat(messages, tools, systemPrompt, signa
 }
 ```
 
-- **`createOpenAIStreamingClient({ baseUrl, apiKey, model = "gpt-4o", temperature })`** POSTs to
-  `${baseUrl}/chat/completions` with `Authorization: Bearer`, `stream: true`,
-  `stream_options: { include_usage: true }`, and `{ role: "system", content: systemPrompt }`
-  prepended to your messages. A non-empty `tools` array also sets `tool_choice: "auto"` and
-  `parallel_tool_calls: true`; an empty one sends no `tools` key. `temperature` is forwarded **only
-  when defined**, because reasoning models (GPT-5.x, o-series) reject a custom temperature. That is a
-  provider behaviour recorded in the source comment, not covered by a test here. It does
-  its own SSE framing and reassembles fragmented tool-call argument JSON keyed by the provider's
-  `delta.tool_calls[].index`.
-- **`createAnthropicStreamingClient({ baseUrl, apiKey })`** is a stub. It makes no network call and
-  yields exactly one `error` event with `code: "NOT_IMPLEMENTED"`. Only the OpenAI-compatible path
-  ships (`specs/ai.md` §2).
-- **`createProxyStreamingClient({ chatUrl, model = "gpt-4o", apiKey, baseUrl })`** POSTs
-  `{ messages, tools, systemPrompt, model }` to an endpoint that already speaks the normalized
-  format (the dev/desktop server's `/__studio/ai/chat`). It handles no credentials of its own;
-  `apiKey` and `baseUrl` are passed through as the `X-Api-Key` and `X-Api-Base-URL` headers only
-  when truthy, and the proxy owns the provider key. It is a pass-through, **not** a translator: it
-  re-yields whatever parses out of each `data:` line and returns at the first `done` or `error`, so
-  frames after `done` are dropped.
+- **`createOpenAIStreamingClient({ baseUrl, apiKey, model = "gpt-4o", temperature })`** POSTs to `${baseUrl}/chat/completions` with `Authorization: Bearer`, `stream: true`, `stream_options: { include_usage: true }`, and `{ role: "system", content: systemPrompt }` prepended to your messages. A non-empty `tools` array also sets `tool_choice: "auto"` and `parallel_tool_calls: true`; an empty one sends no `tools` key. `temperature` is forwarded **only when defined**, because reasoning models (GPT-5.x, o-series) reject a custom temperature. That is a provider behaviour recorded in the source comment, not covered by a test here. It does its own SSE framing and reassembles fragmented tool-call argument JSON keyed by the provider's `delta.tool_calls[].index`.
+- **`createAnthropicStreamingClient({ baseUrl, apiKey })`** is a stub. It makes no network call and yields exactly one `error` event with `code: "NOT_IMPLEMENTED"`. Only the OpenAI-compatible path ships (`specs/ai.md` §2).
+- **`createProxyStreamingClient({ chatUrl, model = "gpt-4o", apiKey, baseUrl })`** POSTs `{ messages, tools, systemPrompt, model }` to an endpoint that already speaks the normalized format (the dev/desktop server's `/__studio/ai/chat`). It handles no credentials of its own; `apiKey` and `baseUrl` are passed through as the `X-Api-Key` and `X-Api-Base-URL` headers only when truthy, and the proxy owns the provider key. It is a pass-through, **not** a translator: it re-yields whatever parses out of each `data:` line and returns at the first `done` or `error`, so frames after `done` are dropped.
 
 Three behaviours are easy to get wrong when consuming the stream:
 
-1. **Cancellation is a `done`, not an `error`.** An `AbortError` from `fetch` or mid-read becomes
-   `{ type: "done", stopReason: "cancelled" }`. Treating abort as failure paints a user's Stop
-   button as a crash. The OpenAI client's other stop reasons are `"stop"`, `"tool_calls"` and
-   `"length"`.
-2. **The OpenAI client drains pending tool calls on every termination path.** `[DONE]`, a
-   `finish_reason` of `stop`, `length` or `tool_calls` (any other value is ignored and the stream
-   continues), and a body that simply closes all emit `tool_call_end` for anything still open, then
-   exactly one `done`. The proxy client tracks nothing of its own, so a body that closes without a
-   `done` frame ends its generator with no `done` at all.
-3. **`error` frames may carry an RFC 9457 `problem` beside the human `message`,** because the
-   response has already begun with a 200 and the status can no longer change (a committed standards
-   row in `specs/ai.md` §5). The field is optional and no client in this package sets it.
-   `@jxsuite/server`'s proxy is what populates it, and `createProxyStreamingClient` passes it
-   through. Read `problem.type` for machine dispatch when it is present; keep showing `message`.
+1. **Cancellation is a `done`, not an `error`.** An `AbortError` from `fetch` or mid-read becomes `{ type: "done", stopReason: "cancelled" }`. Treating abort as failure paints a user's Stop button as a crash. The OpenAI client's other stop reasons are `"stop"`, `"tool_calls"` and `"length"`.
+2. **The OpenAI client drains pending tool calls on every termination path.** `[DONE]`, a `finish_reason` of `stop`, `length` or `tool_calls` (any other value is ignored and the stream continues), and a body that simply closes all emit `tool_call_end` for anything still open, then exactly one `done`. The proxy client tracks nothing of its own, so a body that closes without a `done` frame ends its generator with no `done` at all.
+3. **`error` frames may carry an RFC 9457 `problem` beside the human `message`,** because the response has already begun with a 200 and the status can no longer change (a committed standards row in `specs/ai.md` §5). The field is optional and no client in this package sets it. `@jxsuite/server`'s proxy is what populates it, and `createProxyStreamingClient` passes it through. Read `problem.type` for machine dispatch when it is present; keep showing `message`.
 
 ## The tool registry
 
-`createToolRegistry()` returns `{ register, list, listForLLM, validate, execute, getDefinition }`.
-`listForLLM()` emits `{ type: "function", function: { name, description, parameters } }`, ready to
-hand straight to `streamChat`'s `tools` argument.
+`createToolRegistry()` returns `{ register, list, listForLLM, validate, execute, getDefinition }`. `listForLLM()` emits `{ type: "function", function: { name, description, parameters } }`, ready to hand straight to `streamChat`'s `tools` argument.
 
 ```ts
 import { createToolDefinition, createToolRegistry, toolSuccess } from "@jxsuite/ai/tools";
@@ -113,65 +70,27 @@ registry.register(
 );
 ```
 
-- **`strict` and `llmStrict` are unrelated despite the names.** `strict` (default `true`) drives the
-  registry's own argument validation. `llmStrict` (default `false`) is the only one that reaches the
-  wire, adding OpenAI's `strict: true` to the emitted function schema. OpenAI strict mode demands
-  `additionalProperties: false` and every property in `required`, which Jx's own tools deliberately
-  violate, so GPT-5.x rejects such a request outright (again, committed rationale and no test).
-- **`validate()` is a lightweight structural check, not a JSON Schema validator.** It reads only
-  `type`, `properties` and `required`: nested schemas, `enum`, `pattern`, `minimum` and every other
-  keyword are ignored. Unknown properties are ignored too (the model may send extra); a required key
-  that is present but `null`/`undefined` counts as missing; numeric strings coerce, so `"42"`
-  validates against `number`. `strict: false`, or a schema without `properties`, skips it entirely.
-- **`execute()` never throws.** An unknown tool, a validation failure, and an exception inside the
-  tool all return `{ success: false, error }`, which is what lets an agent loop feed the failure
-  back to the model and self-correct. It calls `this.validate(...)`, so it is `this`-bound: do not
-  destructure it off the registry.
+- **`strict` and `llmStrict` are unrelated despite the names.** `strict` (default `true`) drives the registry's own argument validation. `llmStrict` (default `false`) is the only one that reaches the wire, adding OpenAI's `strict: true` to the emitted function schema. OpenAI strict mode demands `additionalProperties: false` and every property in `required`, which Jx's own tools deliberately violate, so GPT-5.x rejects such a request outright (again, committed rationale and no test).
+- **`validate()` is a lightweight structural check, not a JSON Schema validator.** It reads only `type`, `properties` and `required`: nested schemas, `enum`, `pattern`, `minimum` and every other keyword are ignored. Unknown properties are ignored too (the model may send extra); a required key that is present but `null`/`undefined` counts as missing; numeric strings coerce, so `"42"` validates against `number`. `strict: false`, or a schema without `properties`, skips it entirely.
+- **`execute()` never throws.** An unknown tool, a validation failure, and an exception inside the tool all return `{ success: false, error }`, which is what lets an agent loop feed the failure back to the model and self-correct. It calls `this.validate(...)`, so it is `this`-bound: do not destructure it off the registry.
 - Re-registering a name `console.warn`s and overwrites.
 
-To vary the tool set per turn, wrap rather than mutate. Studio's `createGatedToolRegistry` returns
-a `ToolRegistry` that filters `list()`/`listForLLM()` through per-tool predicates
-(`packages/studio/src/services/gated-registry.ts`).
+To vary the tool set per turn, wrap rather than mutate. Studio's `createGatedToolRegistry` returns a `ToolRegistry` that filters `list()`/`listForLLM()` through per-tool predicates (`packages/studio/src/services/gated-registry.ts`).
 
 ## The reactive chat store
 
-`createChatState(options?: { model?: string })` returns a `@vue/reactivity` `reactive()` store with
-its mutators `Object.assign`ed onto the same proxy, so the returned value is both the state and the
-API. The store holds `messages`, `status`, `streamingContent`, `pendingToolCalls`, `error`, `model`,
-`tokenCount` and `contextWarning`. The model falls back to `"gpt-4o"` via `||`, so an empty string
-takes the default too. `status` is `"idle" | "streaming" | "error"`; `toMessagesArray()` serializes
-back to OpenAI wire shape (assistant `tool_calls`, `tool` messages with `tool_call_id`, everything
-else `{ role, content }`).
-
-Two ordering rules inside `beginAssistantTurn` are load-bearing, and any reimplementation must keep
-them: `status` is set to `"streaming"` **before** the placeholder message is pushed (the push itself
-triggers effects, and a reader seeing `"idle"` renders the empty placeholder as a finished message),
-and the pushed object is immediately re-read back through the proxy (`store.messages.at(-1)`),
-because mutating the raw object would notify nothing. A regression test asserts that an `effect()`
-reading `messages.at(-1).content` re-runs on every `appendDelta`.
+`createChatState(options?: { model?: string })` returns a `@vue/reactivity` `reactive()` store with its mutators `Object.assign`ed onto the same proxy, so the returned value is both the state and the API. The store holds `messages`, `status`, `streamingContent`, `pendingToolCalls`, `error`, `model`, `tokenCount` and `contextWarning`. The model falls back to `"gpt-4o"` via `||`, so an empty string takes the default too. `status` is `"idle" | "streaming" | "error"`; `toMessagesArray()` serializes back to OpenAI wire shape (assistant `tool_calls`, `tool` messages with `tool_call_id`, everything else `{ role, content }`).
+
+Two ordering rules inside `beginAssistantTurn` are load-bearing, and any reimplementation must keep them: `status` is set to `"streaming"` **before** the placeholder message is pushed (the push itself triggers effects, and a reader seeing `"idle"` renders the empty placeholder as a finished message), and the pushed object is immediately re-read back through the proxy (`store.messages.at(-1)`), because mutating the raw object would notify nothing. A regression test asserts that an `effect()` reading `messages.at(-1).content` re-runs on every `appendDelta`.
 
 Further surprises:
 
-- **`sendMessage(text)` produces two messages**, not one: the user message plus an empty assistant
-  placeholder, and status flips to `"streaming"`. There is no way to append a bare user message with
-  it. `beginAssistantTurn()` exists separately so an agent loop can open the next round after
-  pushing tool results, with no new user message.
-- **`sendMessage` / `beginAssistantTurn` are no-ops while streaming**; `appendDelta` /
-  `appendToolCallStart` are no-ops while not streaming.
-- **`setError` and `cancelStream` delete the partial streaming message**, because it may hold
-  incomplete `tool_calls` that would poison history on the next send. That deletion is why
-  `specs/ai.md` §3.2 forbids reporting an exhausted tool-call budget as an error: the error path
-  destroys the only account of the edits that did land.
-- **`appendToolCallEnd(id)` is an intentional no-op.** Arguments are already fully accumulated; the
-  caller parses the JSON and executes the tool.
+- **`sendMessage(text)` produces two messages**, not one: the user message plus an empty assistant placeholder, and status flips to `"streaming"`. There is no way to append a bare user message with it. `beginAssistantTurn()` exists separately so an agent loop can open the next round after pushing tool results, with no new user message.
+- **`sendMessage` / `beginAssistantTurn` are no-ops while streaming**; `appendDelta` / `appendToolCallStart` are no-ops while not streaming.
+- **`setError` and `cancelStream` delete the partial streaming message**, because it may hold incomplete `tool_calls` that would poison history on the next send. That deletion is why `specs/ai.md` §3.2 forbids reporting an exhausted tool-call budget as an error: the error path destroys the only account of the edits that did land.
+- **`appendToolCallEnd(id)` is an intentional no-op.** Arguments are already fully accumulated; the caller parses the JSON and executes the tool.
 - Message ids come from a module-level counter (`msg_${Date.now()}_${n}`), not a UUID.
 
 ## Versioning
 
-Published to npm as `@jxsuite/ai`, following the monorepo's release train. Like every published
-`@jxsuite` library, it ships TypeScript source: every `exports` subpath resolves to `./src/*.ts`, so
-a consumer must be able to compile TypeScript out of `node_modules`. Within the monorepo,
-`@jxsuite/studio` depends on it via `workspace:^` and is its only consumer. `@vue/reactivity` is
-pinned to an **exact** version, matching `@jxsuite/studio`, `@jxsuite/runtime` and
-`@jxsuite/compiler`: reactive proxies from one copy do not track in effects from another, and the
-failure is silent.
+Published to npm as `@jxsuite/ai`, following the monorepo's release train. Like every published `@jxsuite` library, it ships TypeScript source: every `exports` subpath resolves to `./src/*.ts`, so a consumer must be able to compile TypeScript out of `node_modules`. Within the monorepo, `@jxsuite/studio` depends on it via `workspace:^` and is its only consumer. `@vue/reactivity` is pinned to an **exact** version, matching `@jxsuite/studio`, `@jxsuite/runtime` and `@jxsuite/compiler`: reactive proxies from one copy do not track in effects from another, and the failure is silent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/ai",
-  "version": "0.37.0",
+  "version": "0.37.2",
   "description": "AI infrastructure for Jx Suite — streaming LLM client abstraction, tool registry, and reactive chat state",
   "license": "MIT",
   "repository": {
@@ -28,10 +28,10 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/protocol": "^2.2.0",
-    "@vue/reactivity": "3.5.42"
+    "@jxsuite/protocol": "^2.3.1",
+    "@vue/reactivity": "3.5.43"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.12.0"
+    "@happy-dom/global-registrator": "^20.14.5"
   }
 }

package/src/chat-state.ts

@@ -21,6 +21,13 @@ export interface Message {
   id: string;
   role: MessageRole;
   content: string;
+  /**
+   * The turn's chain-of-thought, when the provider streamed one (`reasoning_content` /
+   * `reasoning`). Kept because a thinking model's own history is not optional: DeepSeek's thinking
+   * mode REQUIRES every prior turn's `reasoning_content` back on any request that carries `tools`,
+   * which is every request the agent loop makes. See {@link toMessagesArray}.
+   */
+  reasoningContent?: string;
   toolCalls?: ToolCallRecord[];
   toolCallId?: string;
   timestamp: number;
@@ -67,6 +74,7 @@ function uid() {
  *   sendMessage: (text: string) => void;
  *   beginAssistantTurn: () => void;
  *   appendDelta: (content: string) => void;
+ *   appendReasoning: (content: string) => void;
  *   appendToolCallStart: (id: string, name: string) => void;
  *   appendToolCallDelta: (id: string, args: string) => void;
  *   appendToolCallEnd: (id: string) => void;
@@ -183,6 +191,21 @@ export function createChatState(opts: { model?: string } = {}) {
     _streamingMessage.content = store.streamingContent;
   }
 
+  /**
+   * Append a reasoning delta to the streaming assistant message.
+   *
+   * Held on the message rather than in `streamingContent`: it is not part of the answer, but it IS
+   * part of the turn the provider will be shown again on the next round.
+   *
+   * @param {string} content
+   */
+  function appendReasoning(content: string) {
+    if (store.status !== "streaming" || !_streamingMessage) {
+      return;
+    }
+    _streamingMessage.reasoningContent = (_streamingMessage.reasoningContent ?? "") + content;
+  }
+
   /**
    * Start tracking a tool call within the stream.
    *
@@ -358,25 +381,56 @@ export function createChatState(opts: { model?: string } = {}) {
    * Convert the current chat state to an array suitable for sending to an LLM API. Includes the
    * system prompt as the first message and all conversation turns.
    *
+   * Two things it does NOT do verbatim, both because the array is a transcript for the UI and this
+   * is the wire:
+   *
+   * 1. **An assistant turn carrying neither text nor tool calls is dropped.** The one that always
+   *    exists is {@link beginAssistantTurn}'s placeholder — the message being generated by the very
+   *    request this builds, so it is a turn that has not happened yet. It reached providers as a
+   *    trailing `{"role":"assistant","content":""}`, which most read as an empty prefill and
+   *    ignore; DeepSeek's thinking mode instead answers 400 `The reasoning_content in the thinking
+   *    mode must be passed back to the API`, because a thinking-mode assistant turn owes it one.
+   *    `persistChat` in Studio already skipped the same message for the same reason — it just
+   *    skipped it on the way to storage, and nothing skipped it on the way to the provider.
+   * 2. **`reasoning_content` is replayed when the turn has one.** DeepSeek requires the reasoning of
+   *    all previous turns back on any request carrying `tools` — which is every request the agent
+   *    loop makes — and ignores it on requests that carry none, so echoing what the provider itself
+   *    streamed is safe for providers that never send it (they get no field at all).
+   *
    * @returns {object[]}
    */
   function toMessagesArray() {
     const out = [];
 
     for (const msg of store.messages) {
-      if (msg.role === "assistant" && msg.toolCalls && msg.toolCalls.length > 0) {
-        out.push({
+      if (msg.role === "assistant") {
+        const calls = msg.toolCalls ?? [];
+        if (!msg.content && calls.length === 0) {
+          continue;
+        }
+        const entry: {
+          role: string;
+          content: string | null;
+          reasoning_content?: string;
+          tool_calls?: object[];
+        } = {
           role: "assistant",
-          content: msg.content || null,
-          tool_calls: msg.toolCalls.map((tc) => ({
+          content: calls.length > 0 ? msg.content || null : msg.content,
+        };
+        if (msg.reasoningContent) {
+          entry.reasoning_content = msg.reasoningContent;
+        }
+        if (calls.length > 0) {
+          entry.tool_calls = calls.map((tc) => ({
             id: tc.id,
             type: "function",
             function: {
               name: tc.name,
               arguments: tc.arguments,
             },
-          })),
-        });
+          }));
+        }
+        out.push(entry);
       } else if (msg.role === "tool") {
         out.push({
           role: "tool",
@@ -398,6 +452,7 @@ export function createChatState(opts: { model?: string } = {}) {
     sendMessage,
     beginAssistantTurn,
     appendDelta,
+    appendReasoning,
     appendToolCallStart,
     appendToolCallDelta,
     appendToolCallEnd,

package/src/index.ts

@@ -28,6 +28,7 @@ export type {
   StreamDoneEvent,
   StreamErrorEvent,
   StreamEvent,
+  StreamReasoningEvent,
   StreamingClient,
   StreamToolCallDeltaEvent,
   StreamToolCallEndEvent,

package/src/streaming-client.ts

@@ -5,7 +5,7 @@
  * and concrete implementations for OpenAI and Anthropic. Designed upfront so switching
  * providers is a new implementation, not a refactor.
  *
- * The union and its six members are exported because they are the contract a third-party Studio
+ * The union and its seven members are exported because they are the contract a third-party Studio
  * backend implements for the `ai/chat` route, not an internal detail — see the docs page below.
  *
  * @license MIT
@@ -17,6 +17,7 @@ import type { ProblemDetails } from "@jxsuite/protocol";
 
 export type StreamEvent =
   | StreamDeltaEvent
+  | StreamReasoningEvent
   | StreamToolCallStartEvent
   | StreamToolCallDeltaEvent
   | StreamToolCallEndEvent
@@ -28,6 +29,21 @@ export interface StreamDeltaEvent {
   content: string;
 }
 
+/**
+ * A chain-of-thought fragment from a thinking model — OpenAI-compatible providers stream it as
+ * `reasoning_content` (DeepSeek, Volcengine) or `reasoning` (OpenRouter) beside `content`.
+ *
+ * It is a SEPARATE event rather than a `delta` because it is not part of the answer and must not be
+ * rendered as one — but it is part of the turn, and DeepSeek's thinking mode requires every prior
+ * turn's reasoning back on any request carrying `tools`. A client that drops these frames replays a
+ * history the provider rejects with 400 `The reasoning_content in the thinking mode must be passed
+ * back to the API`, so a backend implementing this route MUST forward them.
+ */
+export interface StreamReasoningEvent {
+  type: "reasoning";
+  content: string;
+}
+
 export interface StreamToolCallStartEvent {
   type: "tool_call_start";
   id: string;
@@ -105,7 +121,14 @@ interface OpenAIToolCallDelta {
 interface OpenAIStreamChunk {
   choices?: {
     index?: number;
-    delta?: { content?: string; tool_calls?: OpenAIToolCallDelta[] };
+    delta?: {
+      content?: string;
+      /** Thinking models' chain-of-thought: DeepSeek/Volcengine spell it this way… */
+      reasoning_content?: string;
+      /** …and OpenRouter this way. Both carry the same thing. */
+      reasoning?: string;
+      tool_calls?: OpenAIToolCallDelta[];
+    };
     finish_reason?: string | null;
   }[];
 }
@@ -121,6 +144,45 @@ interface ErrorResponseBody {
    * reading a sentence and deciding what it meant.
    */
   code?: string;
+  /**
+   * An array-shaped envelope, as Cloudflare's own REST API uses for a BYOK base URL pointed
+   * directly at it: `{ success: false, errors: [{ code, message }] }`, with no top-level `error`
+   * key at all. Reachable only when `baseUrl` bypasses the Studio proxy and talks to such a
+   * provider directly — the proxy itself normalizes this shape before it ever reaches a client.
+   */
+  errors?: { code?: number; message?: string }[];
+}
+
+/**
+ * Extract a human-readable message from an error body, falling back to the raw body (or `fallback`
+ * when the body is empty).
+ */
+function extractErrorMessage(rawBody: string, fallback: string): string {
+  if (!rawBody) {
+    return fallback;
+  }
+  try {
+    const { error, errors } = JSON.parse(rawBody) as ErrorResponseBody;
+    if (typeof error === "string") {
+      return error;
+    }
+    if (error) {
+      const { message } = error;
+      if (message) {
+        return message;
+      }
+    }
+    const [first] = errors ?? [];
+    if (first) {
+      const { message } = first;
+      if (message) {
+        return message;
+      }
+    }
+  } catch {
+    /* Not JSON — use the raw body. */
+  }
+  return rawBody;
 }
 
 // ─── Type definitions ────────────────────────────────────────────────────────
@@ -133,6 +195,7 @@ interface ErrorResponseBody {
  */
 export const STREAM_EVENT_TYPES = {
   DELTA: "delta",
+  REASONING: "reasoning",
   TOOL_CALL_START: "tool_call_start",
   TOOL_CALL_DELTA: "tool_call_delta",
   TOOL_CALL_END: "tool_call_end",
@@ -251,9 +314,10 @@ export function createOpenAIStreamingClient({
       } catch {
         /* Ignore */
       }
+      const message = extractErrorMessage(errorBody, response.statusText);
       yield {
         type: "error",
-        message: `API error ${response.status}: ${errorBody || response.statusText}`,
+        message: `API error ${response.status}: ${message}`,
         code: String(response.status),
       };
       return;
@@ -322,6 +386,12 @@ export function createOpenAIStreamingClient({
             yield { type: "delta", content: delta.content };
           }
 
+          // Chain-of-thought, under either of the two names providers give it.
+          const reasoning = delta.reasoning_content ?? delta.reasoning;
+          if (typeof reasoning === "string" && reasoning) {
+            yield { type: "reasoning", content: reasoning };
+          }
+
           // Tool calls
           if (delta.tool_calls) {
             for (const tc of delta.tool_calls) {
@@ -513,23 +583,17 @@ export function createProxyStreamingClient({
       } catch {
         /* Ignore */
       }
-      // Try to extract a clean message from JSON error bodies (e.g. the proxy's
-      // { error: "..." } shape or OpenAI's { error: { message: "..." } }).
-      let cleanMessage = errorBody || response.statusText;
+      // Extract a clean message from the JSON error body — see extractErrorMessage.
+      const cleanMessage = extractErrorMessage(errorBody, response.statusText);
       /* The body's machine code beats the status. `code` was `String(response.status)`
          unconditionally, so a proxy answering 401 `{ code: "cf_reconnect_required" }` reached the
          client as `"401"` — indistinguishable from a bad BYOK key, and the one reading that would
          have put a Reconnect button on screen was thrown away at the only place it arrived. */
       let machineCode = "";
       try {
-        const parsed = JSON.parse(errorBody) as ErrorResponseBody;
-        if (typeof parsed.error === "string") {
-          cleanMessage = parsed.error;
-        } else if (parsed.error?.message) {
-          cleanMessage = parsed.error.message;
-        }
-        if (typeof parsed.code === "string" && parsed.code) {
-          machineCode = parsed.code;
+        const { code } = JSON.parse(errorBody) as ErrorResponseBody;
+        if (typeof code === "string" && code) {
+          machineCode = code;
         }
       } catch {
         /* Not JSON — use the raw body. */