@combycode/llm-sdk 3.1.0 → 3.2.1

package/CHANGELOG.md

@@ -4,7 +4,101 @@ All notable changes to `@combycode/llm-sdk` are documented here. The format foll
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [3.2.1] — 2026-08-31
+
+### Fixed
+
+- **Three TypeScript errors in an MCP test file** that made v3.2.0 unpublishable: `searchParams.get()`
+  returns `string | null` while `.at(-1)` returns `string | undefined`, and `toBe` has no overload
+  spanning both. The assertions are unchanged; only their types are aligned.
+
+- **Two lint warnings** left standing in `network/engine.ts` (an unused type import) and an MCP test
+  helper (`let x!` forward declarations that nothing forward-references).
+
+### Internal
+
+- **The release gate now runs lint, typecheck and the tests** (`G1 build-green` in CombyCode's shared
+  quality-gate). v3.2.0 was tagged with a green gate and a red typecheck, because the gate checked
+  documentation and consumers while lint and typecheck lived in a playbook sentence — the half a
+  human has to remember. The gate's own README names that failure mode: "a checklist you have to
+  remember to read is guarded by the same attention that failed in the first place." The check ships
+  with the good/bad/blind fixtures the selftest requires, and was verified against the exact error
+  that escaped.
+
+## [3.2.0] — 2026-08-31
+
+### Added
+
+- **`response.citations` — the sources an answer cited, unified across providers.** Reaching them
+  meant regexing `response.raw`; the SDK's own web-search example did exactly that, which is every
+  consumer reimplementing provider knowledge that belongs here. Four wire shapes are read: Anthropic's
+  text-block `citations[]` (the only provider that also reports the cited passage), Google's
+  `groundingMetadata.groundingChunks[]`, OpenAI Responses/Chat `url_citation` annotations, and xAI's
+  bare top-level `citations[]`.
+
+  Distinct from `builtinToolCalls`, which records what the model *invoked*: a turn can run three
+  searches and cite one page. Through an agent run the sources **accumulate across steps**, deduped
+  by URL — a run that searches in step 1 and answers in step 3 keeps the sources its answer rests on.
+  Optional per R3 (`response.citations ?? []`); absent on `stream()`, which holds no raw payload, and
+  on Google's Interactions surface, whose grounding shape has not been measured.
+
+  **Streaming reports them too**, as a `citation` StreamEvent per source, collected onto the streamed
+  final response so `stream()` and `complete()` agree. Four more measured shapes, since a stream never
+  assembles the body the buffered reader parses: Anthropic `citations_delta`, Responses
+  `response.output_text.annotation.added` (OpenAI and xAI), chat-completions `delta.annotations`, and
+  Google's *late* populated `groundingMetadata` chunk — the first one carrying that key is empty, so
+  latching on first sight would report a search and no sources.
+
+  Verified live on Anthropic, OpenAI, Google, xAI and OpenRouter, buffered and streamed: 5/5 providers
+  return real cited URLs for the web-search scenario, which previously reported `no-citation` on all
+  five. Note Google reports each source as a `grounding-api-redirect` URL, not the page itself.
+
+### Fixed
+
+- **xAI file `delete`, `getInfo` and `list` never worked.** `XAIFileAdapter` is exported, and three
+  of its four methods rejected with `unknown spec: xai/files.<op>` before any HTTP — only
+  `xai/files.upload` had ever been written, so roughly twenty lines of response mapping below them
+  had never run. The three specs follow `xai.upload`'s own note that the surface differs from
+  OpenAI's only in the upload `purpose`, so they carry the same paths and the same Bearer base.
+
+- **`listModelsLive` was blocked by CORS in the browser, for Anthropic only.** Anthropic refuses a
+  browser request without an explicit opt-in header. The chat path sends it and the Anthropic files
+  specs carry it, but `models.list` lost it when that request moved to a spec: the header had lived
+  in the helper's own table, which nothing called any more. Measured from a browser with a raw
+  fetch — `/v1/models` returns 200 with the header and fails without it. The sandbox listed models
+  through `Promise.allSettled` and kept only the fulfilled results, so the rejection was swallowed
+  and Anthropic simply showed no models rather than an error.
+
+### Removed
+
+- **Five private functions left behind by the spec migration.** Each was live until its area moved to
+  the spec-driven builder, which renamed it with a leading underscore instead of deleting it:
+  `_buildForm`, `_batchName`, `_toOpenAIAudioFormat`, `_toResponseModalities` and
+  `LiveSpec.headers`. Each was checked field by field against the spec that replaced it before
+  removal — and the last of them was **not** equivalent, which is how the CORS bug above was found.
+
+### Internal
+
+- **Line coverage 91.62% → 99.53%**, function coverage 87.53% → 97.41%, across 2290 → 4051 tests.
+  Eleven modules had no function coverage at all — `batcher.ts` ran 3.5% of its lines,
+  `plugins/internal-tools/runner/runner.ts` 3.7%, `transport-ws.ts` 9.6%. Every new test is mutation-verified: the
+  source line it claims to cover was broken and the test watched to fail.
+
+  The exercise found ten defects no existing test caught, each pinned as a `DEFECT:` test rather
+  than fixed in the same pass: `ResponseStore.list(null)` returning every user's response ids,
+  `chunker.ts` silently dropping space-free text (3000 characters of CJK or base64 yield one
+  400-character chunk), `attachment.ts fromBlob` leaving the MIME type empty because a type-less
+  `Blob` reports `''` rather than `null`, and `oauth.ts tryRefresh` discarding the refresh token it
+  means to preserve.
+
+  Two pre-existing tests turned out to execute no code at all — one asserts against `readFileSync`
+  of `realtime.ts` with regexes over the source text, which is why that file sat at 0% functions
+  while appearing tested.
+
+- **A coverage floor that can actually fail.** `bunfig.toml`'s `coverageThreshold` is accepted and
+  ignored by bun 1.3.14 — set to an impossible 1.0 the run still exits 0 — so the floor is its own
+  step (`bun run coverage:gate`), carrying a `--self-test` that proves it discriminates.
+
 
 ## [3.1.0] — 2026-08-25
 

package/dist/agent/loop-step-state.d.ts

@@ -1,7 +1,7 @@
 /** Mutable accumulator for a single agent loop step.
  *  Passed through stream-event helpers so they don't fight closure state. */
 import type { ToolCallPart } from '../llm/types/messages';
-import type { Usage } from '../llm/types/response';
+import type { Citation, Usage } from '../llm/types/response';
 /** Accumulation bucket for one in-progress tool call (before tool_call_end). */
 export interface ToolCallAccumEntry {
     id: string;
@@ -19,4 +19,8 @@ export interface StepState {
     toolCallAccum: Map<string, ToolCallAccumEntry>;
     stepUsage: Usage;
     stepFinishReason: string;
+    /** Sources cited during this step, keyed by url. A Map rather than an array
+     *  because Google repeats its grounding chunks across late chunks, and one page
+     *  cited twice is one source. */
+    stepCitations: Map<string, Citation>;
 }

package/dist/index.browser.js

@@ -30969,7 +30969,7 @@ var xai_create_default = {
 var xai_addRequests_default = {
   id: "xai/batch.addRequests",
   extends: "xai/batch.base",
-  _note: "Step 2 of submit. Step 1 creates the batch and is NOT modelled: its body embeds Date.now(), so the request is not reproducible. See report 039 A3.",
+  _note: "Step 2 of submit: the batch opened in step 1 is filled here. batch_request is a TAGGED UNION whose variant name is the KEY -- {responses: <body>}, never {endpoint: 'responses', body: <body>}. Measured live 2026-08-28: the endpoint-field form is rejected 422 with 'unknown variant endpoint, expected one of chat_get_completion, responses, image_generation, image_edit, video_generation, video_extension'. That form had never been sent to xAI, here or in the TypeScript adapter this spec came from.",
   envelope: {
     method: "POST",
     url: { $join: [{ $config: "baseURL" }, "/v1/batches/", { $: "batchId" }, "/requests"] },
@@ -30985,7 +30985,7 @@ var xai_addRequests_default = {
           {
             value: {
               batch_request_id: { $: "@customId" },
-              batch_request: { endpoint: "responses", body: { $: "@body" } }
+              batch_request: { responses: { $: "@body" } }
             }
           }
         ]
@@ -31337,6 +31337,42 @@ var xai_upload_default = {
   multipart: [{ name: "file", file: true }, { name: "purpose", value: "assistants" }]
 };
 
+// src/wire/specs/files/xai.delete.json
+var xai_delete_default = {
+  id: "xai/files.delete",
+  extends: "openai/files.base",
+  _note: "Same shape as OpenAI's, per xai.upload's note that the surface differs only in the upload purpose. baseURL is supplied by the adapter, so the path is all that is declared here.",
+  envelope: {
+    method: "DELETE",
+    bodyKind: "none",
+    url: { $join: [{ $config: "baseURL" }, "/v1/files/", { $: "remoteId" }] }
+  }
+};
+
+// src/wire/specs/files/xai.getInfo.json
+var xai_getInfo_default = {
+  id: "xai/files.getInfo",
+  extends: "openai/files.base",
+  _note: "Same shape as OpenAI's, per xai.upload's note that the surface differs only in the upload purpose. baseURL is supplied by the adapter, so the path is all that is declared here.",
+  envelope: {
+    method: "GET",
+    bodyKind: "none",
+    url: { $join: [{ $config: "baseURL" }, "/v1/files/", { $: "remoteId" }] }
+  }
+};
+
+// src/wire/specs/files/xai.list.json
+var xai_list_default = {
+  id: "xai/files.list",
+  extends: "openai/files.base",
+  _note: "Same shape as OpenAI's, per xai.upload's note that the surface differs only in the upload purpose. baseURL is supplied by the adapter, so the path is all that is declared here.",
+  envelope: {
+    method: "GET",
+    bodyKind: "none",
+    url: { $join: [{ $config: "baseURL" }, "/v1/files"] }
+  }
+};
+
 // src/wire/specs/files/google.finishUpload.json
 var google_finishUpload_default = {
   id: "google/files.finishUpload",
@@ -31577,6 +31613,9 @@ var DELTAS = new Map(
     google_getInfo_default,
     google_list_default,
     xai_upload_default,
+    xai_delete_default,
+    xai_getInfo_default,
+    xai_list_default,
     google_finishUpload_default,
     videos_status_default,
     videos_cancel_default,
@@ -32387,6 +32426,14 @@ var anthropic_default3 = {
         value: {
           $config: "apiVersion"
         }
+      },
+      {
+        name: "anthropic-dangerous-direct-browser-access",
+        value: "true",
+        _note: "Only in a browser, where the request is otherwise blocked by CORS. The chat path sends it (messages.ts) and so do the files specs; models.list lost it when this request moved to a spec, because the header lived in the helper's own table.",
+        when: {
+          truthy: "browser"
+        }
       }
     ]
   }
@@ -36663,6 +36710,7 @@ var LLMClient = class {
     let moderationReport;
     const files = [];
     const builtinToolCalls = [];
+    const citationsByUrl = /* @__PURE__ */ new Map();
     const fetchStream = this.fetchStreamFn;
     const queueName = this.queueName;
     const priority = this.priority;
@@ -36716,6 +36764,9 @@ var LLMClient = class {
         case "file":
           files.push(event.file);
           break;
+        case "citation":
+          citationsByUrl.set(event.citation.url, event.citation);
+          break;
         case "builtin_tool_end":
           builtinToolCalls.push({
             tool: event.tool,
@@ -36750,6 +36801,7 @@ var LLMClient = class {
       media: [],
       ...files.length ? { files } : {},
       ...builtinToolCalls.length ? { builtinToolCalls } : {},
+      ...citationsByUrl.size ? { citations: [...citationsByUrl.values()] } : {},
       ...moderationReport ? { moderation: moderationReport } : {},
       latencyMs: performance.now() - start,
       raw: null
@@ -38560,6 +38612,87 @@ function pinFor(model, pins) {
 var ANTHROPIC_MESSAGE_PINS = anthropic_messages_default;
 var GOOGLE_GENERATE_PINS = google_generate_default;
 
+// src/llm/providers/_shared/citations.ts
+function fromAnthropic(raw) {
+  const out = [];
+  for (const block of raw.content ?? []) {
+    for (const cite of block.citations ?? []) {
+      const url = cite.url;
+      if (url) {
+        out.push({
+          url,
+          ...cite.title ? { title: cite.title } : {},
+          // Anthropic is the only provider that reports the cited passage.
+          ...cite.cited_text ? { text: cite.cited_text } : {}
+        });
+      }
+    }
+  }
+  return out;
+}
+function fromGoogle(raw) {
+  const out = [];
+  for (const candidate of raw.candidates ?? []) {
+    const grounding = candidate.groundingMetadata ?? {};
+    for (const chunk of grounding.groundingChunks ?? []) {
+      const web = chunk.web ?? {};
+      const uri = web.uri;
+      if (uri) out.push({ url: uri, ...web.title ? { title: web.title } : {} });
+    }
+  }
+  return out;
+}
+function fromResponses(raw) {
+  const out = [];
+  for (const item of raw.output ?? []) {
+    for (const part of item.content ?? []) {
+      for (const note of part.annotations ?? []) {
+        if (note.type === "url_citation" && note.url) {
+          out.push({
+            url: note.url,
+            ...note.title ? { title: note.title } : {}
+          });
+        }
+      }
+    }
+  }
+  return out;
+}
+function fromCompletions(raw) {
+  const out = [];
+  const message = (raw.choices ?? [])[0]?.message ?? {};
+  for (const note of message.annotations ?? []) {
+    const detail = note.url_citation ?? note;
+    if (note.type === "url_citation" && detail.url) {
+      out.push({
+        url: detail.url,
+        ...detail.title ? { title: detail.title } : {}
+      });
+    }
+  }
+  for (const url of raw.citations ?? []) {
+    if (typeof url === "string") out.push({ url });
+  }
+  return out;
+}
+var READERS = {
+  messages: fromAnthropic,
+  generate: fromGoogle,
+  responses: fromResponses,
+  completions: fromCompletions
+  // `interactions` is DELIBERATELY absent. Google's Interactions API returns a
+  // `steps[]` machine, not `candidates[]`, so `fromGoogle` would read a key that
+  // is never there -- and no recorded Interactions response carries grounding, so
+  // there is nothing to write a reader against. Guessing the shape would produce
+  // a reader that is confidently wrong and passes a test built from the same
+  // guess. The adapter is wired anyway: when the shape is measured, only this
+  // table changes.
+};
+function extractCitations(api, raw) {
+  if (raw == null || typeof raw !== "object") return [];
+  return READERS[api]?.(raw) ?? [];
+}
+
 // src/llm/providers/_shared/builtin-tools.ts
 var NATIVE_TO_UNIFIED = {
   // OpenAI / xAI Responses output-item types
@@ -38778,6 +38911,7 @@ var AnthropicAdapter = class {
       model_context_window_exceeded: "length",
       refusal: "content_filter"
     });
+    const citations = extractCitations("messages", raw);
     return {
       id: r.id,
       model: r.model,
@@ -38787,6 +38921,7 @@ var AnthropicAdapter = class {
       text: content.filter((p) => p.type === "text").map((p) => p.text).join(""),
       toolCalls,
       media: [],
+      ...citations.length ? { citations } : {},
       ...files.length ? { files } : {},
       ...builtinToolCalls.length ? { builtinToolCalls } : {},
       thinking,
@@ -38814,6 +38949,20 @@ var AnthropicAdapter = class {
       if (delta.type === "text_delta") return [{ type: "text", text: delta.text }];
       if (delta.type === "thinking_delta")
         return [{ type: "thinking", text: delta.thinking }];
+      if (delta.type === "citations_delta") {
+        const cite = delta.citation ?? {};
+        const url = cite.url;
+        return url ? [
+          {
+            type: "citation",
+            citation: {
+              url,
+              ...cite.title ? { title: cite.title } : {},
+              ...cite.cited_text ? { text: cite.cited_text } : {}
+            }
+          }
+        ] : [];
+      }
       if (delta.type === "input_json_delta") {
         if (state.current) {
           state.current.json += delta.partial_json ?? "";
@@ -39364,6 +39513,7 @@ var GoogleAdapter = class {
         builtinToolCalls.push({ tool: "web_fetch", ...typeof url === "string" ? { url } : {} });
       }
     }
+    const citations = extractCitations("generate", raw);
     return {
       // generateContent DOES return an id — `responseId`, at the top level. The
       // fallback stays for older payloads, but minting one unconditionally made
@@ -39379,6 +39529,7 @@ var GoogleAdapter = class {
       toolCalls,
       thinking,
       media,
+      ...citations.length ? { citations } : {},
       ...files.length ? { files } : {},
       ...builtinToolCalls.length ? { builtinToolCalls } : {},
       latencyMs,
@@ -39463,6 +39614,18 @@ var GoogleAdapter = class {
         events.push({ type: "tool_call_end", id: "" });
       }
     }
+    for (const chunk of candidate.groundingMetadata?.groundingChunks ?? []) {
+      const web = chunk.web ?? {};
+      if (web.uri) {
+        events.push({
+          type: "citation",
+          citation: {
+            url: web.uri,
+            ...web.title ? { title: web.title } : {}
+          }
+        });
+      }
+    }
     if (candidate.groundingMetadata && !state.webSearchEmitted) {
       state.webSearchEmitted = true;
       const q = candidate.groundingMetadata.webSearchQueries?.[0];
@@ -39685,6 +39848,7 @@ var GoogleInteractionsAdapter = class {
       queued: "pending",
       in_progress: "pending"
     });
+    const citations = extractCitations("interactions", raw);
     return {
       id: r.id ?? crypto.randomUUID(),
       model: "",
@@ -39694,6 +39858,7 @@ var GoogleInteractionsAdapter = class {
       text,
       toolCalls,
       media,
+      ...citations.length ? { citations } : {},
       thinking,
       latencyMs,
       raw
@@ -41035,13 +41200,14 @@ var OpenAIAdapter = class {
       content.push(parsed);
       toolCalls.push(parsed);
     }
-    const finishReason = extractFinishReason(
-      toolCalls.length > 0,
-      choice.finish_reason,
-      { tool_calls: "tool_use", length: "length", content_filter: "content_filter" }
-    );
+    const finishReason = extractFinishReason(toolCalls.length > 0, choice.finish_reason, {
+      tool_calls: "tool_use",
+      length: "length",
+      content_filter: "content_filter"
+    });
     const reasoningContent = message.reasoning_content ?? null;
     const moderation = parseNativeModeration(r.moderation);
+    const citations = extractCitations("completions", raw);
     return {
       id: r.id,
       model: r.model,
@@ -41051,6 +41217,7 @@ var OpenAIAdapter = class {
       text,
       toolCalls,
       media,
+      ...citations.length ? { citations } : {},
       thinking: reasoningContent,
       ...moderation ? { moderation } : {},
       latencyMs,
@@ -41083,6 +41250,18 @@ var OpenAIAdapter = class {
     if (delta.content) {
       events.push({ type: "text", text: delta.content });
     }
+    for (const note of delta.annotations ?? []) {
+      const detail = note.url_citation ?? note;
+      if (note.type === "url_citation" && detail.url) {
+        events.push({
+          type: "citation",
+          citation: {
+            url: detail.url,
+            ...detail.title ? { title: detail.title } : {}
+          }
+        });
+      }
+    }
     const toolIdByIndex = state?.toolIdByIndex ?? /* @__PURE__ */ new Map();
     const toolCalls = delta.tool_calls ?? [];
     for (const tc of toolCalls) {
@@ -41993,6 +42172,7 @@ var OpenAIResponsesAdapter = class {
       if (text && content.length === 0) content.push({ type: "text", text });
     }
     const moderation = parseNativeModeration(r.moderation);
+    const citations = extractCitations("responses", raw);
     return {
       id: r.id,
       model: r.model ?? "",
@@ -42003,6 +42183,7 @@ var OpenAIResponsesAdapter = class {
       toolCalls,
       thinking,
       media,
+      ...citations.length ? { citations } : {},
       ...files.length ? { files } : {},
       ...builtinToolCalls.length ? { builtinToolCalls } : {},
       ...moderation ? { moderation } : {},
@@ -42015,6 +42196,19 @@ var OpenAIResponsesAdapter = class {
     const data = sseJson(event);
     const type = data.type;
     const events = [];
+    if (type === "response.output_text.annotation.added") {
+      const note = data.annotation ?? {};
+      if (note.type === "url_citation" && note.url) {
+        events.push({
+          type: "citation",
+          citation: {
+            url: note.url,
+            ...note.title ? { title: note.title } : {}
+          }
+        });
+      }
+      return events;
+    }
     if (type === "response.output_text.delta") {
       const itemId = data.item_id;
       const phase = itemId ? phaseByItem?.get(itemId) : void 0;
@@ -42335,10 +42529,6 @@ var XAIBatchAdapter = class {
       throw new Error(`xAI batch create failed: ${JSON.stringify(createRes.body)}`);
     const batch2 = createRes.body ?? {};
     const batchId = batch2.batch_id ?? batch2.id;
-    const _batchRequests = requests.map((r) => ({
-      batch_request_id: r.customId,
-      batch_request: { endpoint: "responses", body: r.body }
-    }));
     const addRes = await fetch2(this.buildAddRequestsRequest(batchId, requests));
     if (addRes.status >= 400)
       throw new Error(`xAI batch add requests failed: ${JSON.stringify(addRes.body)}`);
@@ -43853,7 +44043,8 @@ function makeStepState() {
     stepToolCalls: [],
     toolCallAccum: /* @__PURE__ */ new Map(),
     stepUsage: emptyUsage(),
-    stepFinishReason: "stop"
+    stepFinishReason: "stop",
+    stepCitations: /* @__PURE__ */ new Map()
   };
 }
 function accumulateStreamEvent(event, state) {
@@ -43887,6 +44078,9 @@ function accumulateStreamEvent(event, state) {
       }
       return null;
     }
+    case "citation":
+      state.stepCitations.set(event.citation.url, event.citation);
+      return null;
     case "usage":
       state.stepUsage = event.usage;
       return null;
@@ -43944,6 +44138,7 @@ function buildStepResponse(state, model, stepStart) {
     toolCalls: state.stepToolCalls,
     thinking: state.stepThinking || null,
     media: [],
+    ...state.stepCitations.size ? { citations: [...state.stepCitations.values()] } : {},
     latencyMs: stepLatency,
     raw: null
   };
@@ -44285,6 +44480,8 @@ var AgentLoop = class _AgentLoop {
       // final LLM response (e.g. code-execution files produced during the run).
       ...last?.files ? { files: last.files } : {},
       ...last?.builtinToolCalls ? { builtinToolCalls: last.builtinToolCalls } : {},
+      // Every step's sources, not just the final step's — see the accumulator.
+      ...args.citations.length ? { citations: args.citations } : {},
       ...last?.moderation ? { moderation: last.moderation } : {},
       latencyMs: performance.now() - args.startPerf,
       raw: args.raw
@@ -44351,6 +44548,7 @@ var AgentLoop = class _AgentLoop {
     let stepCount = 0;
     let toolCallCount = 0;
     let lastResponse = null;
+    const citationsByUrl = /* @__PURE__ */ new Map();
     let reason = "done";
     let errorMsg;
     let caughtError;
@@ -44392,6 +44590,7 @@ var AgentLoop = class _AgentLoop {
         const stepLatency = performance.now() - stepStart;
         totalLlmTimeMs += stepLatency;
         addUsage(totalUsage, lastResponse.usage);
+        for (const cite of lastResponse.citations ?? []) citationsByUrl.set(cite.url, cite);
         if (this._reflectRetry?.handles(lastResponse.finishReason)) {
           const verdict = this._reflectRetry.recordFailure();
           await this.hooks.emit("onWarning", {
@@ -44499,6 +44698,7 @@ var AgentLoop = class _AgentLoop {
       totalUsage,
       lastResponse,
       media: lastResponse?.media ?? [],
+      citations: [...citationsByUrl.values()],
       raw: lastResponse?.raw ?? null
     });
     await this.settleRun({
@@ -44544,6 +44744,7 @@ var AgentLoop = class _AgentLoop {
     let finalText = "";
     let finalContent = [];
     let lastResponse = null;
+    const citationsByUrl = /* @__PURE__ */ new Map();
     let reason = "done";
     let errorMsg;
     let caughtError;
@@ -44598,6 +44799,7 @@ var AgentLoop = class _AgentLoop {
         finalContent = content;
         finalText = state.stepText;
         lastResponse = stepResponse;
+        for (const cite of stepResponse.citations ?? []) citationsByUrl.set(cite.url, cite);
         this._history.append(
           {
             ...buildAssistantMessage(lastResponse, {
@@ -44681,6 +44883,7 @@ var AgentLoop = class _AgentLoop {
       finalContent,
       totalUsage,
       lastResponse,
+      citations: [...citationsByUrl.values()],
       // The streaming path already emitted media as events, and never holds a
       // raw provider payload.
       media: [],
@@ -54674,37 +54877,26 @@ function listModels(opts = {}) {
 var LIVE = {
   openai: {
     url: "https://api.openai.com/v1/models",
-    headers: (k) => ({ authorization: `Bearer ${k}` }),
     items: (b) => b.data ?? [],
     id: (m) => m.id
   },
   openrouter: {
     url: "https://openrouter.ai/api/v1/models",
-    headers: (k) => ({ authorization: `Bearer ${k}` }),
     items: (b) => b.data ?? [],
     id: (m) => m.id
   },
   xai: {
     url: "https://api.x.ai/v1/models",
-    headers: (k) => ({ authorization: `Bearer ${k}` }),
     items: (b) => b.data ?? [],
     id: (m) => m.id
   },
   anthropic: {
     url: "https://api.anthropic.com/v1/models",
-    // Mirror the chat adapter: Anthropic rejects browser requests without the
-    // explicit opt-in header, so the /models call must send it too.
-    headers: (k) => ({
-      "x-api-key": k,
-      "anthropic-version": ANTHROPIC_API_VERSION,
-      ...isBrowser() ? { "anthropic-dangerous-direct-browser-access": "true" } : {}
-    }),
     items: (b) => b.data ?? [],
     id: (m) => m.id
   },
   google: {
     url: "https://generativelanguage.googleapis.com/v1beta/models",
-    headers: (k) => ({ "x-goog-api-key": k }),
     items: (b) => b.models ?? [],
     id: (m) => m.name.replace(/^models\//, "")
   }
@@ -54797,7 +54989,9 @@ async function fetchLiveBody(opts) {
   const p = (async () => {
     const built = buildFromSpec(
       utilitySpec(`${opts.provider}/models.list`),
-      {},
+      // Anthropic refuses a browser request without an explicit opt-in header,
+      // and the spec asks for `browser` to decide whether to send it.
+      { browser: isBrowser() },
       makeRegistry({}),
       opts.provider,
       void 0,

package/dist/index.d.ts

@@ -49,7 +49,7 @@ export type { AssistantPhase, Role, MessageOrigin, ContentPart, TextPart, ImageP
 export { isFunctionTool, isBuiltinTool } from './llm/types/tools';
 export type { FunctionTool, BuiltinTool, McpToolParams, Tool, ToolChoice, JsonSchema } from './llm/types/tools';
 export { emptyUsage } from './llm/types/response';
-export type { BuiltinToolCall, CompletionResponse, FileOutput, FinishReason, KnownFinishReason, Usage, } from './llm/types/response';
+export type { BuiltinToolCall, Citation, CompletionResponse, FileOutput, FinishReason, KnownFinishReason, Usage, } from './llm/types/response';
 export type { FileStream, RetrievedFile } from './llm/files/retrieve';
 export type { CacheConfig, NormalizedRequest, ProviderOptions, ReasoningContext, ThinkingConfig } from './llm/types/request';
 export type { MediaStreamType, StreamEvent } from './llm/types/stream';

package/dist/index.js

@@ -30896,7 +30896,7 @@ var xai_create_default = {
 var xai_addRequests_default = {
   id: "xai/batch.addRequests",
   extends: "xai/batch.base",
-  _note: "Step 2 of submit. Step 1 creates the batch and is NOT modelled: its body embeds Date.now(), so the request is not reproducible. See report 039 A3.",
+  _note: "Step 2 of submit: the batch opened in step 1 is filled here. batch_request is a TAGGED UNION whose variant name is the KEY -- {responses: <body>}, never {endpoint: 'responses', body: <body>}. Measured live 2026-08-28: the endpoint-field form is rejected 422 with 'unknown variant endpoint, expected one of chat_get_completion, responses, image_generation, image_edit, video_generation, video_extension'. That form had never been sent to xAI, here or in the TypeScript adapter this spec came from.",
   envelope: {
     method: "POST",
     url: { $join: [{ $config: "baseURL" }, "/v1/batches/", { $: "batchId" }, "/requests"] },
@@ -30912,7 +30912,7 @@ var xai_addRequests_default = {
           {
             value: {
               batch_request_id: { $: "@customId" },
-              batch_request: { endpoint: "responses", body: { $: "@body" } }
+              batch_request: { responses: { $: "@body" } }
             }
           }
         ]
@@ -31264,6 +31264,42 @@ var xai_upload_default = {
   multipart: [{ name: "file", file: true }, { name: "purpose", value: "assistants" }]
 };
 
+// src/wire/specs/files/xai.delete.json
+var xai_delete_default = {
+  id: "xai/files.delete",
+  extends: "openai/files.base",
+  _note: "Same shape as OpenAI's, per xai.upload's note that the surface differs only in the upload purpose. baseURL is supplied by the adapter, so the path is all that is declared here.",
+  envelope: {
+    method: "DELETE",
+    bodyKind: "none",
+    url: { $join: [{ $config: "baseURL" }, "/v1/files/", { $: "remoteId" }] }
+  }
+};
+
+// src/wire/specs/files/xai.getInfo.json
+var xai_getInfo_default = {
+  id: "xai/files.getInfo",
+  extends: "openai/files.base",
+  _note: "Same shape as OpenAI's, per xai.upload's note that the surface differs only in the upload purpose. baseURL is supplied by the adapter, so the path is all that is declared here.",
+  envelope: {
+    method: "GET",
+    bodyKind: "none",
+    url: { $join: [{ $config: "baseURL" }, "/v1/files/", { $: "remoteId" }] }
+  }
+};
+
+// src/wire/specs/files/xai.list.json
+var xai_list_default = {
+  id: "xai/files.list",
+  extends: "openai/files.base",
+  _note: "Same shape as OpenAI's, per xai.upload's note that the surface differs only in the upload purpose. baseURL is supplied by the adapter, so the path is all that is declared here.",
+  envelope: {
+    method: "GET",
+    bodyKind: "none",
+    url: { $join: [{ $config: "baseURL" }, "/v1/files"] }
+  }
+};
+
 // src/wire/specs/files/google.finishUpload.json
 var google_finishUpload_default = {
   id: "google/files.finishUpload",
@@ -31504,6 +31540,9 @@ var DELTAS = new Map(
     google_getInfo_default,
     google_list_default,
     xai_upload_default,
+    xai_delete_default,
+    xai_getInfo_default,
+    xai_list_default,
     google_finishUpload_default,
     videos_status_default,
     videos_cancel_default,
@@ -32314,6 +32353,14 @@ var anthropic_default3 = {
         value: {
           $config: "apiVersion"
         }
+      },
+      {
+        name: "anthropic-dangerous-direct-browser-access",
+        value: "true",
+        _note: "Only in a browser, where the request is otherwise blocked by CORS. The chat path sends it (messages.ts) and so do the files specs; models.list lost it when this request moved to a spec, because the header lived in the helper's own table.",
+        when: {
+          truthy: "browser"
+        }
       }
     ]
   }
@@ -36590,6 +36637,7 @@ var LLMClient = class {
     let moderationReport;
     const files = [];
     const builtinToolCalls = [];
+    const citationsByUrl = /* @__PURE__ */ new Map();
     const fetchStream = this.fetchStreamFn;
     const queueName = this.queueName;
     const priority = this.priority;
@@ -36643,6 +36691,9 @@ var LLMClient = class {
         case "file":
           files.push(event.file);
           break;
+        case "citation":
+          citationsByUrl.set(event.citation.url, event.citation);
+          break;
         case "builtin_tool_end":
           builtinToolCalls.push({
             tool: event.tool,
@@ -36677,6 +36728,7 @@ var LLMClient = class {
       media: [],
       ...files.length ? { files } : {},
       ...builtinToolCalls.length ? { builtinToolCalls } : {},
+      ...citationsByUrl.size ? { citations: [...citationsByUrl.values()] } : {},
       ...moderationReport ? { moderation: moderationReport } : {},
       latencyMs: performance.now() - start,
       raw: null
@@ -38487,6 +38539,87 @@ function pinFor(model, pins) {
 var ANTHROPIC_MESSAGE_PINS = anthropic_messages_default;
 var GOOGLE_GENERATE_PINS = google_generate_default;
 
+// src/llm/providers/_shared/citations.ts
+function fromAnthropic(raw) {
+  const out = [];
+  for (const block of raw.content ?? []) {
+    for (const cite of block.citations ?? []) {
+      const url = cite.url;
+      if (url) {
+        out.push({
+          url,
+          ...cite.title ? { title: cite.title } : {},
+          // Anthropic is the only provider that reports the cited passage.
+          ...cite.cited_text ? { text: cite.cited_text } : {}
+        });
+      }
+    }
+  }
+  return out;
+}
+function fromGoogle(raw) {
+  const out = [];
+  for (const candidate of raw.candidates ?? []) {
+    const grounding = candidate.groundingMetadata ?? {};
+    for (const chunk of grounding.groundingChunks ?? []) {
+      const web = chunk.web ?? {};
+      const uri = web.uri;
+      if (uri) out.push({ url: uri, ...web.title ? { title: web.title } : {} });
+    }
+  }
+  return out;
+}
+function fromResponses(raw) {
+  const out = [];
+  for (const item of raw.output ?? []) {
+    for (const part of item.content ?? []) {
+      for (const note of part.annotations ?? []) {
+        if (note.type === "url_citation" && note.url) {
+          out.push({
+            url: note.url,
+            ...note.title ? { title: note.title } : {}
+          });
+        }
+      }
+    }
+  }
+  return out;
+}
+function fromCompletions(raw) {
+  const out = [];
+  const message = (raw.choices ?? [])[0]?.message ?? {};
+  for (const note of message.annotations ?? []) {
+    const detail = note.url_citation ?? note;
+    if (note.type === "url_citation" && detail.url) {
+      out.push({
+        url: detail.url,
+        ...detail.title ? { title: detail.title } : {}
+      });
+    }
+  }
+  for (const url of raw.citations ?? []) {
+    if (typeof url === "string") out.push({ url });
+  }
+  return out;
+}
+var READERS = {
+  messages: fromAnthropic,
+  generate: fromGoogle,
+  responses: fromResponses,
+  completions: fromCompletions
+  // `interactions` is DELIBERATELY absent. Google's Interactions API returns a
+  // `steps[]` machine, not `candidates[]`, so `fromGoogle` would read a key that
+  // is never there -- and no recorded Interactions response carries grounding, so
+  // there is nothing to write a reader against. Guessing the shape would produce
+  // a reader that is confidently wrong and passes a test built from the same
+  // guess. The adapter is wired anyway: when the shape is measured, only this
+  // table changes.
+};
+function extractCitations(api, raw) {
+  if (raw == null || typeof raw !== "object") return [];
+  return READERS[api]?.(raw) ?? [];
+}
+
 // src/llm/providers/_shared/builtin-tools.ts
 var NATIVE_TO_UNIFIED = {
   // OpenAI / xAI Responses output-item types
@@ -38705,6 +38838,7 @@ var AnthropicAdapter = class {
       model_context_window_exceeded: "length",
       refusal: "content_filter"
     });
+    const citations = extractCitations("messages", raw);
     return {
       id: r.id,
       model: r.model,
@@ -38714,6 +38848,7 @@ var AnthropicAdapter = class {
       text: content.filter((p) => p.type === "text").map((p) => p.text).join(""),
       toolCalls,
       media: [],
+      ...citations.length ? { citations } : {},
       ...files.length ? { files } : {},
       ...builtinToolCalls.length ? { builtinToolCalls } : {},
       thinking,
@@ -38741,6 +38876,20 @@ var AnthropicAdapter = class {
       if (delta.type === "text_delta") return [{ type: "text", text: delta.text }];
       if (delta.type === "thinking_delta")
         return [{ type: "thinking", text: delta.thinking }];
+      if (delta.type === "citations_delta") {
+        const cite = delta.citation ?? {};
+        const url = cite.url;
+        return url ? [
+          {
+            type: "citation",
+            citation: {
+              url,
+              ...cite.title ? { title: cite.title } : {},
+              ...cite.cited_text ? { text: cite.cited_text } : {}
+            }
+          }
+        ] : [];
+      }
       if (delta.type === "input_json_delta") {
         if (state.current) {
           state.current.json += delta.partial_json ?? "";
@@ -39291,6 +39440,7 @@ var GoogleAdapter = class {
         builtinToolCalls.push({ tool: "web_fetch", ...typeof url === "string" ? { url } : {} });
       }
     }
+    const citations = extractCitations("generate", raw);
     return {
       // generateContent DOES return an id — `responseId`, at the top level. The
       // fallback stays for older payloads, but minting one unconditionally made
@@ -39306,6 +39456,7 @@ var GoogleAdapter = class {
       toolCalls,
       thinking,
       media,
+      ...citations.length ? { citations } : {},
       ...files.length ? { files } : {},
       ...builtinToolCalls.length ? { builtinToolCalls } : {},
       latencyMs,
@@ -39390,6 +39541,18 @@ var GoogleAdapter = class {
         events.push({ type: "tool_call_end", id: "" });
       }
     }
+    for (const chunk of candidate.groundingMetadata?.groundingChunks ?? []) {
+      const web = chunk.web ?? {};
+      if (web.uri) {
+        events.push({
+          type: "citation",
+          citation: {
+            url: web.uri,
+            ...web.title ? { title: web.title } : {}
+          }
+        });
+      }
+    }
     if (candidate.groundingMetadata && !state.webSearchEmitted) {
       state.webSearchEmitted = true;
       const q = candidate.groundingMetadata.webSearchQueries?.[0];
@@ -39612,6 +39775,7 @@ var GoogleInteractionsAdapter = class {
       queued: "pending",
       in_progress: "pending"
     });
+    const citations = extractCitations("interactions", raw);
     return {
       id: r.id ?? crypto.randomUUID(),
       model: "",
@@ -39621,6 +39785,7 @@ var GoogleInteractionsAdapter = class {
       text,
       toolCalls,
       media,
+      ...citations.length ? { citations } : {},
       thinking,
       latencyMs,
       raw
@@ -40962,13 +41127,14 @@ var OpenAIAdapter = class {
       content.push(parsed);
       toolCalls.push(parsed);
     }
-    const finishReason = extractFinishReason(
-      toolCalls.length > 0,
-      choice.finish_reason,
-      { tool_calls: "tool_use", length: "length", content_filter: "content_filter" }
-    );
+    const finishReason = extractFinishReason(toolCalls.length > 0, choice.finish_reason, {
+      tool_calls: "tool_use",
+      length: "length",
+      content_filter: "content_filter"
+    });
     const reasoningContent = message.reasoning_content ?? null;
     const moderation = parseNativeModeration(r.moderation);
+    const citations = extractCitations("completions", raw);
     return {
       id: r.id,
       model: r.model,
@@ -40978,6 +41144,7 @@ var OpenAIAdapter = class {
       text,
       toolCalls,
       media,
+      ...citations.length ? { citations } : {},
       thinking: reasoningContent,
       ...moderation ? { moderation } : {},
       latencyMs,
@@ -41010,6 +41177,18 @@ var OpenAIAdapter = class {
     if (delta.content) {
       events.push({ type: "text", text: delta.content });
     }
+    for (const note of delta.annotations ?? []) {
+      const detail = note.url_citation ?? note;
+      if (note.type === "url_citation" && detail.url) {
+        events.push({
+          type: "citation",
+          citation: {
+            url: detail.url,
+            ...detail.title ? { title: detail.title } : {}
+          }
+        });
+      }
+    }
     const toolIdByIndex = state?.toolIdByIndex ?? /* @__PURE__ */ new Map();
     const toolCalls = delta.tool_calls ?? [];
     for (const tc of toolCalls) {
@@ -41920,6 +42099,7 @@ var OpenAIResponsesAdapter = class {
       if (text && content.length === 0) content.push({ type: "text", text });
     }
     const moderation = parseNativeModeration(r.moderation);
+    const citations = extractCitations("responses", raw);
     return {
       id: r.id,
       model: r.model ?? "",
@@ -41930,6 +42110,7 @@ var OpenAIResponsesAdapter = class {
       toolCalls,
       thinking,
       media,
+      ...citations.length ? { citations } : {},
       ...files.length ? { files } : {},
       ...builtinToolCalls.length ? { builtinToolCalls } : {},
       ...moderation ? { moderation } : {},
@@ -41942,6 +42123,19 @@ var OpenAIResponsesAdapter = class {
     const data = sseJson(event);
     const type = data.type;
     const events = [];
+    if (type === "response.output_text.annotation.added") {
+      const note = data.annotation ?? {};
+      if (note.type === "url_citation" && note.url) {
+        events.push({
+          type: "citation",
+          citation: {
+            url: note.url,
+            ...note.title ? { title: note.title } : {}
+          }
+        });
+      }
+      return events;
+    }
     if (type === "response.output_text.delta") {
       const itemId = data.item_id;
       const phase = itemId ? phaseByItem?.get(itemId) : void 0;
@@ -42262,10 +42456,6 @@ var XAIBatchAdapter = class {
       throw new Error(`xAI batch create failed: ${JSON.stringify(createRes.body)}`);
     const batch2 = createRes.body ?? {};
     const batchId = batch2.batch_id ?? batch2.id;
-    const _batchRequests = requests.map((r) => ({
-      batch_request_id: r.customId,
-      batch_request: { endpoint: "responses", body: r.body }
-    }));
     const addRes = await fetch2(this.buildAddRequestsRequest(batchId, requests));
     if (addRes.status >= 400)
       throw new Error(`xAI batch add requests failed: ${JSON.stringify(addRes.body)}`);
@@ -43780,7 +43970,8 @@ function makeStepState() {
     stepToolCalls: [],
     toolCallAccum: /* @__PURE__ */ new Map(),
     stepUsage: emptyUsage(),
-    stepFinishReason: "stop"
+    stepFinishReason: "stop",
+    stepCitations: /* @__PURE__ */ new Map()
   };
 }
 function accumulateStreamEvent(event, state) {
@@ -43814,6 +44005,9 @@ function accumulateStreamEvent(event, state) {
       }
       return null;
     }
+    case "citation":
+      state.stepCitations.set(event.citation.url, event.citation);
+      return null;
     case "usage":
       state.stepUsage = event.usage;
       return null;
@@ -43871,6 +44065,7 @@ function buildStepResponse(state, model, stepStart) {
     toolCalls: state.stepToolCalls,
     thinking: state.stepThinking || null,
     media: [],
+    ...state.stepCitations.size ? { citations: [...state.stepCitations.values()] } : {},
     latencyMs: stepLatency,
     raw: null
   };
@@ -44212,6 +44407,8 @@ var AgentLoop = class _AgentLoop {
       // final LLM response (e.g. code-execution files produced during the run).
       ...last?.files ? { files: last.files } : {},
       ...last?.builtinToolCalls ? { builtinToolCalls: last.builtinToolCalls } : {},
+      // Every step's sources, not just the final step's — see the accumulator.
+      ...args.citations.length ? { citations: args.citations } : {},
       ...last?.moderation ? { moderation: last.moderation } : {},
       latencyMs: performance.now() - args.startPerf,
       raw: args.raw
@@ -44278,6 +44475,7 @@ var AgentLoop = class _AgentLoop {
     let stepCount = 0;
     let toolCallCount = 0;
     let lastResponse = null;
+    const citationsByUrl = /* @__PURE__ */ new Map();
     let reason = "done";
     let errorMsg;
     let caughtError;
@@ -44319,6 +44517,7 @@ var AgentLoop = class _AgentLoop {
         const stepLatency = performance.now() - stepStart;
         totalLlmTimeMs += stepLatency;
         addUsage(totalUsage, lastResponse.usage);
+        for (const cite of lastResponse.citations ?? []) citationsByUrl.set(cite.url, cite);
         if (this._reflectRetry?.handles(lastResponse.finishReason)) {
           const verdict = this._reflectRetry.recordFailure();
           await this.hooks.emit("onWarning", {
@@ -44426,6 +44625,7 @@ var AgentLoop = class _AgentLoop {
       totalUsage,
       lastResponse,
       media: lastResponse?.media ?? [],
+      citations: [...citationsByUrl.values()],
       raw: lastResponse?.raw ?? null
     });
     await this.settleRun({
@@ -44471,6 +44671,7 @@ var AgentLoop = class _AgentLoop {
     let finalText = "";
     let finalContent = [];
     let lastResponse = null;
+    const citationsByUrl = /* @__PURE__ */ new Map();
     let reason = "done";
     let errorMsg;
     let caughtError;
@@ -44525,6 +44726,7 @@ var AgentLoop = class _AgentLoop {
         finalContent = content;
         finalText = state.stepText;
         lastResponse = stepResponse;
+        for (const cite of stepResponse.citations ?? []) citationsByUrl.set(cite.url, cite);
         this._history.append(
           {
             ...buildAssistantMessage(lastResponse, {
@@ -44608,6 +44810,7 @@ var AgentLoop = class _AgentLoop {
       finalContent,
       totalUsage,
       lastResponse,
+      citations: [...citationsByUrl.values()],
       // The streaming path already emitted media as events, and never holds a
       // raw provider payload.
       media: [],
@@ -54601,37 +54804,26 @@ function listModels(opts = {}) {
 var LIVE = {
   openai: {
     url: "https://api.openai.com/v1/models",
-    headers: (k) => ({ authorization: `Bearer ${k}` }),
     items: (b) => b.data ?? [],
     id: (m) => m.id
   },
   openrouter: {
     url: "https://openrouter.ai/api/v1/models",
-    headers: (k) => ({ authorization: `Bearer ${k}` }),
     items: (b) => b.data ?? [],
     id: (m) => m.id
   },
   xai: {
     url: "https://api.x.ai/v1/models",
-    headers: (k) => ({ authorization: `Bearer ${k}` }),
     items: (b) => b.data ?? [],
     id: (m) => m.id
   },
   anthropic: {
     url: "https://api.anthropic.com/v1/models",
-    // Mirror the chat adapter: Anthropic rejects browser requests without the
-    // explicit opt-in header, so the /models call must send it too.
-    headers: (k) => ({
-      "x-api-key": k,
-      "anthropic-version": ANTHROPIC_API_VERSION,
-      ...isBrowser() ? { "anthropic-dangerous-direct-browser-access": "true" } : {}
-    }),
     items: (b) => b.data ?? [],
     id: (m) => m.id
   },
   google: {
     url: "https://generativelanguage.googleapis.com/v1beta/models",
-    headers: (k) => ({ "x-goog-api-key": k }),
     items: (b) => b.models ?? [],
     id: (m) => m.name.replace(/^models\//, "")
   }
@@ -54724,7 +54916,9 @@ async function fetchLiveBody(opts) {
   const p = (async () => {
     const built = buildFromSpec(
       utilitySpec(`${opts.provider}/models.list`),
-      {},
+      // Anthropic refuses a browser request without an explicit opt-in header,
+      // and the spec asks for `browser` to decide whether to send it.
+      { browser: isBrowser() },
       makeRegistry({}),
       opts.provider,
       void 0,

package/dist/llm/providers/_shared/citations.d.ts

@@ -0,0 +1,25 @@
+/** The sources an answer cited, read from four different wire shapes.
+ *
+ *  `builtinToolCalls` already records what the model INVOKED — that it searched,
+ *  and for what. This is the other half: what it ended up CITING. They are not
+ *  the same list. A model can run three searches and cite one page, or open a
+ *  page and cite nothing, and a caller rendering footnotes needs the second
+ *  list, not the first.
+ *
+ *  Until now this was only reachable by regexing `response.raw`, which is what
+ *  the web-search example actually did. That is a per-consumer reimplementation
+ *  of provider knowledge that belongs in the SDK.
+ *
+ *  This function always returns an array. The RESPONSE FIELD it feeds is
+ *  optional and omitted when empty, like the `files` / `builtinToolCalls` lines
+ *  it sits beside -- R3 forbids adding a required field to a response type, so
+ *  the Python port's always-present array is not available here. Callers read
+ *  `response.citations ?? []`.
+ */
+import type { Citation } from '../../types/response';
+/** Every source the answer cited, or `[]`.
+ *
+ *  `api` is the wire surface (`'messages' | 'generate' | 'interactions' |
+ *  'responses' | 'completions'`). An unknown surface yields `[]` rather than
+ *  throwing: a response we cannot read citations from is still a valid answer. */
+export declare function extractCitations(api: string, raw: unknown): Citation[];

package/dist/llm/types/response.d.ts

@@ -20,6 +20,16 @@ export interface CompletionResponse {
      *  search or code-execution run. A durable trail of what was called (the provider
      *  ran them server-side; nothing for the client to execute). Absent when none. */
     builtinToolCalls?: BuiltinToolCall[];
+    /** Sources the answer cited, unified across providers.
+     *
+     *  Distinct from `builtinToolCalls`, which records what the model INVOKED: a turn
+     *  can run three searches and cite one page, or open a page and cite nothing.
+     *  Rendering footnotes needs this list, not that one.
+     *
+     *  Absent when the model cited nothing — R3: a response type grows by OPTIONAL
+     *  fields only, so this cannot be the always-present array the Python port
+     *  exposes. Read it as `response.citations ?? []`. */
+    citations?: Citation[];
     /** Inline-moderation outcome, when the `moderation` request option was used.
      *  Report-only: present for observability; it never blocks the call. Absent when
      *  moderation was not requested. */
@@ -58,6 +68,19 @@ export interface FileOutput {
      *  Absent for providers that don't need extra context. */
     ref?: Record<string, unknown>;
 }
+/** A source the answer cited.
+ *
+ *  Four providers report these four different ways — Anthropic on the text block,
+ *  Google in `groundingMetadata`, OpenAI as annotations, xAI as bare top-level URLs.
+ *  The differences stop at the adapter. */
+export interface Citation {
+    url: string;
+    /** Page title, when the provider supplies one. */
+    title?: string;
+    /** The passage the source supports. Only Anthropic reports this today; absent
+     *  elsewhere rather than faked from the answer text. */
+    text?: string;
+}
 /** A hosted builtin tool the model invoked (provider-run), with its inputs/outputs. */
 export interface BuiltinToolCall {
     /** Unified tool name: `'web_search'` | `'code_interpreter'` | … (normalized from

package/dist/llm/types/stream.d.ts

@@ -1,7 +1,7 @@
 /** Universal streaming event types. */
 import type { ModerationEntry } from '../moderation/types';
 import type { AssistantPhase } from './messages';
-import type { FileOutput, Usage } from './response';
+import type { Citation, FileOutput, Usage } from './response';
 export type MediaStreamType = 'image' | 'audio' | 'video';
 export type StreamEvent = 
 /** `itemId` identifies WHICH output item a delta belongs to, when the provider reports
@@ -62,6 +62,19 @@ export type StreamEvent =
     type: 'file';
     file: FileOutput;
 }
+/** The answer cited a source. Emitted as the citation arrives, which is NOT
+ *  when the search ran: a provider searches early and cites while it writes, so
+ *  these interleave with `text` deltas. Distinct from `builtin_tool_end`, which
+ *  reports the search itself.
+ *
+ *  Measured shapes: Anthropic `citations_delta`, OpenAI/xAI Responses
+ *  `response.output_text.annotation.added`, chat-completions `delta.annotations`,
+ *  Google's populated `groundingMetadata` chunk. Also collected onto the streamed
+ *  final response's `citations`, deduped by url. */
+ | {
+    type: 'citation';
+    citation: Citation;
+}
 /** A hosted (provider-run) builtin tool began executing server-side — e.g. the
  *  model started a web search or code-execution run. `tool` is the unified name
  *  (`'web_search'` | `'code_interpreter'` | …). Informational progress: unlike

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "Unified, pluggable AI SDK for accessing the LLMs of every major provider (Anthropic, OpenAI, Google, xAI, OpenRouter) through one API. Cross-environment: Node, Bun, and the browser.",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,6 +34,8 @@
     "prepublishOnly": "bun run build",
     "test": "bun test",
     "test:unit": "bun test tests/unit",
+    "test:coverage": "bun test tests/unit --coverage",
+    "coverage:gate": "bun run scripts/coverage-gate.ts",
     "test:integration": "bun test tests/integration",
     "test:helpers": "bun test tests/helpers",
     "test:live": "bun test tests/live",