@combycode/llm-sdk 3.0.0 → 3.1.0

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/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/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.1.0",
   "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",