@jxsuite/ai 0.38.0 → 0.39.0

package/README.md

@@ -4,13 +4,13 @@ The provider-agnostic substrate Jx Studio's assistant is built on: a streaming L
 
 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`, the `ChatUsage` type, `STREAM_EVENT_TYPES`, and the streaming types                                                   |
-| `@jxsuite/ai/streaming-client` | `StreamingClient`, `StreamEvent` and its eight members, the three factories and their option types, `STREAM_EVENT_TYPES`, `usageEventFromOpenAI` and its `OpenAIUsage` input type                                   |
-| `@jxsuite/ai/tools`            | `createToolDefinition`, `createToolRegistry`, `toolSuccess`, `toolError`, the call context (`createToolContext`, `createLedger`, `createSessionFacts`, `linkCallSignal`), and their types                           |
-| `@jxsuite/ai/chat-state`       | `createChatState`, `ChatStore`, `ChatUsage`, `Message`, `ToolCallRecord`, `ChatState`, `MessageRole`                                                                                                                |
-| `@jxsuite/ai/gateway`          | `createChatHandler`, `modelsResponse`, `normalizeOpenAIStream`, `encodeSse`, `problemResponse`, `extractUpstreamErrorMessage`, and the `Upstream`, `GatewayRefusal`, `ChatAdmission` and `ChatGatewayOptions` types |
+| Entrypoint                     | Exports                                                                                                                                                                                                                                     |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@jxsuite/ai`                  | Barrel: the three factories, `createToolDefinition`, `createToolRegistry`, `createChatState`, the `ChatUsage` type, `STREAM_EVENT_TYPES`, the streaming types, and the prompt-cache hints (below)                                           |
+| `@jxsuite/ai/streaming-client` | `StreamingClient`, `StreamEvent` and its eight members, the three factories and their option types, `STREAM_EVENT_TYPES`, `usageEventFromOpenAI` and its `OpenAIUsage` input type, and the prompt-cache hints                               |
+| `@jxsuite/ai/tools`            | `createToolDefinition`, `createToolRegistry`, `toolSuccess`, `toolError`, the call context (`createToolContext`, `createLedger`, `createSessionFacts`, `linkCallSignal`), and their types                                                   |
+| `@jxsuite/ai/chat-state`       | `createChatState`, `ChatStore`, `ChatUsage`, `Message`, `ToolCallRecord`, `ChatState`, `MessageRole`                                                                                                                                        |
+| `@jxsuite/ai/gateway`          | `createChatHandler`, `modelsResponse`, `normalizeOpenAIStream`, `encodeSse`, `problemResponse`, `extractUpstreamErrorMessage`, the prompt-cache hints, and the `Upstream`, `GatewayRefusal`, `ChatAdmission` and `ChatGatewayOptions` types |
 
 `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.
 
@@ -39,9 +39,9 @@ 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`.
+- **`createOpenAIStreamingClient({ baseUrl, apiKey, model = "gpt-4o", temperature, sessionAffinity })`** 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`). `chatUrl` may also be a function returning the URL (or a promise of it): it is called once, inside the first stream, so a caller can arm its turn's signal before waiting on a lookup, and a stream stopped by the time it answers ends `cancelled` without sending anything; a lookup that rejects rejects the stream. 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.
+- **`createProxyStreamingClient({ chatUrl, model = "gpt-4o", apiKey, baseUrl, sessionId })`** POSTs `{ messages, tools, systemPrompt, model }` to an endpoint that already speaks the normalized format (the dev/desktop server's `/__studio/ai/chat`). `chatUrl` may also be a function returning the URL (or a promise of it): it is called once, inside the first stream, so a caller can arm its turn's signal before waiting on a lookup, and a stream stopped by the time it answers ends `cancelled` without sending anything; a lookup that rejects rejects the stream. 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. `sessionId`, likewise only when truthy, is sent as `X-Jx-Ai-Session` (`AI_SESSION_HEADER`) for the backend to hash into a prompt-cache key; the raw id is meant for the backend alone. 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:
 
@@ -77,6 +77,7 @@ const models = modelsResponse({ configured: true, models: [{ id: "gpt-4o" }] });
 - **The stream is always a `200`.** The upstream request is on the wire before the response is returned, and anything that goes wrong after that (a network failure, a provider's non-2xx, a reset mid-stream) is an `error` frame, while an abort is `done: cancelled`. `normalizeOpenAIStream` is the server's normalizer, moved here unchanged, so its frames are the ones `packages/server/tests/fixtures/ai-upstream/*.server.json` records.
 - **`fetch` is looked up per request** unless you pass one, so a host (or a test) can swap it.
 - **`modelsResponse(body)` is always a `200`,** because the models route is a capability probe. What the catalogue says is the host's business.
+- **A conversation can keep a warm prompt cache.** Studio's proxy client sends its conversation id as `X-Jx-Ai-Session` (`AI_SESSION_HEADER`). The host checks it with `isAiSessionId`, hashes it with `affinityKey(scope, id)` (the first 32 hex characters of SHA-256 over `jx-ai-affinity/v1:<scope>:<id>`) and returns the hash as the upstream's `sessionAffinity`. `upstreamCacheHints(baseUrl, affinity)` then decides what the provider sees: `prompt_cache_key` in the body for `api.openai.com`, the `x-session-affinity` header for Workers AI (`api.cloudflare.com` with `/ai/` in the path) and AI Gateway (`gateway.ai.cloudflare.com`), and nothing for any other host, so a strict server never meets an unknown field and an arbitrary endpoint never sees a stable id. `createOpenAIStreamingClient` takes the same key as `sessionAffinity` and applies the same rule.
 
 `./gateway` is Worker-safe. Studio never imports it (`packages/studio/tests/ai-import-rules.test.ts`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/ai",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "AI infrastructure for Jx Suite — streaming LLM client abstraction, tool registry, and reactive chat state",
   "license": "MIT",
   "repository": {
@@ -29,11 +29,11 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/protocol": "^2.4.0",
+    "@jxsuite/protocol": "^2.5.0",
     "@vue/reactivity": "3.5.43"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^5.20260926.1",
+    "@cloudflare/workers-types": "^5.20260928.1",
     "@happy-dom/global-registrator": "^20.14.5"
   }
 }

package/src/cache-hints.ts

@@ -0,0 +1,111 @@
+/**
+ * Cache-hints.ts — Prompt-cache routing hints for OpenAI-compatible upstreams.
+ *
+ * A provider's prompt cache only pays off when consecutive requests sharing a prefix reach the same
+ * machine. The assistant's requests are built for that (a stable system-prompt prefix, then a
+ * history that only grows), but the providers that route by prefix still need to be told which
+ * requests belong together, and each one is told differently:
+ *
+ * - OpenAI reads a `prompt_cache_key` body field.
+ * - Cloudflare Workers AI (directly, or through AI Gateway) reads an `x-session-affinity` header.
+ *
+ * Neither hint is sent anywhere else. An OpenAI-compatible server is free to reject an unknown body
+ * field, and a browser-side BYOK client adding an unknown header to a cross-origin request turns a
+ * simple request into a CORS preflight the endpoint may not answer. Above all, the value is a
+ * stable per-conversation identifier, and an arbitrary endpoint the user pointed a key at has no
+ * use for one.
+ *
+ * What travels is never the client's own session id. A client sends that only to its own backend
+ * (as {@link AI_SESSION_HEADER}); the backend hashes it with {@link affinityKey}, scoped to itself,
+ * and the hash is the only form a provider sees.
+ *
+ * Worker-safe: `crypto.subtle` and `TextEncoder` are globals in every runtime the gateway targets.
+ *
+ * @module @jxsuite/ai/streaming-client
+ * @license MIT
+ * @docs extending/embedding/backend-protocol
+ */
+
+/**
+ * The request header a client puts its conversation id in, for its OWN backend to hash. Never
+ * forwarded to a provider as sent.
+ */
+export const AI_SESSION_HEADER = "X-Jx-Ai-Session";
+
+/** 1–128 characters of `[A-Za-z0-9_.:-]`: wide enough for any id a client mints, nothing else. */
+const SESSION_ID = /^[\w.:-]{1,128}$/;
+
+/**
+ * Whether a value is a session id a backend may hash. A header that fails this is ignored rather
+ * than refused: the hint is an optimisation, and a request without one is still a valid request.
+ *
+ * @param {unknown} value - Typically the raw {@link AI_SESSION_HEADER} value, or null
+ * @returns {boolean}
+ */
+export function isAiSessionId(value: unknown): value is string {
+  return typeof value === "string" && SESSION_ID.test(value);
+}
+
+/**
+ * The affinity key a backend forwards for a session: the first 32 hex characters of
+ * SHA-256(`jx-ai-affinity/v1:<scope>:<sessionId>`).
+ *
+ * `scope` names the backend (`"local"` for the dev/desktop server), so two backends that happen to
+ * see the same id never share a key, and the version prefix lets the derivation change without
+ * colliding with the old one. 128 bits is plenty to keep unrelated conversations apart, and short
+ * enough for every provider's limit on the field.
+ *
+ * @param {string} scope - The backend's own namespace
+ * @param {string} sessionId - The client's session id, already checked with {@link isAiSessionId}
+ * @returns {Promise<string>} 32 lowercase hex characters
+ */
+export async function affinityKey(scope: string, sessionId: string): Promise<string> {
+  const input = new TextEncoder().encode(`jx-ai-affinity/v1:${scope}:${sessionId}`);
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", input));
+  let hex = "";
+  for (const byte of digest.subarray(0, 16)) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+
+/** The hints to merge into one upstream request: extra headers, and extra body members. */
+export interface UpstreamCacheHints {
+  headers: Record<string, string>;
+  body: { prompt_cache_key?: string };
+}
+
+/**
+ * The cache hints for a request to `baseUrl`, in the form that upstream understands, or none.
+ *
+ * Classified by host, because the hint's NAME is per provider: `api.openai.com` gets
+ * `prompt_cache_key` in the body; Workers AI (an `api.cloudflare.com` URL with `/ai/` in its path)
+ * and AI Gateway (`gateway.ai.cloudflare.com`) get the `x-session-affinity` header. Every other
+ * host, an unparseable base URL, and a request with no affinity get nothing.
+ *
+ * @param {string} baseUrl - The upstream's base URL, as the request is about to use it
+ * @param {string} [affinity] - The affinity key, from {@link affinityKey} (or a caller's own id)
+ * @returns {UpstreamCacheHints}
+ */
+export function upstreamCacheHints(baseUrl: string, affinity?: string): UpstreamCacheHints {
+  const hints: UpstreamCacheHints = { body: {}, headers: {} };
+  if (!affinity) {
+    return hints;
+  }
+  let url: URL;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    return hints;
+  }
+  const host = url.hostname.toLowerCase();
+  if (host === "api.openai.com") {
+    hints.body.prompt_cache_key = affinity;
+  } else if (
+    (host === "api.cloudflare.com" && url.pathname.includes("/ai/")) ||
+    host === "gateway.ai.cloudflare.com"
+  ) {
+    hints.headers["x-session-affinity"] = affinity;
+  }
+  return hints;
+}

package/src/gateway/chat.ts

@@ -4,6 +4,7 @@
  * @module @jxsuite/ai/gateway
  */
 
+import { upstreamCacheHints } from "../cache-hints.ts";
 import type { StreamEvent } from "../streaming-client.ts";
 import { fetchFailureFrame, normalizeOpenAIStream } from "./normalize.ts";
 import { problemResponse, refusal } from "./problem.ts";
@@ -30,6 +31,7 @@ interface UpstreamBody {
   tools?: unknown;
   tool_choice?: string;
   parallel_tool_calls?: boolean;
+  prompt_cache_key?: string;
 }
 
 /**
@@ -115,8 +117,10 @@ async function* exchange(
  *
  * The version 1 body is forwarded as the OpenAI-compatible request it describes: the system prompt
  * as a leading `system` message, `stream_options.include_usage` so the provider's own token count
- * arrives, and `tool_choice: "auto"` with parallel calls whenever tools are offered. The upstream
- * request carries `context.signal`, so aborting it ends the stream with `done: cancelled`.
+ * arrives, and `tool_choice: "auto"` with parallel calls whenever tools are offered. When the host
+ * resolved a `sessionAffinity`, it rides along as the prompt-cache hint the upstream's host
+ * understands, and not at all to any other host (`upstreamCacheHints`). The upstream request
+ * carries `context.signal`, so aborting it ends the stream with `done: cancelled`.
  *
  * @param {ChatGatewayOptions<C>} options - The host's policy
  * @returns {(request: Request, context: C) => Promise<Response>}
@@ -200,6 +204,8 @@ export function createChatHandler<C extends { readonly signal: AbortSignal }>(
       upstreamBody.tool_choice = "auto";
       upstreamBody.parallel_tool_calls = true;
     }
+    const hints = upstreamCacheHints(upstream.baseUrl, upstream.sessionAffinity);
+    Object.assign(upstreamBody, hints.body);
 
     // Looked up per request, not captured at construction: a host or a test may swap it.
     const upstreamFetch = options.fetch ?? fetch;
@@ -208,6 +214,7 @@ export function createChatHandler<C extends { readonly signal: AbortSignal }>(
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${upstream.apiKey}`,
+        ...hints.headers,
       },
       body: JSON.stringify(upstreamBody),
       signal: context.signal,

package/src/gateway/index.ts

@@ -17,10 +17,17 @@
  * @docs extending/embedding/backend-protocol
  */
 
+export {
+  AI_SESSION_HEADER,
+  affinityKey,
+  isAiSessionId,
+  upstreamCacheHints,
+} from "../cache-hints.ts";
 export { createChatHandler } from "./chat.ts";
 export { modelsResponse } from "./models.ts";
 export { normalizeOpenAIStream } from "./normalize.ts";
 export { problemResponse } from "./problem.ts";
 export { encodeSse } from "./sse.ts";
 export { extractUpstreamErrorMessage } from "./upstream-error.ts";
+export type { UpstreamCacheHints } from "../cache-hints.ts";
 export type { ChatAdmission, ChatGatewayOptions, GatewayRefusal, Upstream } from "./types.ts";

package/src/gateway/types.ts

@@ -27,6 +27,13 @@ export interface Upstream {
   readonly defaultModel: string;
   /** True when the platform brokers the credential, rather than the user supplying one. */
   readonly managed: boolean;
+  /**
+   * The prompt-cache affinity key for the request's conversation, when the host derived one: the
+   * gateway forwards it in whatever form this upstream understands, and to no other upstream
+   * (`upstreamCacheHints`). A host derives it with `affinityKey(scope, id)` from the client's
+   * `X-Jx-Ai-Session` header, so the raw id never leaves the host.
+   */
+  readonly sessionAffinity?: string;
 }
 
 /**

package/src/index.ts

@@ -1,8 +1,8 @@
 /**
  * Index.js — AI infrastructure for Jx Suite (`@jxsuite/ai`)
  *
- * Re-exports the core modules: streaming client abstraction, tool registry, and
- * reactive chat state management. Provider-agnostic; no Studio or Jx dependencies.
+ * Re-exports the core modules: streaming client abstraction, tool registry, and reactive chat state
+ * management. Provider-agnostic; no Studio or Jx dependencies.
  *
  * @license MIT
  */
@@ -22,6 +22,15 @@ export {
   createProxyStreamingClient,
 } from "./streaming-client.js";
 
+export {
+  AI_SESSION_HEADER,
+  affinityKey,
+  isAiSessionId,
+  upstreamCacheHints,
+} from "./cache-hints.js";
+
+export type { UpstreamCacheHints } from "./cache-hints.js";
+
 export type {
   AnthropicStreamingClientOptions,
   OpenAIStreamingClientOptions,

package/src/streaming-client.ts

@@ -1,19 +1,30 @@
 /**
  * Streaming-client.js — Provider-agnostic streaming LLM client abstraction
  *
- * Defines the StreamingClient interface, the StreamEvent union every implementation yields,
- * and concrete implementations for OpenAI and Anthropic. Designed upfront so switching
- * providers is a new implementation, not a refactor.
+ * Defines the StreamingClient interface, the StreamEvent union every implementation yields, and
+ * concrete implementations for OpenAI and Anthropic. Designed upfront so switching providers is a
+ * new implementation, not a refactor.
  *
  * The union and its eight 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
  * @module @jxsuite/ai/streaming-client
+ * @license MIT
  * @docs extending/embedding/backend-protocol
  */
 
 import type { ProblemDetails } from "@jxsuite/protocol";
+import { AI_SESSION_HEADER, upstreamCacheHints } from "./cache-hints.ts";
+
+/* Re-exported so `./streaming-client`, the subpath a backend already imports, carries the cache
+   hints too: a Worker backend hashing the session header needs nothing else from this package. */
+export {
+  AI_SESSION_HEADER,
+  affinityKey,
+  isAiSessionId,
+  upstreamCacheHints,
+} from "./cache-hints.ts";
+export type { UpstreamCacheHints } from "./cache-hints.ts";
 
 export type StreamEvent =
   | StreamDeltaEvent
@@ -129,6 +140,8 @@ interface OpenAIChatRequestBody {
   tools?: object[];
   tool_choice?: string;
   parallel_tool_calls?: boolean;
+  /** OpenAI's prompt-cache routing key, sent only to OpenAI itself (see `cache-hints.ts`). */
+  prompt_cache_key?: string;
 }
 
 /** A tool-call fragment inside an OpenAI streaming `delta`. */
@@ -305,6 +318,9 @@ export const STREAM_EVENT_TYPES = {
  * @param {number} [opts.temperature] - Sampling temperature, forwarded only when defined. Omit for
  *   reasoning models (GPT-5.x, o-series) that reject a custom temperature; set 0 for
  *   near-deterministic eval runs.
+ * @param {string} [opts.sessionAffinity] - A stable key for the conversation, forwarded as the
+ *   prompt-cache hint the provider understands (`prompt_cache_key` to OpenAI, `x-session-affinity`
+ *   to Workers AI) and to no other host. See `upstreamCacheHints`.
  * @returns {StreamingClient}
  */
 export interface OpenAIStreamingClientOptions {
@@ -312,6 +328,7 @@ export interface OpenAIStreamingClientOptions {
   apiKey: string;
   model?: string;
   temperature?: number | undefined;
+  sessionAffinity?: string | undefined;
 }
 
 export function createOpenAIStreamingClient({
@@ -319,7 +336,11 @@ export function createOpenAIStreamingClient({
   apiKey,
   model = "gpt-4o",
   temperature,
+  sessionAffinity,
 }: OpenAIStreamingClientOptions): StreamingClient {
+  // Fixed for the client's life, so it is classified once rather than per request.
+  const hints = upstreamCacheHints(baseUrl, sessionAffinity);
+
   /**
    * @param {object[]} messages
    * @param {object[]} tools
@@ -353,6 +374,7 @@ export function createOpenAIStreamingClient({
       body.tool_choice = "auto";
       body.parallel_tool_calls = true;
     }
+    Object.assign(body, hints.body);
 
     let response;
     try {
@@ -361,6 +383,7 @@ export function createOpenAIStreamingClient({
         headers: {
           "Content-Type": "application/json",
           Authorization: `Bearer ${apiKey}`,
+          ...hints.headers,
         },
         body: JSON.stringify(body),
         signal,
@@ -595,6 +618,9 @@ export function createAnthropicStreamingClient(
  * @param {string} [opts.model] - Default model if not specified per-request
  * @param {string} [opts.apiKey] - Optional client-supplied key, sent as the `X-Api-Key` header
  * @param {string} [opts.baseUrl] - Optional OpenAI-compatible base URL, sent as `X-Api-Base-URL`
+ * @param {string} [opts.sessionId] - The conversation's id, sent as the `X-Jx-Ai-Session` header so
+ *   the backend can derive a prompt-cache affinity key from it. The raw id goes to the backend
+ *   only; a provider sees a hash of it, scoped to that backend (`affinityKey`).
  * @returns {StreamingClient}
  */
 export interface ProxyStreamingClientOptions {
@@ -602,6 +628,7 @@ export interface ProxyStreamingClientOptions {
   model?: string;
   apiKey?: string | undefined;
   baseUrl?: string | undefined;
+  sessionId?: string | undefined;
 }
 
 export function createProxyStreamingClient({
@@ -609,6 +636,7 @@ export function createProxyStreamingClient({
   model = "gpt-4o",
   apiKey,
   baseUrl,
+  sessionId,
 }: ProxyStreamingClientOptions): StreamingClient {
   /** The URL, once the first stream has asked for it. */
   let resolvedUrl: Promise<string> | null = null;
@@ -636,6 +664,12 @@ export function createProxyStreamingClient({
     if (baseUrl) {
       headers["X-Api-Base-URL"] = baseUrl;
     }
+    /* The conversation, so consecutive rounds can be routed to a warm prompt cache. Same-origin on
+       every platform, so the extra header costs no preflight; a backend that ignores it loses only
+       the cache hit. */
+    if (sessionId) {
+      headers[AI_SESSION_HEADER] = sessionId;
+    }
 
     resolvedUrl ??= Promise.resolve(typeof chatUrl === "function" ? chatUrl() : chatUrl);
     let url: string;