@sayknow-cli/ai 0.4.2 → 0.4.3

package/dist/types/utils/schema/compatibility.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Schema compatibility audits.
+ *
+ * Each provider has a different idea of what JSON Schema features it accepts
+ * for tool definitions. The normalizers in `normalize.ts`, `strict-mode`,
+ * and `adapt.ts` rewrite incoming schemas to fit. This module is the
+ * *audit* counterpart: it walks a (presumably already-sanitized) schema and
+ * reports any feature the target provider would reject. Tests use it to lock
+ * down the contract; the runtime uses it to fail-open with diagnostic logs
+ * rather than silently shipping a broken tool definition.
+ */
+export type SchemaCompatibilityProvider = "openai-strict" | "google" | "cloud-code-assist-claude";
+export interface SchemaCompatibilityViolation {
+    path: string;
+    rule: string;
+    message: string;
+    key?: string;
+    value?: unknown;
+}
+export interface SchemaCompatibilityResult {
+    provider: SchemaCompatibilityProvider;
+    compatible: boolean;
+    violations: SchemaCompatibilityViolation[];
+}
+export interface StrictSchemaEnforcementResult {
+    schema: Record<string, unknown>;
+    strict: boolean;
+}
+export declare function validateSchemaCompatibility(schema: unknown, provider: SchemaCompatibilityProvider): SchemaCompatibilityResult;
+export declare function validateStrictSchemaEnforcement(originalSchema: Record<string, unknown>, result: StrictSchemaEnforcementResult): SchemaCompatibilityResult;

package/dist/types/utils/schema/dereference.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Dereference all local `$ref` pointers in a JSON Schema, inlining definitions
+ * from `$defs` / `definitions`. The `$defs` block is stripped from the output.
+ *
+ * Non-local refs (e.g. `http://...`) are left untouched.
+ * Circular references are broken with `{}`.
+ *
+ * @returns A new schema object with all local refs inlined, or the input unchanged
+ *          if it's not an object or has no `$defs`/`definitions`.
+ */
+export declare function dereferenceJsonSchema(schema: unknown): unknown;

package/dist/types/utils/schema/draft.d.ts

@@ -0,0 +1,10 @@
+export declare const JSON_SCHEMA_DRAFT_2020_12_URI = "https://json-schema.org/draft/2020-12/schema";
+/** Pre-check entrypoint. Exposed so callers can decide whether to take the upgrade path at all. */
+export declare function schemaNeedsDraft202012Upgrade(schema: unknown): boolean;
+/**
+ * Upgrade legacy JSON Schema shapes to the draft 2020-12 form emitted by Zod.
+ *
+ * This keeps extension/MCP/TypeBox schemas compatible with providers whose tool
+ * validators reject draft-07 tuple and dependency keywords.
+ */
+export declare function upgradeJsonSchemaTo202012(schema: unknown): unknown;

package/dist/types/utils/schema/equality.d.ts

@@ -0,0 +1,4 @@
+import type { JsonObject } from "./types";
+export declare function areJsonValuesEqual(left: unknown, right: unknown): boolean;
+export declare function mergeCompatibleEnumSchemas(existing: unknown, incoming: unknown): JsonObject | null;
+export declare function mergePropertySchemas(existing: unknown, incoming: unknown): unknown;

package/dist/types/utils/schema/fields.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Field classification sets for JSON Schema sanitization across providers.
+ *
+ * Each set serves a different provider need. They overlap intentionally —
+ * co-locating them makes the overlap visible and maintainable.
+ *
+ * All keysets here are static and small (≤ ~40 entries) so they live as
+ * `Record<string, true>` literals — `k in REC` resolves through hidden
+ * class inline caches without the per-call hashtable cost of `Set.has`.
+ */
+/**
+ * Google Generative AI unsupported schema fields.
+ * Stripped during normalizeSchemaForGoogle / normalizeSchemaForCCA.
+ */
+export declare const UNSUPPORTED_SCHEMA_FIELDS: Record<string, true>;
+/**
+ * Human-meaningful validation/decorative keywords that can be preserved in a
+ * sibling description when a provider-specific normalizer strips them from the
+ * wire schema.
+ */
+export declare const LIFTABLE_TO_DESCRIPTION_FIELDS: Record<string, true>;
+/**
+ * Non-structural schema keys stripped during OpenAI strict mode sanitization.
+ * These are decorative/validation-only keywords that don't affect the structural
+ * shape OpenAI's strict mode enforces.
+ */
+export declare const NON_STRUCTURAL_SCHEMA_KEYS: Record<string, true>;
+/**
+ * Cloud Code Assist type-specific allowed keys per JSON Schema type.
+ * Used when collapsing mixed-type combiner variants for CCA Anthropic model.
+ */
+export declare const CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS: Record<string, Record<string, true>>;
+/**
+ * Cloud Code Assist shared schema keys allowed on any type.
+ * Used alongside CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS for CCA combiner collapsing.
+ */
+export declare const CLOUD_CODE_ASSIST_SHARED_SCHEMA_KEYS: Record<string, true>;
+/**
+ * Combinator keys used across schema sanitization modules.
+ * Defined once to avoid duplication in strict-mode.ts and normalize.ts.
+ */
+export declare const COMBINATOR_KEYS: readonly ["anyOf", "allOf", "oneOf"];
+/**
+ * Cloud Code Assist Anthropic model unsupported schema fields.
+ * Much smaller than UNSUPPORTED_SCHEMA_FIELDS (Google) because CCA supports
+ * validation keywords like additionalProperties, minLength, pattern, etc.
+ * Meta/reference keywords plus object-key validators that CCA cannot resolve are stripped.
+ */
+export declare const CCA_UNSUPPORTED_SCHEMA_FIELDS: Record<string, true>;

package/dist/types/utils/schema/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./adapt";
+export * from "./compatibility";
+export * from "./dereference";
+export * from "./draft";
+export * from "./equality";
+export * from "./fields";
+export * from "./json-schema-validator";
+export * from "./meta-validator";
+export * from "./normalize";
+export * from "./root-combinator";
+export * from "./spill";
+export * from "./types";
+export * from "./wire";
+export * from "./zod-decontaminate";

package/dist/types/utils/schema/json-schema-validator.d.ts

@@ -0,0 +1,12 @@
+export interface JsonSchemaValidationIssue {
+    path: PropertyKey[];
+    message: string;
+    expectedTypes?: string[];
+    keyword?: string;
+}
+export interface JsonSchemaValidationResult {
+    success: boolean;
+    issues: JsonSchemaValidationIssue[];
+}
+export declare function validateJsonSchemaValue(schema: unknown, value: unknown): JsonSchemaValidationResult;
+export declare function isJsonSchemaValueValid(schema: unknown, value: unknown): boolean;

package/dist/types/utils/schema/meta-validator.d.ts

@@ -0,0 +1,2 @@
+/** Validate that `schema` is structurally a valid JSON Schema (subset). */
+export declare function isValidJsonSchema(schema: unknown): boolean;

package/dist/types/utils/schema/normalize.d.ts

@@ -0,0 +1,93 @@
+import { type DescriptionSpillFormat } from "./spill";
+import { type JsonObject } from "./types";
+export type ResidualSchemaIncompatibility = "type-array" | "type-null" | "nullable" | "combiners";
+export interface NormalizeSchemaOptions {
+    unsupportedFields: (key: string) => boolean;
+    normalizeFieldNames: boolean;
+    collapseNullFields: boolean;
+    normalizeTypeArrayToNullable: boolean;
+    stripNullableKeyword: boolean;
+    autoPropertyOrdering: boolean;
+    ensureObjectProperties: boolean;
+    liftStrippedToDescription: false | {
+        keys?: (key: string) => boolean;
+        format?: DescriptionSpillFormat;
+    };
+    mergeObjectCombiners: boolean;
+    collapseSameTypeCombiners: boolean;
+    collapseMixedTypeCombiners: boolean;
+    stripResidualCombinersFixpoint: boolean;
+    extractNullableFromUnions: boolean;
+    rejectResidualIncompatibilities?: ReadonlyArray<ResidualSchemaIncompatibility>;
+    validateAndFallback?: {
+        fallback: unknown;
+    };
+}
+/** Copy all keys from a schema except the specified combiner key. */
+export declare function copySchemaWithout(schema: JsonObject, combiner: string): JsonObject;
+/**
+ * Recursively strip any remaining anyOf/oneOf that same-type or mixed-type
+ * collapse can handle. This is needed because object-combiner merging can
+ * create new anyOf in merged subtrees after child normalization already ran.
+ */
+export declare function stripResidualCombiners(value: unknown, epoch?: number): unknown;
+export declare function normalizeSchema(value: unknown, options: NormalizeSchemaOptions): unknown;
+export declare function normalizeSchemaForGoogle(value: unknown): unknown;
+export declare function normalizeSchemaForCCA(value: unknown): unknown;
+export declare function normalizeSchemaForMCP(value: unknown): unknown;
+/**
+ * OpenAI Responses rejects `oneOf` in tool schemas even when strict mode is
+ * disabled, and rejects every schema node with `type: "object"` unless it has
+ * a `properties` member. Normalize only schema-valued positions so literal
+ * payloads under `enum`, `const`, `default`, and `examples` remain unchanged.
+ *
+ * Identity-preserving: returns the input reference unchanged when no rewrite
+ * occurred so callers can dedupe via reference equality (and the strict-mode
+ * cache stays warm). If a node has both `oneOf` and `anyOf`, the two are
+ * concatenated (the wire payload accepts a single union; preserving both
+ * would not survive).
+ */
+export declare function sanitizeSchemaForOpenAIResponses(schema: JsonObject): JsonObject;
+/**
+ * Alias for {@link sanitizeSchemaForOpenAIResponses} matching the
+ * `normalizeSchemaFor*` dispatcher naming used elsewhere in this module.
+ */
+export declare const normalizeSchemaForOpenAIResponses: (schema: JsonObject) => JsonObject;
+/**
+ * First pass of strict-mode preparation.
+ *
+ * Rewrites everything strict mode forbids into something it accepts:
+ *  - Drops non-structural keywords (`format`, `pattern`, `examples`, …),
+ *    `const`, `nullable`, and `additionalProperties` (re-added by
+ *    `enforceStrictSchema` as `false`).
+ *  - `type: [a, b]` → `anyOf: [{type: a, …}, {type: b, …}]`, copying only the
+ *    keywords each variant can use (e.g. `properties` stays only on the
+ *    object variant).
+ *  - `const` → single-entry `enum`.
+ *  - Description carries a `(default: X)` suffix so the model still sees the
+ *    documented default after the keyword is stripped.
+ *  - `nullable: true` wraps the whole node in `anyOf:[T,{type:"null"}]`.
+ *
+ * Recurses into properties, items, prefixItems, combinators, and $defs. The
+ * `cache` WeakMap dedupes shared subgraphs; the `epoch` is the cycle guard.
+ */
+export declare function sanitizeSchemaForStrictMode(schema: Record<string, unknown>, epoch?: number, cache?: WeakMap<Record<string, unknown>, Record<string, unknown>>, root?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Recursively enforces JSON Schema constraints required by OpenAI/OpenAI code backend strict mode:
+ *   - `additionalProperties: false` on every object node
+ *   - every key in `properties` present in `required`
+ *
+ * Properties absent from the original `required` array were TypeBox-optional.
+ * They are made nullable (`anyOf: [T, { type: "null" }]`) so the model can
+ * signal omission by outputting null rather than omitting the key entirely.
+ *
+ * @throws {Error} When a schema node has no `type`, array-based combinator
+ *   (`anyOf`/`allOf`/`oneOf`), object-based combinator (`not`), or `$ref` —
+ *   i.e. the node is not representable in strict mode. Prefer
+ *   {@link tryEnforceStrictSchema} which catches this and degrades gracefully.
+ */
+export declare function enforceStrictSchema(schema: Record<string, unknown>, cache?: WeakMap<Record<string, unknown>, Record<string, unknown>>): Record<string, unknown>;
+export declare function tryEnforceStrictSchema(schema: Record<string, unknown>): {
+    schema: Record<string, unknown>;
+    strict: boolean;
+};

package/dist/types/utils/schema/root-combinator.d.ts

@@ -0,0 +1,12 @@
+/** True when a JSON Schema node describes an object (explicit `type` or `properties`). */
+export declare function isJsonSchemaObjectNode(schema: Record<string, unknown>): boolean;
+/**
+ * Flatten a provider-emitted tool ROOT whose top level is a `oneOf`/`anyOf`/`allOf`
+ * combinator into one `type: "object"` schema: merge object-branch properties,
+ * derive the discriminant (`action`) enum, keep the common required set, and demote
+ * leftover combinators plus per-branch guidance into the description. Nested
+ * combinators (inside individual properties) are left untouched.
+ *
+ * Idempotent: a root that already lacks top-level combinators is returned unchanged.
+ */
+export declare function flattenToolRootCombinators(schema: Record<string, unknown>): Record<string, unknown>;

package/dist/types/utils/schema/spill.d.ts

@@ -0,0 +1,8 @@
+import type { JsonObject } from "./types";
+export type DescriptionSpillFormat = "spill" | "paren";
+/**
+ * Demote stripped JSON Schema keywords into a node's `description` so the model
+ * still receives the constraint as natural-language context after the wire
+ * schema drops it.
+ */
+export declare function spillToDescription(node: JsonObject, entries: ReadonlyArray<readonly [string, unknown]>, format?: DescriptionSpillFormat): void;

package/dist/types/utils/schema/stamps.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Symbol-keyed lazy memoization stamped directly onto the host object.
+ *
+ * Faster than a module-level `WeakMap` in V8/JSC because the symbol slot is
+ * resolved through the object's hidden class instead of a side-table hash
+ * lookup. The slot is defined as a non-enumerable property so the stamp
+ * does not leak through `{...spread}`, `Object.keys`, `JSON.stringify`, or
+ * `toEqual`-style deep equality.
+ *
+ * Caveats: the stamp lives as long as the host object, even after callers
+ * release their references to the cached value — only use this for caches
+ * whose lifetime should match the host. Frozen hosts will throw on write in
+ * strict mode; callers that may receive frozen input must handle that.
+ */
+export declare function stamp<T extends object, V>(target: T, key: symbol, compute: (target: T) => V): V;
+export declare function epochNext(): number;
+/**
+ * Marks `target` as visited for this `epoch`. Returns `true` the first time
+ * it is called for a given (target, epoch) pair and `false` on every
+ * subsequent call within the same epoch.
+ */
+export declare function once<T extends object>(target: T, epoch: number): boolean;
+/** Returns `true` on first entry, `false` if `target` is already on the current path. */
+export declare function enter<T extends object>(target: T): boolean;
+export declare function exit<T extends object>(target: T): void;

package/dist/types/utils/schema/types.d.ts

@@ -0,0 +1,4 @@
+export type JsonObject = Record<string, unknown>;
+export declare function isJsonObject(value: unknown): value is JsonObject;
+/** True when `value` is a plain JSON object with no own enumerable keys. */
+export declare function isJsonObjectEmpty(value: JsonObject): boolean;

package/dist/types/utils/schema/wire.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Compute the wire (JSON Schema) representation of a tool's parameters and
+ * convert TypeBox-style schemas into Zod for internal validation.
+ *
+ * Tools may author parameters in two shapes:
+ *   1. Zod (canonical going forward) — converted to JSON Schema on demand.
+ *   2. TypeBox / plain JSON Schema (legacy + extension compat) — upgraded to
+ *      draft 2020-12 without converting through Zod.
+ *
+ * Both are normalized at the boundary so providers and validators see the same
+ * JSON Schema dialect.
+ */
+import { type ZodType } from "zod/v4";
+import type { Tool } from "../../types";
+/**
+ * True when `value` is a live Zod schema instance.
+ *
+ * The check is stricter than "has a `_zod` property" because a JSON
+ * round-trip preserves the `_zod` key as a plain object and would otherwise
+ * fool the predicate — see issue #1101, where MCP servers ship
+ * `JSON.stringify(zodSchemaInstance)` as a tool's `inputSchema` and the
+ * resulting plain object then explodes `z.toJSONSchema` because the prototype
+ * (and every Zod parsing method) is gone.
+ *
+ * Live Zod instances always carry a `.parse` function on the prototype;
+ * impostors do not.
+ */
+export declare function isZodSchema(value: unknown): value is ZodType;
+/**
+ * Normalize `{}` (empty JSON Schema = `z.unknown()` / unconstrained value) to
+ * boolean `true` in every schema-valued position. JSON Schema draft 2020-12
+ * §4.3.1: `{}` and `true` are semantically equivalent ("any JSON value").
+ * Grammar-constrained samplers (llama.cpp, etc.) treat the object form as
+ * "generate an empty object" rather than "any JSON value", causing open-typed
+ * fields like `extra.title` (from `z.record(z.string(), z.unknown())`) to
+ * always emit `{}` instead of the intended string/number/etc. (issue #1179).
+ *
+ * Mutates in place. Provider-agnostic — applied to every tool wire schema so
+ * Anthropic, Google, OpenAI, Ollama, Bedrock, and Cursor all see the
+ * normalized form, regardless of whether the source was Zod or TypeBox.
+ */
+export declare function normalizeEmptySchemas(node: unknown): void;
+/** Convert a Zod schema into the JSON Schema shape providers consume. */
+export declare function zodToWireSchema(schema: ZodType): Record<string, unknown>;
+/**
+ * Resolve a tool's parameters to a JSON Schema object suitable for sending
+ * over the wire. Zod schemas are converted (and cached); legacy TypeBox / raw
+ * JSON Schema parameters are upgraded to draft 2020-12 (and cached).
+ *
+ * Both branches finish with `normalizeEmptySchemas` so every provider —
+ * OpenAI, Anthropic, Google, Ollama, Bedrock, Cursor — sees `{}` normalized
+ * to `true` in schema-valued positions (issue #1179).
+ */
+export declare function toolWireSchema(tool: Tool): Record<string, unknown>;

package/dist/types/utils/schema/zod-decontaminate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Defensive rewrite for nodes that look like `JSON.stringify(zodSchemaInstance)`
+ * output rather than JSON Schema. MCP servers using Zod 4 sometimes ship a
+ * serialised schema instance directly as a tool's `inputSchema`, because the
+ * fields Zod surfaces on its instances (`type`, `enum`, `options`, `def`) shadow
+ * (and clash with) JSON Schema keywords. The resulting payload is neither valid
+ * Zod nor valid JSON Schema 2020-12 and Anthropic's strict validator rejects
+ * the whole tool list.
+ *
+ * Symptoms we've observed (gitnexus_impact.direction):
+ *   {
+ *     def:   { type: "enum", entries: { upstream: "upstream", ... } },
+ *     type:  "enum",                       // <- invalid `type` value
+ *     enum:  { upstream: "upstream", ... }, // <- `enum` MUST be an array
+ *     options: ["upstream", "downstream"],
+ *   }
+ *
+ * This module recognises the shape (`def.type === node.type` and `def.type` is
+ * a known Zod kind) and rewrites it to clean JSON Schema where deterministic.
+ * For Zod kinds we don't fully model, we strip the toxic siblings (`def`,
+ * `options`, object-shaped `enum`) and drop an invalid `type` so the remainder
+ * passes meta-schema validation as a permissive node.
+ *
+ * Pure / identity-preserving: returns the input reference when nothing changes.
+ */
+/**
+ * Walks a JSON value and rewrites every Zod-instance-shaped node into clean
+ * JSON Schema 2020-12. Identity-preserving when no rewrite fires. Tolerates
+ * self-referential graphs — a revisited node returns as-is.
+ */
+export declare function decontaminateZodInstance(value: unknown): unknown;

package/dist/types/utils/sse-debug.d.ts

@@ -0,0 +1,10 @@
+import type { ServerSentEvent } from "@sayknow-cli/utils";
+import type { RawSseEvent } from "../types";
+type FetchFunction = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+type FetchWithPreconnect = FetchFunction & {
+    preconnect?: typeof fetch.preconnect;
+};
+type RawSseObserver = (event: RawSseEvent) => void;
+export declare function notifyRawSseEvent(observer: RawSseObserver | undefined, event: ServerSentEvent | RawSseEvent): void;
+export declare function wrapFetchForSseDebug(fetchImpl: FetchWithPreconnect, observer: RawSseObserver | undefined): FetchWithPreconnect;
+export {};

package/dist/types/utils/tool-call-healing.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Streaming-safe filter for the Kimi K2 chat-template "tool-call section"
+ * grammar.
+ *
+ * Some providers hosting Kimi K2 (the native `kimi-code` API, OpenRouter,
+ * Fireworks, and others) leak the raw chat-template special tokens into
+ * `delta.content` instead of emitting structured `tool_calls`. Visually
+ * that looks like:
+ *
+ *     <|tool_calls_section_begin|>
+ *       <|tool_call_begin|>functions.read:0<|tool_call_argument_begin|>{"path":"foo"}<|tool_call_end|>
+ *     <|tool_calls_section_end|>
+ *
+ * Without healing, the user sees the raw markers and the agent loop never
+ * sees a tool call. This module reconstructs the embedded calls and strips
+ * the markers from visible text. It is stream-aware: any partial token at
+ * the end of a chunk is held back until the next chunk arrives.
+ */
+export interface HealedToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: string;
+}
+/**
+ * State machine that consumes streamed text, emits visible text with all
+ * Kimi tool-call markers stripped, and accumulates the embedded tool calls
+ * for the caller to drain after each `feed()`.
+ *
+ * One instance per stream. Feed only the channel that may carry leaked
+ * markers (typically `delta.content`); mixing reasoning + content into the
+ * same accumulator corrupts the holdback buffer if both channels race in
+ * the same chunk.
+ */
+export declare class ToolCallHealer {
+    #private;
+    /**
+     * Feed a chunk of streamed text. Returns the portion safe to emit
+     * downstream (with all tokens stripped). Any partial token suffix is
+     * held back until the next chunk arrives or {@link flushPending} is
+     * called.
+     */
+    feed(text: string): string;
+    /**
+     * Like {@link feed}, but discards any tool calls that the chunk completes.
+     * Used when the upstream provider also emits structured `delta.tool_calls`
+     * for the same chunk: the healer still strips leaked marker text from the
+     * visible output, but the structured payload remains the single source of
+     * truth for the call list.
+     */
+    consumeWithoutCalls(text: string): string;
+    /**
+     * Drain accumulated tool calls. The internal list is cleared so a
+     * subsequent section in the same stream (rare) yields fresh calls.
+     */
+    drainCompleted(): HealedToolCall[];
+    /**
+     * Flush any held-back fragment when the stream ends. If we were mid-call
+     * the partial is dropped (emitting raw token bytes would surface markers
+     * to the user); otherwise the fragment is returned verbatim so a literal
+     * `<|` in prose is not silently lost.
+     */
+    flushPending(): string;
+    /** True once any tool-call section in this stream has fully closed. */
+    get sectionClosed(): boolean;
+}
+/**
+ * Cheap test for whether a given model is known to leak Kimi-K2 chat-template
+ * tool-call tokens into visible text. Used to gate the per-stream healer so
+ * non-Kimi providers do not pay for the scan.
+ */
+export declare function modelMayLeakKimiToolCalls(provider: string, modelId: string): boolean;

package/dist/types/utils/tool-choice-capability.d.ts

@@ -0,0 +1,41 @@
+import type { Api, Model, ToolChoice, ToolChoiceCompat, ToolChoiceSupport, ToolChoiceSupportSource } from "../types";
+/**
+ * Claude Mythos accepts tools but rejects forced tool use (Anthropic 400:
+ * "tool_choice forces tool use is not compatible with this model"). Catalog
+ * generation and dynamic discovery use this to default `toolChoiceSupport`.
+ */
+export declare function isClaudeForcedToolChoiceIncapableModelId(modelId: string): boolean;
+/** Derives the effective static tool-choice support from compatibility flags. */
+export declare function deriveToolChoiceSupport(compat: ToolChoiceCompat | undefined): {
+    support: ToolChoiceSupport;
+    source: "static" | "derived";
+};
+/** Returns the registry key used for runtime tool-choice capability overrides. */
+export declare function toolChoiceRegistryKey(model: Model<Api>): string;
+/** Returns the current runtime tool-choice capability override for a model. */
+export declare function getToolChoiceCapabilityOverride(model: Model<Api>): ToolChoiceSupport | undefined;
+/** Clears runtime tool-choice capability overrides for tests. */
+export declare function clearToolChoiceIncapabilityRegistryForTests(): void;
+/** Records a discovered maximum supported tool-choice level for a model. */
+export declare function markToolChoiceIncapability(model: Model<Api>, maxSupport: ToolChoiceSupport, reason?: string): void;
+/**
+ * Resolves a requested tool_choice against static and runtime capability limits.
+ * `compat` overrides `model.compat` for transports that layer URL/provider
+ * detection on top of explicit model overrides (e.g. resolveOpenAICompat).
+ */
+export declare function resolveToolChoice(model: Model<Api>, requested: ToolChoice | undefined, compat?: ToolChoiceCompat): ResolveToolChoiceResult;
+/** Detects provider errors indicating forced tool_choice is unsupported. */
+export declare function isForcedToolChoiceUnsupportedError(error: unknown, sentForcedToolChoice: boolean): boolean;
+export type { ToolChoiceCompat, ToolChoiceSupport, ToolChoiceSupportSource } from "../types";
+export interface ResolveToolChoiceResult {
+    requestedChoice: ToolChoice | undefined;
+    requestedLevel: ToolChoiceSupport;
+    resolvedChoice: ToolChoice | undefined;
+    resolvedLevel: ToolChoiceSupport;
+    support: ToolChoiceSupport;
+    supportSource: ToolChoiceSupportSource;
+    degraded: boolean;
+    reason?: string;
+    registryKey: string;
+    targetToolName?: string;
+}

package/dist/types/utils/tool-choice.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Utility functions for mapping unified ToolChoice to provider-specific formats.
+ */
+import type { ToolChoice } from "../types";
+/** OpenAI Completions API tool choice format */
+export type OpenAICompletionsToolChoice = "auto" | "none" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+} | undefined;
+/** OpenAI Responses API tool choice format (flat structure) */
+export type OpenAIResponsesToolChoice = "auto" | "none" | "required" | {
+    type: "function";
+    name: string;
+} | {
+    type: "custom";
+    name: string;
+} | undefined;
+/** Anthropic-compatible tool choice format */
+export type AnthropicToolChoice = "auto" | "none" | "any" | {
+    type: "tool";
+    name: string;
+} | undefined;
+/**
+ * Map unified ToolChoice to OpenAI Completions API format.
+ * - "any" → "required"
+ * - { type: "tool", name } → { type: "function", function: { name } }
+ */
+export declare function mapToOpenAICompletionsToolChoice(choice?: ToolChoice): OpenAICompletionsToolChoice;
+/**
+ * Returns true when an OpenAI-completions `tool_choice` value forces a tool
+ * call (`"required"` or a function-name pin), as opposed to leaving it open
+ * (`"auto"`, `"none"`, or unset). Accepts `unknown` because the param shape
+ * pulled from the OpenAI SDK (`ChatCompletionToolChoiceOption`) widens with
+ * each release; this check only needs the open/forced bit.
+ */
+export declare function isForcedToolChoice(choice: unknown): boolean;
+/**
+ * Map unified ToolChoice to OpenAI Responses API format.
+ * - "any" → "required"
+ * - { type: "tool", name } → { type: "function", name } (flat structure)
+ */
+export declare function mapToOpenAIResponsesToolChoice(choice?: ToolChoice): OpenAIResponsesToolChoice;
+/**
+ * Map unified ToolChoice to Anthropic-compatible format.
+ * - "required" → "any"
+ * - { type: "function", ... } → { type: "tool", name }
+ */
+export declare function mapToAnthropicToolChoice(choice?: ToolChoice): AnthropicToolChoice;

package/dist/types/utils/validation.d.ts

@@ -0,0 +1,17 @@
+import type { Tool, ToolCall } from "../types";
+/**
+ * Finds a tool by name and validates the tool call arguments against its schema.
+ * @param tools Array of tool definitions
+ * @param toolCall The tool call from the LLM
+ * @returns The validated arguments
+ * @throws Error if tool is not found or validation fails
+ */
+export declare function validateToolCall(tools: Tool[], toolCall: ToolCall): ToolCall["arguments"];
+/**
+ * Validates tool call arguments against the tool's schema (Zod or plain JSON
+ * Schema). Applies LLM-quirk coercions (numeric strings, JSON-string
+ * containers, null-for-optional, null-for-default) before declaring failure.
+ *
+ * @throws Error with a formatted message when validation cannot be reconciled.
+ */
+export declare function validateToolArguments(tool: Tool, toolCall: ToolCall): ToolCall["arguments"];