@juspay/neurolink 10.3.0 → 10.4.0

package/dist/types/knowledge.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Knowledge grounding — lexical-first host-supplied knowledge retrieval.
+ *
+ * A host application owns a structured *knowledge registry*: versioned entries
+ * describing concepts, configuration, taxonomies, procedures, and operating
+ * rules. NeuroLink owns the
+ * generic engine that ingests that registry, builds an in-memory lexical
+ * index once per instance, and — independently of tool routing — retrieves a
+ * small, token-bounded set of relevant entries before each main model call.
+ * The selected entries are attached as *ephemeral context*: visible to the
+ * current generation call, never persisted into conversation memory.
+ *
+ * This is retrieval-augmented generation WITHOUT vector retrieval. The first
+ * release ranks with exact identifiers, reviewed aliases, metadata filters,
+ * and weighted field-aware BM25 only. No embedding model, embedding service,
+ * or vector store is initialized. An LLM reranker and semantic retrieval are
+ * deferred behind an explicit evaluation gate.
+ *
+ * Ownership boundary: NeuroLink defines the contracts below and the engine;
+ * it never contains host product content. The host supplies content and
+ * per-request scope. The engine stays provider-neutral.
+ *
+ * Type names are globally prefixed `Knowledge*` to satisfy the repo's
+ * unique-type-name rule and to avoid collision with the pre-existing
+ * web-search `grounding.ts` vocabulary (`EnhancedGroundingMetadata` et al.),
+ * which is a different concept (Google search grounding, not product
+ * knowledge).
+ */
+/** What a knowledge entry primarily is. Drives context labelling, not ranking. */
+export type KnowledgeEntryKind = "concept" | "text" | "configuration" | "tool" | "procedure" | "policy" | "troubleshooting";
+/** Lifecycle state. Only `active` entries are retrievable by default. */
+export type KnowledgeStatus = "draft" | "active" | "deprecated";
+/**
+ * Retrieval mode. Only `"lexical"` is supported in the first release; the
+ * literal is a union of one to reserve a clean upgrade path to `"hybrid"` /
+ * `"vector"` without a breaking change.
+ */
+export type KnowledgeRetrievalMode = "lexical";
+/**
+ * Confidence class returned with every retrieval so the host prompt can
+ * instruct the model to qualify low-confidence answers rather than present
+ * them as authoritative.
+ */
+export type KnowledgeRetrievalConfidence = "high" | "medium" | "low" | "none";
+/** The five weighted text fields used by the field-aware lexical scorer. */
+export type KnowledgeFieldName = "title" | "aliases" | "keywords" | "summary" | "body";
+/**
+ * The record a host author writes. `id`, `title`, `summary`, `domain`, and
+ * `integrations` are required; every other field is optional and omitted
+ * optionals fall back to SDK defaults during normalization.
+ */
+export type KnowledgeEntryInput = {
+    /** Stable unique id (e.g. "account.multi-step-flow"). Drives exact-match lookup and citations. */
+    id: string;
+    /** Human-readable name of the concept/setting. Highest-weighted search field. */
+    title: string;
+    /** One-line searchable description — the short answer when a full body is unnecessary. */
+    summary: string;
+    /** Primary grouping and the main retrieval filter (e.g. "account-settings"). */
+    domain: string;
+    /** Integration identifiers this entry applies to. Empty array = applies to all integrations. */
+    integrations: string[];
+    /** What the entry is (concept, configuration, procedure, …). Default "text". Labels context, not ranking. */
+    kind?: KnowledgeEntryKind;
+    /** Lifecycle state. Default "active"; only active entries are retrievable. */
+    status?: KnowledgeStatus;
+    /** Full explanatory content (Markdown). Use only when the summary is insufficient. */
+    body?: string;
+    /** Reviewed alternate phrasings or raw identifiers that resolve to exact and alias matches. */
+    aliases?: string[];
+    /** Extra search terms that aid recall but are not full aliases. */
+    keywords?: string[];
+    /** Ids of directly related entries, pulled in by bounded relationship expansion. */
+    relatedEntryIds?: string[];
+    /** Id of the parent entry when this is a subtype or child. */
+    parentEntryId?: string;
+};
+/**
+ * The complete, defaults-resolved record NeuroLink indexes and injects. Omitted
+ * optionals are materialized (arrays to `[]`, `body` to `""`, `kind` to "text",
+ * `status` to "active") so downstream code never re-checks the resolution chain.
+ * Field meanings mirror `KnowledgeEntryInput`.
+ */
+export type NormalizedKnowledgeEntry = {
+    id: string;
+    title: string;
+    summary: string;
+    domain: string;
+    integrations: string[];
+    kind: KnowledgeEntryKind;
+    status: KnowledgeStatus;
+    body: string;
+    aliases: string[];
+    keywords: string[];
+    relatedEntryIds: string[];
+    parentEntryId?: string;
+    /** Content version from the source/manifest; appears in citations as [KB:id@version]. */
+    version: string;
+};
+/** One catalog inside a build manifest — a source id and its entries. */
+export type KnowledgeManifestCatalog = {
+    id: string;
+    entries: KnowledgeEntryInput[];
+};
+/**
+ * The versioned build artifact a host emits at build time. NeuroLink can
+ * consume it directly (each catalog becomes a structured source) so hosts do
+ * not need to construct `KnowledgeSource[]` by hand.
+ */
+export type KnowledgeManifest = {
+    schemaVersion: string;
+    contentVersion: string;
+    generatedAt: string;
+    catalogs: KnowledgeManifestCatalog[];
+};
+/**
+ * A configured knowledge source: inline structured entries passed to the
+ * engine. Markdown/provider source kinds were intentionally dropped for now;
+ * re-introduce this as a discriminated union (with a `type` tag) if another
+ * source kind is needed later.
+ */
+export type KnowledgeSource = {
+    id: string;
+    version?: string;
+    entries: KnowledgeEntryInput[];
+};
+/**
+ * Relative weight applied to a lexical match in each field. Title/alias
+ * matches outrank body matches. Tunable through evaluation.
+ */
+export type KnowledgeFieldWeights = {
+    title: number;
+    aliases: number;
+    keywords: number;
+    summary: number;
+    body: number;
+};
+/** Lexical retrieval tuning. All fields optional; the engine supplies defaults. */
+export type KnowledgeRetrievalConfig = {
+    /** Retrieval mode. Default: "lexical". */
+    mode?: KnowledgeRetrievalMode;
+    /** How many scored candidates enter relationship expansion. Default: 24. */
+    candidateLimit?: number;
+    /** How many primary entries survive into the assembled context. Default: 8. */
+    resultLimit?: number;
+    /** Cap on relationship-expanded entries added after primary retrieval. Default: 4. */
+    relationLimit?: number;
+    /** Per-field BM25 weights. */
+    fieldWeights?: KnowledgeFieldWeights;
+    /** Additive boost for an exact entry-id / configuration-key match. Dominant. Default: 100. */
+    exactBoost?: number;
+    /** Additive boost for an exact reviewed-alias phrase match. Default: 60. */
+    aliasBoost?: number;
+};
+/** Ephemeral-context assembly limits. */
+export type KnowledgeContextConfig = {
+    /** Hard token budget for the assembled grounding block. Default: 4000. */
+    maxTokens?: number;
+    /** Emit `[KB:<id>@<version>]` citations. Default: true. */
+    includeCitations?: boolean;
+};
+/**
+ * Constructor-level configuration for knowledge grounding. Sources are fixed
+ * for the lifetime of a NeuroLink instance so the index can be built once.
+ */
+export type KnowledgeGroundingConfig = {
+    /** Master switch. Grounding runs only when true AND at least one source is loaded. */
+    enabled: boolean;
+    /**
+     * Knowledge sources used to build the instance's immutable in-memory index.
+     * Required alongside `enabled`; pass an empty array only when intentionally
+     * configuring no retrievable content.
+     */
+    sources: KnowledgeSource[];
+    /** Exclude these domains from retrieval. Empty/omitted means all domains are eligible. */
+    blockedDomains?: string[];
+    retrieval?: KnowledgeRetrievalConfig;
+    context?: KnowledgeContextConfig;
+    /** Hard ceiling for one grounding operation before it fails open. Default: 800ms. */
+    timeoutMs?: number;
+};
+/**
+ * Per-call scope the host attaches to `GenerateOptions` / `StreamOptions`.
+ * Supplies the enabled integrations for this turn only.
+ */
+export type KnowledgeRequestScope = {
+    /** Installed/enabled integrations used to filter integration-specific entries. */
+    enabledIntegrations?: string[];
+};
+/** One bounded recent conversation turn used to contextualize the query. */
+export type KnowledgeConversationTurn = {
+    role: "user" | "assistant";
+    text: string;
+};
+/**
+ * The fully-resolved retrieval request the engine builds internally from the
+ * user query, a bounded recent window, and host scope.
+ */
+export type KnowledgeRetrievalRequest = {
+    query: string;
+    recentTurns: KnowledgeConversationTurn[];
+    enabledIntegrations: string[];
+};
+/**
+ * The internal search document built from a normalized entry. `exactKeys` and
+ * `fields` hold pre-tokenized normalized text. Internal to NeuroLink.
+ */
+export type IndexedKnowledgeDocument = {
+    id: string;
+    /** Normalized whole-phrase keys for exact/alias resolution. */
+    exactKeys: string[];
+    /** Per-field normalized token arrays fed to the field-aware BM25 scorer. */
+    fields: {
+        title: string[];
+        aliases: string[];
+        keywords: string[];
+        summary: string[];
+        body: string[];
+    };
+};
+/** One lexical match with its per-field score breakdown, for tuning and traces. */
+export type KnowledgeLexicalMatch = {
+    id: string;
+    score: number;
+    fieldScores: Partial<Record<KnowledgeFieldName, number>>;
+};
+/**
+ * Structural contract of the field-aware lexical index held in a snapshot. A
+ * concrete class in the knowledge runtime module satisfies this shape; typing
+ * it structurally keeps this types file free of runtime imports.
+ */
+export type KnowledgeLexicalSearcher = {
+    search: (queryTokens: string[], topK: number, eligibleEntryIds?: ReadonlySet<string>) => KnowledgeLexicalMatch[];
+};
+/**
+ * Immutable, ready-to-query index built once at client construction. Sessions
+ * and turns search this snapshot; it is never mutated in place.
+ */
+export type KnowledgeIndexSnapshot = {
+    entriesById: Map<string, NormalizedKnowledgeEntry>;
+    /** Normalized entry id or title phrase -> entry ids. */
+    exactIndex: Map<string, Set<string>>;
+    /** Normalized reviewed alias phrase -> entry ids. */
+    aliasIndex: Map<string, Set<string>>;
+    /** Entry id -> directly related entry ids, for bounded expansion. */
+    relationIndex: Map<string, string[]>;
+    /** Field-aware BM25 over all documents. */
+    lexical: KnowledgeLexicalSearcher;
+    entryCount: number;
+};
+/** A stable citation to a specific knowledge entry version. */
+export type KnowledgeCitation = {
+    id: string;
+    version: string;
+};
+/**
+ * The result of one retrieval: the selected entries, the assembled ephemeral
+ * context string, a confidence class, and assembly diagnostics.
+ */
+export type KnowledgeRetrievalResult = {
+    entries: NormalizedKnowledgeEntry[];
+    assembledContext: string;
+    confidence: KnowledgeRetrievalConfidence;
+    citations: KnowledgeCitation[];
+    /** Ids of the primary (non-expanded) entries, in final order. */
+    selectedEntryIds: string[];
+    /** Ids added by bounded relationship expansion. */
+    expandedEntryIds: string[];
+    /** Candidates scored before truncation to the result limit. */
+    candidateCount: number;
+    /** Estimated token size of `assembledContext`. */
+    contextTokens: number;
+    /** True when any entry body was truncated or entries were dropped for budget. */
+    truncated: boolean;
+    durationMs: number;
+};
+/**
+ * A block of context assembled for a single generation call without becoming
+ * durable conversation. The NeuroLink call boundary injects its content into
+ * the effective system prompt and never persists it as a user message.
+ */
+export type EphemeralContext = {
+    content: string;
+    kind: "knowledge";
+    /** Host-supplied reviewed content is trusted reference data. */
+    trusted: boolean;
+    citations?: KnowledgeCitation[];
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Aggregate, content-free diagnostics attached to a generation/stream result
+ * so the host can evaluate retrieval without the SDK exposing entry bodies.
+ */
+export type KnowledgeGroundingMetadata = {
+    retrievalMode: KnowledgeRetrievalMode;
+    selectedIds: string[];
+    expandedIds: string[];
+    candidateCount: number;
+    contextTokens: number;
+    truncated: boolean;
+    durationMs: number;
+    confidence?: KnowledgeRetrievalConfidence;
+    /** Present when grounding failed open; names the failure class. */
+    failureReason?: string;
+};
+/** A single validation problem found while normalizing/indexing a source. */
+export type KnowledgeValidationIssue = {
+    level: "error" | "warning";
+    code: string;
+    message: string;
+    entryId?: string;
+    sourceId?: string;
+};
+/** Outcome of validating a set of sources before indexing. */
+export type KnowledgeValidationResult = {
+    ok: boolean;
+    issues: KnowledgeValidationIssue[];
+};
+/** Per-turn input to `KnowledgeGroundingEngine.ground()`. */
+export type KnowledgeGroundingInput = {
+    query: string;
+    recentTurns?: KnowledgeConversationTurn[];
+    scope?: KnowledgeRequestScope;
+};
+/**
+ * The engine's per-turn output: the ephemeral context to inject (null on
+ * no-match, when disabled, or on fail-open), the aggregate metadata for the
+ * result, and the full retrieval for host diagnostics.
+ */
+export type KnowledgeGroundingOutcome = {
+    ephemeralContext: EphemeralContext | null;
+    metadata: KnowledgeGroundingMetadata;
+    retrieval: KnowledgeRetrievalResult | null;
+};
+/** Snapshot of engine health for telemetry and host introspection. */
+export type KnowledgeEngineStatus = {
+    enabled: boolean;
+    ready: boolean;
+    entryCount: number;
+    lastError: string | null;
+    validationIssues: KnowledgeValidationIssue[];
+};

package/dist/types/knowledge.js

@@ -0,0 +1,29 @@
+/**
+ * Knowledge grounding — lexical-first host-supplied knowledge retrieval.
+ *
+ * A host application owns a structured *knowledge registry*: versioned entries
+ * describing concepts, configuration, taxonomies, procedures, and operating
+ * rules. NeuroLink owns the
+ * generic engine that ingests that registry, builds an in-memory lexical
+ * index once per instance, and — independently of tool routing — retrieves a
+ * small, token-bounded set of relevant entries before each main model call.
+ * The selected entries are attached as *ephemeral context*: visible to the
+ * current generation call, never persisted into conversation memory.
+ *
+ * This is retrieval-augmented generation WITHOUT vector retrieval. The first
+ * release ranks with exact identifiers, reviewed aliases, metadata filters,
+ * and weighted field-aware BM25 only. No embedding model, embedding service,
+ * or vector store is initialized. An LLM reranker and semantic retrieval are
+ * deferred behind an explicit evaluation gate.
+ *
+ * Ownership boundary: NeuroLink defines the contracts below and the engine;
+ * it never contains host product content. The host supplies content and
+ * per-request scope. The engine stays provider-neutral.
+ *
+ * Type names are globally prefixed `Knowledge*` to satisfy the repo's
+ * unique-type-name rule and to avoid collision with the pre-existing
+ * web-search `grounding.ts` vocabulary (`EnhancedGroundingMetadata` et al.),
+ * which is a different concept (Google search grounding, not product
+ * knowledge).
+ */
+export {};

package/dist/types/openaiCompatible.d.ts

@@ -226,6 +226,8 @@ export type StreamLoopArgs = {
     openAITools: OpenAICompatChatTool[] | undefined;
     openAIToolChoice: OpenAICompatToolChoiceWire | undefined;
     toolsRecord: Record<string, Tool>;
+    /** Wire → registered tool-name map when sanitization was needed (see buildWireToolNameMaps). */
+    toolNameFromWire?: Map<string, string>;
     emitter: TypedEventEmitter<NeuroLinkEvents> | undefined;
     toolsUsed: string[];
     toolExecutionSummaries: ToolExecutionSummaryInternal[];

package/dist/types/providers.d.ts

@@ -601,6 +601,15 @@ export type AIProvider = {
      * external AIProvider implementations — callers treat absence as `true`.
      */
     supportsTools?(): boolean;
+    /**
+     * Ensure runtime-discovered model limits (context window, output-token
+     * ceiling) are registered before budget math runs. Implemented by
+     * BaseProvider (default no-op); providers with a discovery source override
+     * it (LiteLLM `/model/info`). Must never reject — discovery failure
+     * degrades to static defaults. Optional for compile compatibility with
+     * external AIProvider implementations — callers treat absence as no-op.
+     */
+    ensureModelLimits?(): Promise<void>;
 };
 /**
  * Provider attempt result for iteration tracking (converted from interface)

package/dist/types/stream.d.ts

@@ -1,6 +1,7 @@
 import type { AIProviderName } from "../constants/enums.js";
 import type { EvaluationData } from "./evaluation.js";
 import type { RAGConfig } from "./rag.js";
+import type { KnowledgeGroundingMetadata, KnowledgeRequestScope } from "./knowledge.js";
 import type { SkillsCallOptions } from "./skills.js";
 import type { AnalyticsData, ToolExecutionEvent, ToolExecutionSummary } from "../types/index.js";
 import type { MiddlewareFactoryOptions, OnChunkCallback, OnErrorCallback, OnFinishCallback } from "../types/middleware.js";
@@ -169,6 +170,17 @@ export type StreamChunk = {
     audio: TTSChunk;
 };
 export type StreamOptions = {
+    /**
+     * Opt this stream call into the knowledge grounding configured on the
+     * NeuroLink instance. Defaults to `false` when omitted.
+     */
+    useKnowledgeGrounding?: boolean;
+    /**
+     * Enabled integrations used to scope knowledge retrieval for this turn.
+     * Used only when `useKnowledgeGrounding` is true and knowledge grounding is
+     * enabled on the NeuroLink instance.
+     */
+    knowledgeContext?: KnowledgeRequestScope;
     input: {
         /** Prompt text. Optional for media-only modes (avatar, music) that are driven by uploaded files rather than a prompt. */
         text?: string;
@@ -552,6 +564,8 @@ export type StreamOptions = {
  * Future-ready for multi-modal outputs while maintaining text focus
  */
 export type StreamResult = {
+    /** Knowledge-grounding diagnostics for this turn (present only when grounding ran). */
+    knowledge?: KnowledgeGroundingMetadata;
     stream: AsyncIterable<{
         content: string;
         reasoning?: string;

package/dist/utils/errorHandling.js

@@ -1012,12 +1012,18 @@ export class ErrorFactory {
  * Timeout wrapper for async operations
  */
 export async function withTimeout(promise, timeoutMs, timeoutError) {
+    let timer;
     const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => {
+        timer = setTimeout(() => {
             reject(timeoutError || new Error(`Operation timed out after ${timeoutMs}ms`));
         }, timeoutMs);
     });
-    return Promise.race([promise, timeoutPromise]);
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
 }
 /**
  * Retry mechanism for retriable operations

package/dist/utils/schemaConversion.d.ts

@@ -29,6 +29,22 @@ export declare function ensureNestedSchemaTypes(schema: Record<string, unknown>)
  */
 export declare function convertZodToJsonSchema(zodSchema: ZodUnknownSchema, target?: "jsonSchema7" | "openApi3"): object;
 export declare function normalizeJsonSchemaObject(schema: Record<string, unknown> | undefined | null): Record<string, unknown>;
+/**
+ * Normalize a JSON Schema for the OpenAI chat-completions `tools` wire
+ * block. Generic proxied backends (LiteLLM → vllm/GLM/Qwen, local servers)
+ * render tool schemas into chat templates more or less verbatim, so `$ref`
+ * indirection, `$defs` containers, `$schema` annotations, and zod's
+ * nullable `anyOf` pattern all measurably degrade argument generation —
+ * this is the parity gap behind "the model can't find the right arguments"
+ * on litellm while the same tools work on Gemini/Claude native paths
+ * (which sanitize schemas before the wire).
+ *
+ * Pipeline: strip annotation keys → inline local `$ref`/`$defs`/
+ * `definitions` → collapse nullable variants → guarantee a top-level object
+ * shape. Identity for already-clean schemas; `description`, `required`,
+ * `enum`, and `default` — what models actually read — are always preserved.
+ */
+export declare function normalizeWireToolSchema(schema: unknown): Record<string, unknown>;
 /**
  * Check if a value is a Zod schema
  */

package/dist/utils/schemaConversion.js

@@ -80,9 +80,11 @@ function safePercentDecode(segment) {
  * - Circular reference detection to prevent infinite loops
  */
 export function inlineJsonSchema(schema, definitions, visited = new Set(), rootSchema) {
-    // Use definitions from schema if not provided
+    // Use definitions from schema if not provided. Modern MCP servers and
+    // zod v4's native toJSONSchema emit the 2020-12 `$defs` keyword; older
+    // emitters use draft-07 `definitions`. Support both.
     const defs = definitions ||
-        schema.definitions;
+        (schema.definitions ?? schema.$defs);
     // Keep track of the root schema for deep ref resolution
     const root = rootSchema || schema;
     // Handle $ref at current level
@@ -94,10 +96,14 @@ export function inlineJsonSchema(schema, definitions, visited = new Set(), rootS
             // Return a simple object placeholder for circular refs
             return { type: "object" };
         }
-        // Try simple definition lookup first (for #/definitions/SomeName)
-        if (refPath.startsWith("#/definitions/")) {
-            const defName = refPath.replace("#/definitions/", "");
-            // Check if it's a simple definition name (no slashes after definitions/)
+        // Try simple definition lookup first (#/definitions/SomeName or the
+        // 2020-12 #/$defs/SomeName form)
+        if (refPath.startsWith("#/definitions/") ||
+            refPath.startsWith("#/$defs/")) {
+            const defName = refPath
+                .replace("#/definitions/", "")
+                .replace("#/$defs/", "");
+            // Check if it's a simple definition name (no slashes after the prefix)
             if (!defName.includes("/") && defs && defs[defName]) {
                 visited.add(refPath);
                 const resolved = inlineJsonSchema({ ...defs[defName] }, defs, visited, root);
@@ -124,8 +130,8 @@ export function inlineJsonSchema(schema, definitions, visited = new Set(), rootS
     // Create result without $ref and definitions
     const result = {};
     for (const [key, value] of Object.entries(schema)) {
-        // Skip $ref and definitions keys
-        if (key === "$ref" || key === "definitions") {
+        // Skip $ref and definition-container keys (both draft-07 and 2020-12)
+        if (key === "$ref" || key === "definitions" || key === "$defs") {
             continue;
         }
         // Recursively process nested schemas
@@ -402,6 +408,157 @@ function ensureTypeField(schema) {
     }
     return schema;
 }
+/** JSON Schema keys whose values are themselves schemas (single). */
+const SCHEMA_VALUE_KEYS = new Set([
+    "items",
+    "additionalProperties",
+    "not",
+    "if",
+    "then",
+    "else",
+    "contains",
+    "propertyNames",
+]);
+/** JSON Schema keys whose values are arrays of schemas. */
+const SCHEMA_ARRAY_KEYS = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+/** JSON Schema keys whose values are name → schema maps. */
+const SCHEMA_MAP_KEYS = new Set([
+    "properties",
+    "patternProperties",
+    "$defs",
+    "definitions",
+]);
+/**
+ * Annotation keys that carry no validation semantics for a model and that
+ * generic OpenAI-compatible backends (vllm, GLM/Qwen chat templates, local
+ * servers) may render into the prompt verbatim, confusing argument
+ * generation. Removed only at SCHEMA positions — never inside data values
+ * like `default`, `const`, `enum` or `examples`, where `$id` etc. are
+ * legitimate payload.
+ */
+const SCHEMA_ANNOTATION_KEYS = new Set(["$schema", "$id", "$comment"]);
+/** Walk schema positions only, dropping annotation-only keys. */
+function stripSchemaAnnotations(schema) {
+    const result = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (SCHEMA_ANNOTATION_KEYS.has(key)) {
+            continue;
+        }
+        if (SCHEMA_VALUE_KEYS.has(key) &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            result[key] = stripSchemaAnnotations(value);
+        }
+        else if (SCHEMA_ARRAY_KEYS.has(key) && Array.isArray(value)) {
+            result[key] = value.map((item) => item && typeof item === "object" && !Array.isArray(item)
+                ? stripSchemaAnnotations(item)
+                : item);
+        }
+        else if (SCHEMA_MAP_KEYS.has(key) &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            const map = {};
+            for (const [name, sub] of Object.entries(value)) {
+                map[name] =
+                    sub && typeof sub === "object" && !Array.isArray(sub)
+                        ? stripSchemaAnnotations(sub)
+                        : sub;
+            }
+            result[key] = map;
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Collapse the zod-emitted nullable pattern `anyOf/oneOf: [T, {type:"null"}]`
+ * into `{...T, type: [t, "null"]}`. Weaker OSS models handle a plain type
+ * array far better than composition keywords when choosing tool arguments.
+ * Conservative: only fires for exactly-two variants where the non-null
+ * variant has a primitive `type` string — everything else passes through.
+ */
+function collapseNullableVariants(schema) {
+    const result = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (SCHEMA_VALUE_KEYS.has(key) &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            result[key] = collapseNullableVariants(value);
+        }
+        else if (SCHEMA_ARRAY_KEYS.has(key) && Array.isArray(value)) {
+            result[key] = value.map((item) => item && typeof item === "object" && !Array.isArray(item)
+                ? collapseNullableVariants(item)
+                : item);
+        }
+        else if (SCHEMA_MAP_KEYS.has(key) &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            const map = {};
+            for (const [name, sub] of Object.entries(value)) {
+                map[name] =
+                    sub && typeof sub === "object" && !Array.isArray(sub)
+                        ? collapseNullableVariants(sub)
+                        : sub;
+            }
+            result[key] = map;
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    for (const compositionKey of ["anyOf", "oneOf"]) {
+        const variants = result[compositionKey];
+        if (!Array.isArray(variants) || variants.length !== 2) {
+            continue;
+        }
+        const isNullVariant = (v) => !!v &&
+            typeof v === "object" &&
+            v.type === "null";
+        const nullIndex = variants.findIndex(isNullVariant);
+        if (nullIndex === -1) {
+            continue;
+        }
+        const other = variants[1 - nullIndex];
+        if (!other ||
+            typeof other !== "object" ||
+            Array.isArray(other) ||
+            typeof other.type !== "string" ||
+            other.type === "null") {
+            continue;
+        }
+        // Merge: variant content + outer annotations (description etc.) win.
+        const { [compositionKey]: _dropped, ...outer } = result;
+        return { ...other, ...outer, type: [other.type, "null"] };
+    }
+    return result;
+}
+/**
+ * Normalize a JSON Schema for the OpenAI chat-completions `tools` wire
+ * block. Generic proxied backends (LiteLLM → vllm/GLM/Qwen, local servers)
+ * render tool schemas into chat templates more or less verbatim, so `$ref`
+ * indirection, `$defs` containers, `$schema` annotations, and zod's
+ * nullable `anyOf` pattern all measurably degrade argument generation —
+ * this is the parity gap behind "the model can't find the right arguments"
+ * on litellm while the same tools work on Gemini/Claude native paths
+ * (which sanitize schemas before the wire).
+ *
+ * Pipeline: strip annotation keys → inline local `$ref`/`$defs`/
+ * `definitions` → collapse nullable variants → guarantee a top-level object
+ * shape. Identity for already-clean schemas; `description`, `required`,
+ * `enum`, and `default` — what models actually read — are always preserved.
+ */
+export function normalizeWireToolSchema(schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        return { type: "object", properties: {} };
+    }
+    return ensureTypeField(collapseNullableVariants(inlineJsonSchema(stripSchemaAnnotations(schema))));
+}
 /**
  * Check if a value is a Zod schema
  */