@vib-rato/ai 0.16.0

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 "@vib-rato/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,80 @@
+/**
+ * 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.
+ */
+import { type UnicodeEscapeEvidence } from "./json-parse";
+export interface HealedToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: string;
+    /**
+     * Whether the raw leaked payload carried unsafe Unicode argument data.
+     * Captured before the normalizing round-trip below, which would otherwise
+     * erase malformed escape evidence. Valid `\uXXXX` spellings decode
+     * canonically and leave this false.
+     */
+    readonly escapedNonAsciiArguments: boolean;
+    readonly escapedUnicodeArgumentEvidence?: UnicodeEscapeEvidence;
+}
+/**
+ * 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,57 @@
+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;
+/** Overrides durable-cache dependencies for isolated tests. */
+export declare function configureToolChoiceCapabilityCacheForTests(options?: {
+    path?: string;
+    now?: () => number;
+    beforeExpiredDelete?: () => void;
+    beforeMalformedDelete?: () => void;
+    onCacheOpen?: () => void;
+    simulateOperationError?: () => Error | undefined;
+    beforeCorruptRetire?: () => void;
+    beforeLockExactUnlink?: (lockPath: string) => void;
+}): 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;
+/**
+ * Detects Codex's statusless SSE rejection for a named function tool choice.
+ * This is intentionally separate from the shared HTTP-400 classifier.
+ */
+export declare function isCodexStatuslessNamedToolChoiceNotFoundError(error: unknown, forcedToolName: string | undefined, sentToolNames: readonly string[]): 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"];

package/dist/types/utils.d.ts

@@ -0,0 +1,117 @@
+import type { ResponseInput } from "openai/resources/responses/responses";
+import type { CacheRetention, OpenAIResponsesHistoryPayload, ProviderPayload } from "./types";
+export { isRecord } from "@vib-rato/utils";
+export declare function normalizeSystemPrompts(systemPrompt: readonly string[] | string | undefined | null): string[];
+export declare function sanitizeJsonStrings(value: unknown): unknown;
+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;
+/**
+ * Neutralize leaked OpenAI Harmony / control tokens (`<|channel|>`, `<|message|>`,
+ * `<|call|>`, `<|constrain|>`, `<|recipient|>`, `<|content|>`, ...) in replayed
+ * history text. A subagent whose tool-call channel degenerates can dump raw
+ * control-token scaffolding into its reply text; once that poisoned text lands in
+ * history the Codex / Responses endpoint rejects every subsequent request with
+ * `Request blocked (code=invalid_prompt)`, permanently wedging the session because
+ * the offending item is re-sent on each turn. Insert a zero-width space after `<`
+ * so the delimiter can no longer be tokenized as a reserved control token while the
+ * text stays human-readable.
+ *
+ * The pattern matches the two control-token shapes only, so ordinary text and pipe
+ * syntax is left untouched:
+ *   - simple form `<|ident|>` — a leading run of identifier chars then `|>`; and
+ *   - header form `<|role to=recipient|>` — a known Harmony role
+ *     (`system`/`developer`/`user`/`assistant`/`tool`) followed by a single
+ *     recipient assignment `to=<recipient>` whose value is an unbounded run of
+ *     non-delimiter, non-whitespace chars (so long MCP/custom tool recipients like
+ *     `to=functions.<long.name>` are covered).
+ * The header branch is deliberately scoped to the known role + `to=` recipient
+ * grammar rather than an arbitrary `key=value`, so request-boundary sanitization
+ * never rewrites non-control delimiter text such as `<|foo bar=baz|>`. A single-line
+ * body (no `\n`) and the required leading identifier char also leave compact
+ * pipe/operator syntax alone — e.g. F# `value <| f |> g` (space after `<|`),
+ * `sum<|a+b|>c` (punctuation body), and `<|foo bar|>` (no assignment) never match.
+ * The simple branch is a strict superset of the original identifier-only pattern:
+ * every marker the old regex caught still matches.
+ */
+export declare function neutralizeReservedControlTokens(text: string): string;
+/**
+ * Shape-tolerant classifier for the poisoned-history rejection that wedges
+ * gpt-5.6 sessions: `Request blocked (code=invalid_prompt)`. Accepts a raw
+ * provider error, an assistant message, or any object carrying a
+ * `providerCode` / `transportFailure` / `errorMessage` field, and returns true
+ * when the failure is the deterministic `invalid_prompt` content fault rather
+ * than a transient upstream error. This is the single shared contract the
+ * provider transports and the session-level circuit breaker key on so the
+ * classification is explicit (not inferred from a catch-all bucket) and
+ * uniformly testable across transports.
+ */
+export declare function isInvalidPromptError(input: unknown): boolean;
+/**
+ * Shape-tolerant classifier for the DeepSeek-family reasoning-content replay
+ * rejection: "The `reasoning_content` in the thinking mode must be passed back
+ * to the API." DeepSeek V4 (and reasoning-capable siblings reached through any
+ * OpenAI-compatible proxy) 400 every follow-up turn once a prior assistant turn
+ * carried reasoning the proxy stripped to an empty `encrypted_content` /
+ * `reasoning_content`. Resending the identical history re-triggers it, so naive
+ * session auto-retry just burns the budget — it needs the same bounded
+ * repair-and-resend contract as the `invalid_prompt` poisoned-history breaker.
+ *
+ * Accepts a raw provider error, an assistant message, or any object carrying an
+ * `errorMessage` field (the agent-loop circuit breaker keys on this).
+ */
+export declare function isReasoningContentReplayError(input: unknown): boolean;
+/**
+ * Remove Responses-API `reasoning` items whose `encrypted_content` is missing or
+ * empty from an outgoing history payload. DeepSeek rejects replay of reasoning
+ * whose encrypted blob a proxy stripped to `""`; dropping those items lets the
+ * model re-reason on the next turn instead of re-triggering a deterministic 400.
+ * Non-reasoning items (text, function_call, function_call_output, ...) are kept
+ * verbatim so tool-use pairing and message order are preserved. Returns whether
+ * any item was actually removed — the circuit breaker uses this to decide
+ * between a single repaired resend (removed) and immediate fail-fast (unchanged).
+ */
+export declare function stripUnusableReasoningItems(items: Array<Record<string, unknown>>): {
+    result: Array<Record<string, unknown>>;
+    removed: number;
+};
+/**
+ * Neutralize leaked reserved control tokens across every string in an outgoing
+ * Responses `input` array. This is the request-boundary complement to the
+ * replay-history sanitizer: leaked Harmony markers (`<|channel|>analysis`, ...)
+ * can enter the payload from assistant reasoning summaries, live-converted
+ * message/tool-output text, or user-authored content — not just replayed
+ * history — and every gpt-5.6 request that carries one is rejected with
+ * `Request blocked (code=invalid_prompt)`. Walking every string (rather than an
+ * item-type allowlist) guarantees no leak source is missed as item shapes
+ * evolve; the zero-width-space insertion is idempotent (`<\u200b|` no longer
+ * matches `<|`) and keeps the text human-readable.
+ */
+export declare function neutralizeResponsesInputControlTokens<T>(items: readonly T[]): T[];
+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.
+ *
+ * Resolution order: explicit request value → `VIB_CACHE_RETENTION` →
+ * legacy `PI_CACHE_RETENTION` → `fallback`. Both env vars act as explicit
+ * opt-in (`"long"`) or opt-out (any other value) so a provider-specific
+ * `fallback` only applies when nothing else is configured. `fallback`
+ * defaults to `"short"` to preserve the historical behaviour for callers
+ * that don't pass one.
+ */
+export declare function resolveCacheRetention(cacheRetention?: CacheRetention, fallback?: CacheRetention): CacheRetention;
+export declare function isAnthropicOAuthToken(key: string): boolean;