@combycode/llm-sdk 3.0.0 → 3.2.1

package/dist/index.js

@@ -548,6 +548,7 @@ var TelemetryAdapter = class {
         break;
       case "onModelError":
         this.metrics.errors++;
+        this.metrics.inFlight = Math.max(0, this.metrics.inFlight - 1);
         break;
       case "onCostEntry":
         this.metrics.costUsd += event.ctx.entry?.cost?.total ?? 0;
@@ -3328,7 +3329,8 @@ var anthropic_default = {
   "anthropic/claude-opus-4.1": {
     providerModelName: "claude-opus-4-1-20250805",
     aliases: [
-      "claude-opus-4-1-20250805"
+      "claude-opus-4-1-20250805",
+      "claude-opus-4-1"
     ],
     pricing: {
       inputPerMTok: 15,
@@ -3392,7 +3394,8 @@ var anthropic_default = {
   "anthropic/claude-opus-4.5": {
     providerModelName: "claude-opus-4-5-20251101",
     aliases: [
-      "claude-opus-4-5-20251101"
+      "claude-opus-4-5-20251101",
+      "claude-opus-4-5"
     ],
     pricing: {
       inputPerMTok: 5,
@@ -3731,7 +3734,8 @@ var anthropic_default = {
   "anthropic/claude-sonnet-4.5": {
     providerModelName: "claude-sonnet-4-5-20250929",
     aliases: [
-      "claude-sonnet-4-5-20250929"
+      "claude-sonnet-4-5-20250929",
+      "claude-sonnet-4-5"
     ],
     pricing: {
       inputPerMTok: 3,
@@ -3865,7 +3869,8 @@ var anthropic_default = {
   "anthropic/claude-haiku-4.5": {
     providerModelName: "claude-haiku-4-5-20251001",
     aliases: [
-      "claude-haiku-4-5-20251001"
+      "claude-haiku-4-5-20251001",
+      "claude-haiku-4-5"
     ],
     pricing: {
       inputPerMTok: 1,
@@ -4224,7 +4229,7 @@ var google_default = {
       structuredOutput: true,
       vision: true,
       audio: true,
-      video: false,
+      video: true,
       imageGeneration: false,
       audioGeneration: false,
       videoGeneration: false
@@ -4240,7 +4245,9 @@ var google_default = {
     inputModalities: [
       "text",
       "image",
-      "audio"
+      "audio",
+      "pdf",
+      "video"
     ],
     outputModalities: [
       "text"
@@ -4296,7 +4303,7 @@ var google_default = {
       structuredOutput: true,
       vision: true,
       audio: true,
-      video: false,
+      video: true,
       imageGeneration: false,
       audioGeneration: false,
       videoGeneration: false
@@ -4318,7 +4325,9 @@ var google_default = {
     inputModalities: [
       "text",
       "image",
-      "audio"
+      "audio",
+      "pdf",
+      "video"
     ],
     outputModalities: [
       "text"
@@ -4356,7 +4365,7 @@ var google_default = {
       structuredOutput: true,
       vision: true,
       audio: true,
-      video: false,
+      video: true,
       imageGeneration: false,
       audioGeneration: false,
       videoGeneration: false
@@ -4372,7 +4381,9 @@ var google_default = {
     inputModalities: [
       "text",
       "image",
-      "audio"
+      "audio",
+      "pdf",
+      "video"
     ],
     outputModalities: [
       "text"
@@ -4431,7 +4442,7 @@ var google_default = {
       structuredOutput: true,
       vision: true,
       audio: true,
-      video: false,
+      video: true,
       imageGeneration: false,
       audioGeneration: false,
       videoGeneration: false
@@ -4447,7 +4458,9 @@ var google_default = {
     inputModalities: [
       "text",
       "image",
-      "audio"
+      "audio",
+      "pdf",
+      "video"
     ],
     outputModalities: [
       "text"
@@ -4506,7 +4519,7 @@ var google_default = {
       structuredOutput: true,
       vision: true,
       audio: true,
-      video: false,
+      video: true,
       imageGeneration: false,
       audioGeneration: false,
       videoGeneration: false
@@ -4529,7 +4542,9 @@ var google_default = {
     inputModalities: [
       "text",
       "image",
-      "audio"
+      "audio",
+      "pdf",
+      "video"
     ],
     outputModalities: [
       "text"
@@ -4584,7 +4599,7 @@ var google_default = {
       structuredOutput: true,
       vision: true,
       audio: true,
-      video: false,
+      video: true,
       imageGeneration: false,
       audioGeneration: false,
       videoGeneration: false
@@ -4600,7 +4615,9 @@ var google_default = {
     inputModalities: [
       "text",
       "image",
-      "audio"
+      "audio",
+      "pdf",
+      "video"
     ],
     outputModalities: [
       "text"
@@ -4659,7 +4676,7 @@ var google_default = {
       structuredOutput: true,
       vision: true,
       audio: true,
-      video: false,
+      video: true,
       imageGeneration: false,
       audioGeneration: false,
       videoGeneration: false
@@ -4675,7 +4692,9 @@ var google_default = {
     inputModalities: [
       "text",
       "image",
-      "audio"
+      "audio",
+      "pdf",
+      "video"
     ],
     outputModalities: [
       "text"
@@ -4735,7 +4754,7 @@ var google_default = {
       structuredOutput: true,
       vision: true,
       audio: true,
-      video: false,
+      video: true,
       imageGeneration: false,
       audioGeneration: false,
       videoGeneration: false
@@ -4751,7 +4770,9 @@ var google_default = {
     inputModalities: [
       "text",
       "image",
-      "audio"
+      "audio",
+      "pdf",
+      "video"
     ],
     outputModalities: [
       "text"
@@ -5734,7 +5755,8 @@ var google_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -5787,7 +5809,8 @@ var google_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -6956,7 +6979,7 @@ var google_default = {
       structuredOutput: true,
       vision: true,
       audio: true,
-      video: false,
+      video: true,
       imageGeneration: false,
       audioGeneration: false,
       videoGeneration: false
@@ -6972,7 +6995,9 @@ var google_default = {
     inputModalities: [
       "text",
       "image",
-      "audio"
+      "audio",
+      "pdf",
+      "video"
     ],
     outputModalities: [
       "text"
@@ -7028,7 +7053,7 @@ var google_default = {
       structuredOutput: true,
       vision: true,
       audio: true,
-      video: false,
+      video: true,
       imageGeneration: false,
       audioGeneration: false,
       videoGeneration: false
@@ -7044,7 +7069,9 @@ var google_default = {
     inputModalities: [
       "text",
       "image",
-      "audio"
+      "audio",
+      "pdf",
+      "video"
     ],
     outputModalities: [
       "text"
@@ -7099,7 +7126,7 @@ var google_default = {
       structuredOutput: true,
       vision: true,
       audio: true,
-      video: false,
+      video: true,
       imageGeneration: false,
       audioGeneration: false,
       videoGeneration: false
@@ -7115,7 +7142,9 @@ var google_default = {
     inputModalities: [
       "text",
       "image",
-      "audio"
+      "audio",
+      "pdf",
+      "video"
     ],
     outputModalities: [
       "text"
@@ -7405,7 +7434,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -7465,7 +7495,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -7521,7 +7552,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -7632,7 +7664,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -7688,7 +7721,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -7768,7 +7802,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -7841,7 +7876,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -7896,7 +7932,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -7955,7 +7992,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -8014,7 +8052,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -8073,7 +8112,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -8490,7 +8530,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -8553,7 +8594,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -8633,7 +8675,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -8696,7 +8739,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -8763,7 +8807,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -8838,7 +8883,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -8892,7 +8938,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -8946,7 +8993,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -9016,7 +9064,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -9080,7 +9129,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -9138,7 +9188,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -9195,7 +9246,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -10275,7 +10327,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -10332,7 +10385,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -10397,7 +10451,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -10514,7 +10569,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -10582,7 +10638,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -11622,7 +11679,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -11700,7 +11758,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -11778,7 +11837,8 @@ var openai_default = {
     type: "chat",
     inputModalities: [
       "text",
-      "image"
+      "image",
+      "pdf"
     ],
     outputModalities: [
       "text"
@@ -29485,14 +29545,23 @@ function withBuiltinTools(provider, caps) {
   if (!tools || tools.length === 0) return caps;
   return { ...caps, builtinTools: [...tools] };
 }
+function normalizeId(model) {
+  return model.toLowerCase().replace(/(?<=\d)[-.](?=\d)/g, ".");
+}
 var ModelCatalog = class _ModelCatalog {
   models = /* @__PURE__ */ new Map();
   /** `provider/alias` → `provider/canonical-slug`. Lets get()/resolveModelId
    *  accept any callable id (providerModelName, dated snapshot) AND the slug. */
   aliasIndex = /* @__PURE__ */ new Map();
+  /** `provider/normalized-id` → `provider/canonical-slug`. The last resort, so a
+   *  user's spelling of a version never decides whether the model is found. */
+  normIndex = /* @__PURE__ */ new Map();
   key(provider, model) {
     return `${provider}/${model}`;
   }
+  normKey(provider, model) {
+    return `${provider}/${normalizeId(model)}`;
+  }
   set(provider, model, info) {
     const canonical = this.key(provider, model);
     this.models.set(canonical, {
@@ -29530,19 +29599,39 @@ var ModelCatalog = class _ModelCatalog {
         this.aliasIndex.set(this.key(provider, alias), canonical);
       }
     }
+    for (const name of [model, info.providerModelName, ...info.aliases ?? []]) {
+      if (!name) continue;
+      const nk = this.normKey(provider, name);
+      if (!this.normIndex.has(nk)) this.normIndex.set(nk, canonical);
+    }
   }
   get(provider, model) {
     const direct = this.models.get(this.key(provider, model));
     if (direct) return direct;
-    const canonical = this.aliasIndex.get(this.key(provider, model));
+    const canonical = this.aliasIndex.get(this.key(provider, model)) ?? // Last resort: the same model under a different spelling of its version.
+    this.normIndex.get(this.normKey(provider, model));
     return canonical ? this.models.get(canonical) ?? null : null;
   }
-  /** The exact id to SEND to the provider for a given model string. Translates
-   *  our slug → providerModelName; passes an already-callable id (alias) through
-   *  verbatim (respects an explicit choice); unknown model → verbatim passthrough. */
+  /** The exact id to SEND to the provider for a given model string.
+   *
+   *  Three cases, and the difference between them is what the caller ASKED for:
+   *    - our slug            → translate to providerModelName (the pinned snapshot)
+   *    - an id the provider itself accepts (a listed alias, e.g. a dated snapshot
+   *      or anthropic's undated name) → verbatim, because it is a deliberate choice
+   *      and rewriting it would pin a caller who asked to float
+   *    - a spelling variant that is NOT callable (`gemini-2-5-flash`) → the
+   *      canonical entry's providerModelName, since forwarding it verbatim only
+   *      produces a 404 with the user's typo in it
+   *    - unknown → verbatim, so a model we have never heard of still works */
   resolveModelId(provider, model) {
     const direct = this.models.get(this.key(provider, model));
     if (direct) return direct.providerModelName ?? model;
+    if (this.aliasIndex.has(this.key(provider, model))) return model;
+    const canonical = this.normIndex.get(this.normKey(provider, model));
+    if (canonical) {
+      const info = this.models.get(canonical);
+      if (info) return info.providerModelName ?? info.model;
+    }
     return model;
   }
   getPricing(provider, model) {
@@ -29691,14 +29780,31 @@ function evalCond(cond, ctx, reg) {
     const t = ctx.item?.value;
     return !reg.predicates.isFunctionTool(ctx) && t?.type === c.builtin;
   }
+  if ("hasPartType" in c) {
+    const messages = ctx.req.messages;
+    return Boolean(
+      messages?.some(
+        (m) => Array.isArray(m?.content) ? m.content.some((part) => c.hasPartType.includes(part?.type)) : false
+      )
+    );
+  }
   if ("hasTool" in c) {
     const tools = ctx.req.tools;
-    return Boolean(
+    const present = Boolean(
       tools?.some((t) => {
         const itemCtx = { ...ctx, item: { value: t, index: 0, isLast: false } };
         return !reg.predicates.isFunctionTool(itemCtx) && t?.type === c.hasTool;
       })
     );
+    if (!present) return false;
+    const blocked = ctx.spec.toolConstraints?.find(
+      (tc) => tc.tool === c.hasTool && evalCond(tc.conflictsWith, ctx, reg)
+    );
+    if (blocked) {
+      if (ctx.notes && !ctx.notes.includes(blocked.why)) ctx.notes.push(blocked.why);
+      return false;
+    }
+    return true;
   }
   if ("hasFunctionTool" in c) {
     const tools = ctx.req.tools;
@@ -29824,7 +29930,8 @@ function buildFromSpec(spec, req, reg, flavor = spec.provider, onUse, config = {
     flavor,
     config,
     variants: resolveVariants(spec, req.model ?? "", reg),
-    body: {}
+    body: {},
+    notes: []
   };
   for (const v of ctx.variants) onUse?.("variant", v);
   for (const f of spec.fields ?? []) {
@@ -29919,6 +30026,7 @@ function buildFromSpec(spec, req, reg, flavor = spec.provider, onUse, config = {
     }
   }
   const out = { body: ctx.body };
+  if (ctx.notes?.length) out.notes = ctx.notes;
   if (ctx.multipart) out.multipart = ctx.multipart;
   if (spec.envelope?.bodyKind === "none") out.noBody = true;
   if (spec.envelope?.bodyKind === "raw") out.rawBody = true;
@@ -30788,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"] },
@@ -30804,7 +30912,7 @@ var xai_addRequests_default = {
           {
             value: {
               batch_request_id: { $: "@customId" },
-              batch_request: { endpoint: "responses", body: { $: "@body" } }
+              batch_request: { responses: { $: "@body" } }
             }
           }
         ]
@@ -31156,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",
@@ -31396,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,
@@ -32206,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"
+        }
       }
     ]
   }
@@ -36216,6 +36371,18 @@ var LLMClient = class {
     return streamFile(file, this.retrieveContext());
   }
   /** Submit a request. Returns the parsed CompletionResponse. */
+  /** Anything the spec left out on purpose reaches the caller as a warning.
+   *  Said once per request; the build already de-duplicates within one. */
+  reportBuildNotes(req, ctx) {
+    for (const note of req.notes ?? []) {
+      this.hooks.emitSync("onWarning", {
+        source: "llm",
+        code: "request_adjusted",
+        message: note,
+        details: { provider: this.provider, model: this.model, ctx }
+      });
+    }
+  }
   async complete(input, options = {}) {
     const rawMessages = normalizeInput(input);
     const { system: systemFromMessages, messages } = extractSystem(rawMessages);
@@ -36278,6 +36445,7 @@ var LLMClient = class {
       normalized.messages = decision.messages;
     }
     const providerReq = this.adapter.buildRequest(normalized);
+    this.reportBuildNotes(providerReq, ctx);
     const url = this.adapter.baseURL() + (providerReq.path ?? this.adapter.completionPath());
     if (this.cacheKeyFn) {
       ctx.cacheKey = ctx.cacheKey ?? this.cacheKeyFn(normalized, ctx);
@@ -36439,6 +36607,7 @@ var LLMClient = class {
     normalized.messages = resolveCtx.messages;
     normalized.system = resolveCtx.system;
     const providerReq = this.adapter.buildRequest(normalized);
+    this.reportBuildNotes(providerReq, ctx);
     this.adapter.enableStreaming?.(providerReq, normalized);
     const url = this.adapter.baseURL() + (providerReq.path ?? this.adapter.completionPath());
     const httpReq = {
@@ -36468,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;
@@ -36521,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,
@@ -36555,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
@@ -37217,6 +37391,14 @@ var generate_2_5_default = {
   id: "google/generate@2.5",
   provider: "google",
   api: "generate",
+  _toolConstraints: `Measured 2026-08-25: Google answers 400 "The mime type: X is not supported for code execution" when codeExecution is sent with a PDF or a video part. Images are fine, googleSearch is fine, and OpenAI accepts every combination -- so this is one provider's rule, kept with that provider's spec.`,
+  toolConstraints: [
+    {
+      tool: "code_interpreter",
+      conflictsWith: { hasPartType: ["document", "video"] },
+      why: "google: code execution cannot run alongside a PDF or video attachment, so the request was sent without it"
+    }
+  ],
   tables: {
     toolMode: {
       auto: "AUTO",
@@ -38357,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
@@ -38575,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,
@@ -38584,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,
@@ -38611,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 ?? "";
@@ -39161,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
@@ -39176,6 +39456,7 @@ var GoogleAdapter = class {
       toolCalls,
       thinking,
       media,
+      ...citations.length ? { citations } : {},
       ...files.length ? { files } : {},
       ...builtinToolCalls.length ? { builtinToolCalls } : {},
       latencyMs,
@@ -39260,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];
@@ -39482,6 +39775,7 @@ var GoogleInteractionsAdapter = class {
       queued: "pending",
       in_progress: "pending"
     });
+    const citations = extractCitations("interactions", raw);
     return {
       id: r.id ?? crypto.randomUUID(),
       model: "",
@@ -39491,6 +39785,7 @@ var GoogleInteractionsAdapter = class {
       text,
       toolCalls,
       media,
+      ...citations.length ? { citations } : {},
       thinking,
       latencyMs,
       raw
@@ -40832,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,
@@ -40848,6 +41144,7 @@ var OpenAIAdapter = class {
       text,
       toolCalls,
       media,
+      ...citations.length ? { citations } : {},
       thinking: reasoningContent,
       ...moderation ? { moderation } : {},
       latencyMs,
@@ -40880,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) {
@@ -41790,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 ?? "",
@@ -41800,6 +42110,7 @@ var OpenAIResponsesAdapter = class {
       toolCalls,
       thinking,
       media,
+      ...citations.length ? { citations } : {},
       ...files.length ? { files } : {},
       ...builtinToolCalls.length ? { builtinToolCalls } : {},
       ...moderation ? { moderation } : {},
@@ -41812,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;
@@ -42132,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)}`);
@@ -43650,7 +43970,8 @@ function makeStepState() {
     stepToolCalls: [],
     toolCallAccum: /* @__PURE__ */ new Map(),
     stepUsage: emptyUsage(),
-    stepFinishReason: "stop"
+    stepFinishReason: "stop",
+    stepCitations: /* @__PURE__ */ new Map()
   };
 }
 function accumulateStreamEvent(event, state) {
@@ -43684,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;
@@ -43741,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
   };
@@ -44082,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
@@ -44148,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;
@@ -44189,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", {
@@ -44296,6 +44625,7 @@ var AgentLoop = class _AgentLoop {
       totalUsage,
       lastResponse,
       media: lastResponse?.media ?? [],
+      citations: [...citationsByUrl.values()],
       raw: lastResponse?.raw ?? null
     });
     await this.settleRun({
@@ -44341,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;
@@ -44395,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, {
@@ -44478,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: [],
@@ -54471,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\//, "")
   }
@@ -54594,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,
@@ -54670,6 +54994,35 @@ var KNOWN_KEYS = /* @__PURE__ */ new Set([
   ...Object.keys(CAP_KEYS),
   ...Object.keys(BUILTIN_TOOL_KEYS)
 ]);
+function filterFacets(catalog) {
+  const models = catalog?.list() ?? [];
+  const distinct = (pick) => [...new Set(models.map(pick).filter((v) => !!v))].sort();
+  const facets = [
+    { key: "type", category: "what it is", label: "Type", values: distinct((m) => m.type), numeric: false, bare: false },
+    { key: "provider", category: "what it is", label: "Provider", values: distinct((m) => m.provider), numeric: false, bare: false },
+    // The named cutoffs the parser compares against, plus `free` for exactly zero.
+    { key: "price", category: "cost", label: "Price", values: ["free", "low", "mid", "high"], numeric: true, bare: false },
+    // filled below from the models themselves — tiers are per model, not a fixed set
+    { key: "tier", category: "cost", label: "Billing tier", values: [], numeric: false, bare: false },
+    { key: "context", category: "inputs", label: "Context window", values: ["small", "large"], numeric: true, bare: false },
+    { key: "reasoning", category: "thinking", label: "Reasoning", values: ["yes", "no"], numeric: false, bare: true },
+    { key: "status", category: "availability", label: "Status", values: distinct((m) => m.status), numeric: false, bare: false },
+    { key: "active", category: "availability", label: "Offered now", values: ["yes", "no"], numeric: false, bare: true }
+  ];
+  for (const key of Object.keys(CAP_KEYS)) {
+    facets.push({ key, category: "inputs", label: key, values: ["yes", "no"], numeric: false, bare: true });
+  }
+  for (const key of Object.keys(BUILTIN_TOOL_KEYS)) {
+    facets.push({ key, category: "hosted tools", label: key.replace(/_/g, " "), values: ["yes", "no"], numeric: false, bare: true });
+  }
+  const tiers = [...new Set(models.flatMap((m) => Object.keys(m.pricing?.tiers ?? {})))].sort();
+  const tierFacet = facets.find((f) => f.key === "tier");
+  if (tierFacet) tierFacet.values = tiers;
+  return facets;
+}
+function filterAliases() {
+  return { ...DEFAULT_TAGS };
+}
 function parseNum(v) {
   const m = /^([\d.]+)\s*([kKmM]?)$/.exec(v.trim());
   if (!m) return Number.NaN;
@@ -54791,6 +55144,7 @@ function select(query, opts = {}) {
 function createRealtime(opts) {
   const engine = opts.engine ?? coreRegistry.get();
   const { provider, model } = resolveModel(opts.model, opts.provider, "createRealtime");
+  const sendModel = engine.catalog.resolveModelId(provider, model);
   const apiKey = opts.apiKey ?? engine.apiKeys[provider];
   if (!apiKey) {
     throw new Error(
@@ -54800,11 +55154,11 @@ function createRealtime(opts) {
   const adapter = resolveAdapter2(provider, apiKey);
   const voice = resolveVoice(provider, opts.audio?.voice ?? opts.voice);
   const session = adapter.connect(
-    { model, modalities: opts.modalities, voice, instructions: opts.instructions },
+    { model: sendModel, modalities: opts.modalities, voice, instructions: opts.instructions },
     engine.connect
   );
   session.on("usage", (e) => {
-    void engine.hooks.emit("onCompletion", realtimeCompletionContext(provider, model, e.usage)).catch(() => {
+    void engine.hooks.emit("onCompletion", realtimeCompletionContext(provider, sendModel, e.usage)).catch(() => {
     });
   });
   return session;
@@ -57175,6 +57529,8 @@ export {
   exchangeCode,
   extractLastUserText,
   extractSystemText,
+  filterAliases,
+  filterFacets,
   finalAnswerText,
   finishMcpAuth,
   formatBulletedList,