@linxiraos/pi-ai 1.0.0

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * 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>>;
+/**
+ * Flat set of every type-specific key across all CCA types.
+ * Used to identify sibling keys that need filtering during mixed-type collapse.
+ */
+export declare const ALL_CCA_TYPE_SPECIFIC_KEYS: 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,14 @@
+export * from "./adapt.js";
+export * from "./compatibility.js";
+export * from "./dereference.js";
+export * from "./draft.js";
+export * from "./equality.js";
+export * from "./fields.js";
+export * from "./json-schema-validator.js";
+export * from "./meta-validator.js";
+export * from "./normalize.js";
+export * from "./spill.js";
+export * from "./strict-tool-validation.js";
+export * from "./types.js";
+export * from "./typescript.js";
+export * from "./wire.js";

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,153 @@
+import { type DescriptionSpillFormat } from "./spill.js";
+import { type JsonObject } from "./types.js";
+export type ResidualSchemaIncompatibility = "type-array" | "type-null" | "nullable" | "combiners" | "not";
+export interface NormalizeSchemaOptions {
+    /**
+     * Coerce boolean subschemas to object forms. `standard` preserves `false`
+     * with `not`; `permissive` uses `{}` when the provider cannot express it.
+     */
+    coerceBooleanSubschemas?: "standard" | "permissive";
+    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;
+    stringEnumsOnly?: 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.
+ *  - Boolean subschemas are object-coerced; MFJS has no exact `false` schema,
+ *    so both values become the permissive empty schema while local tool
+ *    validation remains authoritative.
+ *
+ * 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;
+/**
+ * Rewrites standard JSON Schema forms that Ollama's Go `/api/chat` tool parser
+ * cannot unmarshal into its object-shaped `Schema` struct.
+ */
+export declare function sanitizeSchemaForOllama(schema: JsonObject): JsonObject;
+/**
+ * Rewrites the one JSON Schema form that grammar-constrained OpenAI-compatible
+ * backends (llama.cpp, LM Studio, vLLM) cannot compile to GBNF: a bare boolean
+ * subschema. `toolWireSchema` normalizes `{}` open subschemas to boolean `true`
+ * (issue #1179); llama.cpp's `json-schema-to-grammar.cpp` `visit()` has no case
+ * for a boolean schema and throws `Unrecognized schema: true` → HTTP 400 before
+ * the model is consulted (issue #5914).
+ *
+ * Narrower than {@link sanitizeSchemaForOllama}: only genuine subschema slots
+ * are widened. Boolean `additionalProperties`/`unevaluatedProperties` stay
+ * intact because the converter reads those as closed/open-object grammar
+ * semantics, and dropping `additionalProperties: false` would silently reopen
+ * every declared object.
+ */
+export declare function sanitizeSchemaForGrammar(schema: JsonObject): JsonObject;
+/**
+ * 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.js";
+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,24 @@
+/**
+ * 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 (none in `harmony` style). */
+    readonly indent?: string;
+    /** Emit `description` keywords as comments on object properties. Default true. */
+    readonly comments?: boolean;
+    /**
+     * Output flavor. `default` renders JSDoc comments, `;` delimiters, and
+     * indented bodies; `harmony` renders the flat OpenAI-Harmony convention —
+     * `//` line comments, `,` delimiters, no indentation.
+     */
+    readonly style?: "default" | "harmony";
+}
+/** 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,52 @@
+/**
+ * Compute the wire (JSON Schema) representation of a tool's parameters.
+ *
+ * Tools may author parameters as ArkType schemas or legacy TypeBox / plain JSON
+ * Schema documents. Both are normalized at the boundary so providers and
+ * validators see the same JSON Schema dialect.
+ */
+import type { Type } from "@linxiraos/pi-omptype";
+import type { Tool } from "../../types.js";
+/**
+ * True when `value` is a live ArkType schema instance.
+ *
+ * ArkType schemas are callable functions carrying `toJsonSchema`/`assert`
+ * methods, while raw JSON Schema is a plain object.
+ */
+export declare function isArkSchema(value: unknown): value is Type;
+/**
+ * Normalize `{}` (an unconstrained schema) to boolean `true` in every
+ * schema-valued position. JSON Schema draft 2020-12 §4.3.1 defines them as
+ * semantically equivalent. Grammar-constrained samplers often treat the object
+ * form as "generate an empty object" rather than "any JSON value".
+ *
+ * Mutates in place and applies to every tool wire schema.
+ */
+export declare function normalizeEmptySchemas(node: unknown): void;
+/**
+ * Convert an ArkType schema into the JSON Schema shape providers consume.
+ */
+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. ArkType schemas are converted and cached; legacy TypeBox /
+ * raw JSON Schema parameters are upgraded to draft 2020-12 and cached.
+ */
+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/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 "@linxiraos/pi-utils";
+import type { RawSseEvent } from "../types.js";
+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;