jeopi-ai 16.2.13

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

@@ -0,0 +1,20 @@
+export interface JsonSchemaValidationIssue {
+    path: PropertyKey[];
+    message: string;
+    expectedTypes?: string[];
+    keyword?: string;
+    /**
+     * Marks issues that originate inside a failed `anyOf` / `oneOf` branch.
+     * Consumers such as the tool-argument coercion layer use this to avoid
+     * applying type repairs (e.g. singleton-array wrapping) that would be
+     * authoritative outside of a combinator but are only one candidate
+     * branch's expectation here.
+     */
+    fromUnionBranch?: boolean;
+}
+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,124 @@
+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;
+    inferTypeForBareEnum: boolean;
+    foldOneOfIntoAnyOf: boolean;
+    dropNonScalarEnum: 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;
+/**
+ * Moonshot Flavored JSON Schema (MFJS) — the stricter subset Moonshot/Kimi
+ * native hosts (api.moonshot.ai, api.kimi.com) validate
+ * `tools.function.parameters` against. It rejects standard JSON Schema
+ * constructs that OpenAI-compatible hosts accept, returning HTTP 400
+ * `tools.function.parameters is not a valid moonshot flavored json schema`.
+ * Differences this normalizer reconciles:
+ *
+ *  - `const` (incl. `anyOf`/`oneOf` whose every branch is a bare `const`) is
+ *    rejected; collapse to `enum` with an inferred scalar `type`.
+ *  - `oneOf` is not an MFJS combinator (only `anyOf` is); residual `oneOf` is
+ *    folded into `anyOf`.
+ *  - `type` must be a scalar string; `type: [...]` arrays are reduced to a
+ *    single scalar (the `null` branch is dropped — `nullable` is unsupported).
+ *  - Enum-bearing nodes get an inferred `type` (the idiomatic MFJS form; a bare
+ *    `enum` is valid too) so `anyOf` branches always carry a `type`.
+ *  - Validation/decorative keywords (`minItems`, `maxItems`, `maxLength`,
+ *    `pattern`, `format`, `title`, …) and tuple `prefixItems` are rejected and
+ *    stripped, spilling human-meaningful ones into the sibling `description`.
+ *    `default` and `description` are MFJS Meta Data fields and are preserved.
+ *  - `additionalProperties` (boolean or schema) and `type: "null"` (incl.
+ *    inside `anyOf`) are kept.
+ *
+ * Out of scope (absent from the built-in tool surface, spec-ambiguous to
+ * rewrite blindly): `allOf` intersection merging, external/recursive `$ref`,
+ * and the depth-10 limit.
+ */
+export declare function normalizeSchemaForMoonshot(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,17 @@
+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. A `false` return does NOT deepen the counter — callers pair
+ * `exit` only with successful enters (`if (!enter(n)) bail; try {…} finally
+ * { exit(n); }`), so incrementing on the cycle branch would leak depth and
+ * make every later top-level walk of the same object misreport a cycle.
+ */
+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/strict-tool-validation.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Detects tool-parameter schemas that pass structural JSON-Schema validation
+ * (so {@link isValidJsonSchema} accepts them) yet make OpenAI-style providers
+ * reject the whole request with HTTP 400 — namely an `enum`/`const` whose
+ * value(s) cannot satisfy the node's declared `type`. MCP servers emit these
+ * when a nullable/array branch is built incorrectly (e.g. a non-null `enum`
+ * copied onto a `type: "null"` branch, or an `enum` placed on an `array`
+ * schema instead of its `items`). One such tool 400s the entire turn, so
+ * callers quarantine just the offending tool. See issue #2652.
+ */
+/**
+ * Walk a tool parameter schema for OpenAI-strict `enum`/`const`-vs-`type`
+ * contradictions. Returns a JSON-pointer-ish path to the first offending node,
+ * or `null` when the schema is safe to emit.
+ */
+export declare function findStrictToolSchemaViolation(schema: unknown, path?: string): string | null;

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/typescript.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Render a JSON Schema as a simplified, human-readable TypeScript type.
+ *
+ * This is a *display* conversion, not a faithful TS codegen: it surfaces the
+ * shape (objects, arrays, unions, enums, records) and property descriptions so
+ * a model — or a human reading `/dump` — can grasp a tool's parameters at a
+ * glance, far more legibly than raw JSON Schema. Refinement keywords
+ * (min/max/pattern/format) are intentionally dropped; only type structure,
+ * literal enums/consts, and descriptions survive.
+ */
+export interface JsonSchemaToTsOptions {
+    /** Indentation unit for nested object bodies. Default two spaces. */
+    readonly indent?: string;
+    /** Emit `description` keywords as JSDoc comments on object properties. Default true. */
+    readonly comments?: boolean;
+}
+/** Convert a JSON Schema object into a simplified TypeScript type string. */
+export declare function jsonSchemaToTypeScript(schema: unknown, options?: JsonSchemaToTsOptions): string;

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

@@ -0,0 +1,92 @@
+/**
+ * Compute the wire (JSON Schema) representation of a tool's parameters.
+ *
+ * Tools may author parameters in three shapes:
+ *   1. Zod (canonical) — converted to JSON Schema on demand.
+ *   2. ArkType — converted to JSON Schema via its native `toJsonSchema`.
+ *   3. TypeBox / plain JSON Schema (legacy + extension compat) — upgraded to
+ *      draft 2020-12 without converting.
+ *
+ * All three are normalized at the boundary so providers and validators see the same
+ * JSON Schema dialect.
+ */
+import type { Type } from "arktype";
+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;
+/**
+ * True when `value` is a live ArkType schema instance.
+ *
+ * ArkType schemas are callable functions carrying `toJsonSchema`/`assert`
+ * methods. Zod v4 instances are non-callable objects (keyed off `_zod`), and
+ * raw JSON Schema is a plain object — the three are disjoint. We deliberately
+ * avoid the Standard Schema `~standard` marker because Zod v4 implements it too.
+ */
+export declare function isArkSchema(value: unknown): value is Type;
+/**
+ * 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>;
+/**
+ * Convert an ArkType schema into the JSON Schema shape providers consume.
+ *
+ * Mirrors {@link zodToWireSchema}: emit draft-2020-12, drop the `$schema`
+ * metadata, run the JSON-schema post-process (NOT the Zod-only cleanup), then
+ * close declared objects so the wire is `additionalProperties: false` like Zod.
+ *
+ * The `fallback` degrades any un-emittable node (a `.narrow()` predicate or a
+ * morph) to its underlying base schema instead of throwing — matching Zod,
+ * whose `.refine()`/`.transform()` likewise never appear in the wire schema.
+ */
+export declare function arkToWireSchema(schema: Type): 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>;
+/**
+ * Return a deep clone of `schema` with every `description` annotation removed.
+ * The result is memoized on the input via a non-enumerable symbol (`stamp`) so
+ * repeated provider requests reuse the same stripped object; the input is never
+ * mutated, so the stamped `toolWireSchema` cache stays intact for
+ * system-prompt/UI rendering.
+ */
+export declare function stripSchemaDescriptions(schema: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Strip a tool's human-readable text from its provider-bound spec: empties the
+ * top-level `description` and removes nested schema `description` annotations.
+ * Used when the full tool catalog is rendered into the system prompt instead, so
+ * the descriptions ride the wire once (in the prompt) rather than duplicated on
+ * every tool definition. Parameters are resolved to wire JSON Schema and cloned,
+ * leaving the original tool objects and the stamped schema cache untouched.
+ */
+export declare function stripToolDescriptions(tools: readonly Tool[]): Tool[];

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,5 @@
+import type { ServerSentEvent } from "jeopi-utils";
+import type { RawSseEvent } from "../types";
+type RawSseObserver = (event: RawSseEvent) => void;
+export declare function notifyRawSseEvent(observer: RawSseObserver | undefined, event: ServerSentEvent | RawSseEvent): void;
+export {};

package/dist/types/utils/stream-markup-healing.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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. Tool-call healing delegates to the same
+ * dialect scanners used by owned in-band tool calling; this file keeps the
+ * provider-facing compatibility wrapper and model/provider gating.
+ */
+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.
+ *
+ * A {@link ThinkingInbandScanner} always heals leaked reasoning idioms
+ * (`<think>`, `<thinking>`, ` ```thinking `, Gemma/Harmony channels, …) out of
+ * the visible channel. For Kimi / DeepSeek-DSML the provider tool-call grammar
+ * runs first and its cleaned text is piped through that thinking healer, so a
+ * model can leak tool-call markup and reasoning in the same stream.
+ *
+ * Feed only one stream channel (usually `delta.content` / `message.content`).
+ * Mixing reasoning and visible text into the same instance can corrupt held-back
+ * partial tag buffers.
+ */
+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[];
+    /**
+     * Feed a chunk and return cleaned events, excluding synthesized tool calls.
+     * Used when the upstream chunk also carries structured `tool_calls`, keeping
+     * that structured payload as the single source of truth while preserving
+     * adjacent text and thinking events.
+     */
+    feedEventsWithoutCalls(text: string): StreamMarkupHealingEvent[];
+    /** 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 by the delegated scanners; 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;
+/**
+ * Pick the leaked-markup healer for an OpenAI-compatible / Ollama visible-text
+ * stream. Kimi chat-template tokens and DeepSeek DSML envelopes need their
+ * dedicated tool-call grammars; every other model uses `"thinking"`. All three
+ * patterns run the generic {@link ThinkingInbandScanner}, so leaked reasoning
+ * idioms (e.g. a Gemini ` ```thinking ` fence on OpenRouter) are always healed.
+ */
+export declare function getStreamMarkupHealingPattern(provider: string, modelId: string): StreamMarkupHealingPattern;

package/dist/types/utils/thinking-loop.d.ts

@@ -0,0 +1,102 @@
+import type { Api, Model, StreamOptions } from "../types";
+import { AssistantMessageEventStream } from "./event-stream";
+/** Stable lead phrase of the guard's error message; exported for tests. The
+ *  message also carries "stream stall" so the session + transport retry
+ *  classifiers treat it as a transient (retryable) stop without bespoke rules. */
+export declare const THINKING_LOOP_ERROR_MARKER = "Thinking loop detected";
+/**
+ * True when `model` is a Gemini model whose native thinking stream surfaces the
+ * "thought summary" titles this module's header guard counts.
+ *
+ * OpenAI-compat transports can serve Gemini under an arbitrary provider/id, so they
+ * carry the explicit `compat.enableGeminiThinkingLoopGuard` flag; direct Gemini
+ * transports carry a clearly shaped id/provider, so a string match is sufficient.
+ */
+export declare function isGeminiThinkingModel(model: Model<Api>): boolean;
+/**
+ * True when `model` should be guarded for thinking/response loops (Gemini & DeepSeek).
+ *
+ * OpenAI-compat transports can serve Gemini or DeepSeek under an arbitrary provider/id.
+ * Direct Gemini/DeepSeek transports carry a clearly shaped id/provider, so a string match
+ * is sufficient.
+ */
+export declare function isLoopGuardedModel(model: Model<Api>, options?: StreamOptions): boolean;
+/** @deprecated Use isLoopGuardedModel instead. */
+export declare function isGeminiThinkingLoopModel(model: Model<Api>): boolean;
+/**
+ * Stateful detector fed the streamed thinking deltas. `push` returns a
+ * human-readable reason the first time a loop shape is recognized; the caller
+ * is responsible for stopping after the first hit.
+ */
+export declare class ThinkingLoopDetector {
+    #private;
+    push(delta: string): string | null;
+    /** Process the buffered trailing paragraph (one with no blank-line / heading
+     *  terminator). Called when the thinking block ends so the final segment —
+     *  which may be the one that completes a duplicate cluster — is not dropped. */
+    flush(): string | null;
+}
+/**
+ * Consecutive Gemini thought-summary headers in one uninterrupted reasoning
+ * stream that trips the tool-call reminder. Gemini occasionally narrates a long
+ * chain of titled summaries ("Examining Result Handling", "Refining Result
+ * Rendering", …) without ever calling a tool, burning the whole budget on
+ * planning. This is the over-planning shape {@link ThinkingLoopDetector} misses —
+ * those titles are stripped before its similarity analysis precisely because their
+ * wording keeps changing, so a genuinely-distinct planning runaway never trips it.
+ *
+ * Set well above legitimate hard-problem depth: a capable model can emit ~10
+ * distinct, progressing hypotheses in a single reasoning block before acting (and
+ * a false trip is costly — the interrupt discards the whole reasoning turn). A
+ * real narration runaway burns dozens-to-hundreds of titles, so this still trips
+ * fast on the actual pathology.
+ */
+export declare const GEMINI_HEADER_RUNAWAY_THRESHOLD = 24;
+/**
+ * True when a single trimmed line is a Gemini reasoning-summary title: a markdown
+ * ATX heading (`## …`) or a whole-line bold / bold-italic run (`**Title**`,
+ * `***Title***`). Inline emphasis inside prose never matches — the bold run must
+ * span the entire line. Mirrors the title shapes {@link ThinkingLoopDetector}
+ * strips before similarity analysis.
+ */
+export declare function isReasoningSummaryHeader(line: string): boolean;
+/**
+ * Counts consecutive Gemini reasoning-summary headers across a streamed thinking
+ * block. {@link push} returns true exactly once — when the running header count
+ * first reaches {@link GEMINI_HEADER_RUNAWAY_THRESHOLD} — and the caller then
+ * interrupts the stream and reminds the model to issue a tool call. Paragraph
+ * lines between titles do NOT reset the run (Gemini emits header + paragraph per
+ * thought, so the run IS the number of summaries); leaving the reasoning channel
+ * does, via {@link reset} on a new thinking block / prose / tool call.
+ */
+export declare class GeminiHeaderRunDetector {
+    #private;
+    /** Feed a thinking delta. Returns true the first time the run hits the threshold. */
+    push(delta: string): boolean;
+    /** Number of summary titles counted in the current run (for the reminder/log). */
+    get count(): number;
+    /** Re-arm for a fresh reasoning block: clears the buffer, count, and latch. */
+    reset(): void;
+}
+/**
+ * Wrap a provider stream with the loop guard. `controller` is the guard's own
+ * abort handle: aborting it (after wiring it into the provider's signal via
+ * {@link withGeminiThinkingLoopGuard}) tears down the upstream once a loop
+ * trips.
+ */
+export declare function guardThinkingLoopStream(inner: AssistantMessageEventStream, model: Model<Api>, controller: AbortController, options?: StreamOptions): AssistantMessageEventStream;
+/**
+ * Apply the loop guard around a provider dispatch. For non-guarded models
+ * (or when disabled) this is a transparent pass-through. For guarded models it injects a
+ * guard abort signal into the provider call so a detected loop tears down the
+ * upstream, then wraps the returned stream. The guard only raises the retryable
+ * stall; bounding the re-samples and the final cook pass lives in the
+ * result-awaiting caller.
+ */
+export declare function withGeminiThinkingLoopGuard<O extends {
+    signal?: AbortSignal;
+    loopGuard?: {
+        enabled?: boolean;
+        checkAssistantContent?: boolean;
+    };
+}>(model: Model<Api>, options: O | undefined, dispatch: (options: O | undefined) => AssistantMessageEventStream): AssistantMessageEventStream;

package/dist/types/utils/tool-call-loop-guard.d.ts

@@ -0,0 +1,26 @@
+import type { AssistantMessage, ToolResultMessage } from "../types";
+/** Runtime settings for cross-turn tool-call repetition detection. */
+export interface ToolCallLoopGuardOptions {
+    readonly threshold: number;
+    readonly exemptTools: readonly string[];
+}
+/** A completed assistant turn plus the tool results it produced. */
+export interface ToolCallLoopTurn {
+    readonly message: AssistantMessage;
+    readonly toolResults: readonly ToolResultMessage[];
+}
+/** Details needed to steer the model away from a repeated tool call. */
+export interface RepeatedToolCallDetection {
+    readonly kind: "repeated_tool_call";
+    readonly toolName: string;
+    readonly count: number;
+    readonly resultSummary: string;
+    readonly argumentsSummary: string;
+}
+/** Detects consecutive identical assistant tool calls across model turns. */
+export declare class ToolCallLoopGuard {
+    #private;
+    constructor(options: ToolCallLoopGuardOptions);
+    /** Records one completed turn and returns the threshold hit, if any. */
+    recordTurn(turn: ToolCallLoopTurn): RepeatedToolCallDetection | null;
+}

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;