@aryee337/aery-ai 0.1.148 → 0.2.10

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 Claude.
+ */
+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 Claude 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,13 @@
+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 "./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/Codex 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/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,53 @@
+/**
+ * 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).
+ *
+ * Zod schemas also receive Zod-artifact cleanup; both branches normalize
+ * schema-valued positions and nullable scalar unions.
+ */
+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/sdk-stream-timeout.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared helpers for mapping `StreamOptions.streamFirstEventTimeoutMs` onto
+ * underlying SDK request-timeout options.
+ *
+ * The hint is intentionally not a watchdog — it just narrows the SDK's
+ * "transport timeout" window so a stuck pre-stream request fails fast
+ * instead of hanging on the default (often multi-minute) SDK timeout. Once
+ * the stream actually starts, silence is not failure; callers must abort
+ * to interrupt a quiet stream.
+ */
+/**
+ * Coerce a caller-supplied `streamFirstEventTimeoutMs` into a positive integer suitable
+ * for the SDK's `timeout` option. Returns `undefined` when the caller passed nothing,
+ * a non-finite value, or a non-positive value (preserving the SDK's default).
+ */
+export declare function resolveSdkTimeoutMs(streamFirstEventTimeoutMs: number | undefined): number | undefined;
+/**
+ * Build per-request SDK options that combine an abort signal with the optional
+ * `streamFirstEventTimeoutMs` request-timeout hint.
+ *
+ * The returned `{ signal, timeout?, maxRetries? }` shape is compatible with both
+ * OpenAI's and Anthropic's `RequestOptions` (and any other SDK that follows the
+ * Stainless conventions), so callers from any of those providers can spread the
+ * result directly into `client.X.create(params, requestOptions)`.
+ *
+ * When the hint is set, retries are forced to zero so the SDK does not silently
+ * extend the caller's explicit deadline by re-attempting after a timeout.
+ */
+export declare function createSdkStreamRequestOptions(signal: AbortSignal, streamFirstEventTimeoutMs: number | undefined): {
+    signal: AbortSignal;
+    timeout?: number;
+    maxRetries?: number;
+};

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

@@ -0,0 +1,10 @@
+import type { ServerSentEvent } from "@aryee337/aery-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/stream-markup-healing.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Streaming-safe filters for leaked chat-template tool-call and thinking markup.
+ *
+ * Hosted models sometimes leak raw template markup into visible `content` instead
+ * of returning structured events. One `StreamMarkupHealing` instance owns one stream
+ * and one grammar selected by options:
+ *
+ * - `kimi`: Kimi K2 `<|tool_calls_section_begin|>` sections.
+ * - `dsml`: DeepSeek `<｜DSML｜tool_calls>` envelopes.
+ * - `thinking`: plain `<think>` / `<thinking>` blocks used by MiniMax-style streams.
+ *
+ * The parser strips marker bytes, reconstructs embedded calls, emits thinking
+ * deltas for thinking blocks, and holds partial tags across chunk boundaries.
+ */
+export interface HealedToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: string;
+}
+export type StreamMarkupHealingPattern = "kimi" | "dsml" | "thinking";
+export interface StreamMarkupHealingOptions {
+    readonly pattern: StreamMarkupHealingPattern;
+}
+export type StreamMarkupHealingEvent = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "thinking";
+    readonly thinking: string;
+} | {
+    readonly type: "toolCall";
+    readonly call: HealedToolCall;
+};
+/**
+ * State machine that consumes streamed visible text and emits cleaned text,
+ * thinking deltas, and reconstructed tool calls.
+ *
+ * Feed only one stream channel (usually `delta.content` / `message.content`).
+ * Mixing reasoning and visible text into the same instance can corrupt the
+ * held-back partial tag buffer.
+ */
+export declare class StreamMarkupHealing {
+    #private;
+    constructor(options: StreamMarkupHealingOptions);
+    get pattern(): StreamMarkupHealingPattern;
+    /**
+     * Feed a chunk and return visible text only. Reconstructed tool calls are
+     * stored for {@link drainCompleted}; thinking blocks are intentionally not
+     * returned by this compatibility helper. Use {@link feedEvents} when the
+     * caller needs ordered text/thinking/tool-call events.
+     */
+    feed(text: string): string;
+    /** Feed a chunk and return cleaned text/thinking/tool-call events in stream order. */
+    feedEvents(text: string): StreamMarkupHealingEvent[];
+    /**
+     * Like {@link feed}, but discards completed calls. Used when the upstream
+     * chunk also carries structured `tool_calls`, keeping that structured payload
+     * as the single source of truth.
+     */
+    consumeWithoutCalls(text: string): string;
+    /** Drain accumulated tool calls from calls to {@link feed}. */
+    drainCompleted(): HealedToolCall[];
+    /**
+     * Flush held-back stream-end fragments as ordered events. Partial tool-call
+     * sections/envelopes are dropped; unterminated thinking blocks are emitted as
+     * thinking, matching the previous MiniMax parser behavior.
+     */
+    flushEvents(): StreamMarkupHealingEvent[];
+    /** Flush held-back text only. Reconstructed calls are retained for {@link drainCompleted}. */
+    flushPending(): string;
+    /** True once any configured tool-call section/envelope has fully closed. */
+    get sectionClosed(): boolean;
+}
+/** Cheap model/provider gate for Kimi-K2 chat-template token leaks. */
+export declare function modelMayLeakKimiToolCalls(provider: string, modelId: string): boolean;
+/** Cheap model/provider gate for DeepSeek DSML envelope leaks. */
+export declare function modelMayLeakDsmlToolCalls(provider: string, modelId: string): boolean;
+export declare function getStreamMarkupHealingPattern(provider: string, modelId: string, options?: {
+    readonly parseThinkingTags?: boolean;
+}): StreamMarkupHealingPattern | undefined;

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"];

package/dist/types/utils.d.ts

@@ -0,0 +1,28 @@
+import type { ResponseInput } from "openai/resources/responses/responses";
+import type { CacheRetention, OpenAIResponsesHistoryPayload, ProviderPayload } from "./types";
+export { isRecord } from "@aryee337/aery-utils";
+export declare function normalizeSystemPrompts(systemPrompt: readonly string[] | string | undefined | null): string[];
+export declare function toNumber(value: unknown): number | undefined;
+export declare function toPositiveNumber(value: unknown, fallback: number): number;
+export declare function toBoolean(value: unknown): boolean | undefined;
+export declare function normalizeToolCallId(id: string): string;
+type ResponsesToolItemIdPrefix = "fc" | "ctc";
+export declare function normalizeResponsesToolCallId(id: string, itemPrefix?: ResponsesToolItemIdPrefix): {
+    callId: string;
+    itemId: string;
+};
+/**
+ * Truncate an OpenAI Responses API item ID to 64 characters.
+ * IDs exceeding the limit are replaced with a hash-based ID using the given prefix.
+ */
+export declare function truncateResponseItemId(id: string, prefix: string): string;
+export declare function sanitizeOpenAIResponsesHistoryItemsForReplay(items: Array<Record<string, unknown>>): ResponseInput;
+export declare function createOpenAIResponsesHistoryPayload(provider: string, items: Array<Record<string, unknown>>, incremental?: boolean): OpenAIResponsesHistoryPayload;
+export declare function getOpenAIResponsesHistoryPayload(providerPayload: ProviderPayload | undefined, currentProvider: string, fallbackProvider?: string): OpenAIResponsesHistoryPayload | undefined;
+export declare function getOpenAIResponsesHistoryItems(providerPayload: ProviderPayload | undefined, currentProvider: string, fallbackProvider?: string): Array<Record<string, unknown>> | undefined;
+/**
+ * Resolve cache retention preference.
+ * Defaults to "short" and uses PI_CACHE_RETENTION for backward compatibility.
+ */
+export declare function resolveCacheRetention(cacheRetention?: CacheRetention): CacheRetention;
+export declare function isAnthropicOAuthToken(key: string): boolean;