@combycode/llm-sdk 3.0.0 → 3.2.1

package/dist/llm/client.d.ts

@@ -85,6 +85,9 @@ export declare class LLMClient {
      *  files piped straight to a file / GridFS / HTTP response without buffering. */
     streamFile(file: FileOutput): Promise<FileStream>;
     /** 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. */
+    private reportBuildNotes;
     complete(input: string | ContentPart[] | Message[], options?: ExecuteOptions): Promise<CompletionResponse>;
     /** Run `complete` with a JSON Schema enforced via `structured`. Strips any
      *  leading/trailing markdown fences from the model reply, then JSON.parses

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/provider.d.ts

@@ -24,6 +24,11 @@ export interface ProviderHttpRequest {
     /** Override of the default completion path. Used by providers that route
      *  per-API or per-modality. */
     path?: string;
+    /** What the build deliberately left out, and why — a hosted tool this provider
+     *  refuses to run beside the attached content, for instance. The client emits
+     *  each as `onWarning`, because dropping a capability the caller asked for and
+     *  saying nothing is how a missing feature gets mistaken for a working one. */
+    notes?: string[];
 }
 export interface ProviderAdapter {
     readonly name: ProviderName;

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/dist/wire/interpreter.d.ts

@@ -53,6 +53,13 @@ export type Cond = {
 /** Array at `path` contains `value`. */
  | {
     includes: [string, Json];
+}
+/** The request carries a message content part of one of these types
+ *  (`image` | `audio` | `video` | `document` | `text`). Needed because the
+ *  parts are nested two levels deep — `messages[].content[].type` — which
+ *  `includes` cannot reach. */
+ | {
+    hasPartType: string[];
 } | {
     not: Cond;
 } | {
@@ -93,10 +100,37 @@ export interface BlockRule {
     /** Named cross-field effects run after the block is written. */
     effects?: string[];
 }
+/** A hosted tool this provider refuses to run alongside certain content.
+ *
+ *  Providers reject some combinations outright: Google answers 400 "The mime
+ *  type: video/mp4 is not supported for code execution" when `code_interpreter`
+ *  is sent with a PDF or a video. The caller cannot be expected to know that, and
+ *  the error names a mime type rather than the tool, so it reads as a problem
+ *  with the attachment.
+ *
+ *  Declared here as data rather than as a provider `if` in the builder: it is one
+ *  more fact about how this API behaves, and the four other providers stay
+ *  untouched because their specs simply do not carry the field.
+ *
+ *  A matched constraint DROPS the tool — `hasTool` reports it absent, so the
+ *  spec's existing `$when` guard omits it with no further edit — and records
+ *  `why` on the built request so the runtime can say what it did. Dropping
+ *  quietly would trade a confusing error for a silent loss of a capability the
+ *  caller asked for, which is worse. */
+export interface ToolConstraint {
+    /** Builtin tool type, e.g. `code_interpreter`. */
+    tool: string;
+    /** When this holds, the tool cannot be sent. */
+    conflictsWith: Cond;
+    /** Said to the caller, verbatim. */
+    why: string;
+}
 export interface WireSpec {
     id: string;
     provider: string;
     api: string;
+    /** Tool/content combinations this provider rejects. See `ToolConstraint`. */
+    toolConstraints?: ToolConstraint[];
     /** Adapter flavor, for specs shared by several providers (openai|xai|openrouter). */
     flavors?: string[];
     envelope?: {
@@ -216,6 +250,8 @@ export interface Ctx {
     };
     /** Collected multipart fields, when the spec declares a multipart body. */
     multipart?: MultipartField[];
+    /** What the build decided to leave out, and why — surfaced to the caller. */
+    notes?: string[];
 }
 export interface MultipartField {
     name: string;
@@ -237,6 +273,10 @@ export declare function evalCond(cond: Cond | undefined, ctx: Ctx, reg: Registry
 export declare function resolveVariants(spec: WireSpec, model: string, reg: Registry): Set<string>;
 export interface BuiltRequest {
     body: Record<string, unknown>;
+    /** Anything the spec deliberately left out, and why — e.g. a hosted tool this
+     *  provider will not run beside the attached content. The runtime turns these
+     *  into `onWarning`; they are never silent. */
+    notes?: string[];
     headers?: Record<string, string>;
     path?: string;
     url?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "3.0.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",