@vib-rato/ai 0.16.0

package/dist/types/providers/google-shared.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Shared utilities for Google Generative AI and Google Cloud Code Assist providers.
+ */
+import type { ProviderSafetyStopAdapterInvocation } from "../adapter-internals/provider-safety-stop";
+import type { AssistantMessage, Context, FetchImpl, Model, StopReason, StreamOptions, TextContent, ThinkingContent, Tool, ToolCall } from "../types";
+import { AssistantMessageEventStream } from "../utils/event-stream";
+import { normalizeSchemaForGoogle } from "../utils/schema";
+import type { Content, FinishReason, FunctionCallingConfigMode, GenerateContentParameters, GenerateContentResponse, Part } from "./google-types";
+export type { Content, FunctionCallingConfigMode, GenerateContentParameters, GenerateContentResponse, ThinkingConfig, } from "./google-types";
+export { normalizeSchemaForGoogle };
+type GoogleApiType = "google-generative-ai" | "google-gemini-cli" | "google-vertex";
+export declare const PROVIDER_SAFETY_STOP = "provider_safety_stop";
+export declare function isGoogleCandidateSafetyStopReason(reason: string): boolean;
+export declare function isGooglePromptSafetyStopReason(reason: string): boolean;
+export declare function getGooglePromptBlockReason(promptFeedback: {
+    blockReason?: unknown;
+} | undefined): string | undefined;
+/**
+ * Thinking level for Gemini 3 models. Mirrors Google's `ThinkingLevel` enum values.
+ * Defined here (not in any specific provider) so all Google providers can reference it
+ * without inducing a circular dependency.
+ */
+export type GoogleThinkingLevel = "THINKING_LEVEL_UNSPECIFIED" | "MINIMAL" | "LOW" | "MEDIUM" | "HIGH";
+/**
+ * Sampling/thinking options shared by `streamGoogle` and `streamGoogleVertex`.
+ * `google-gemini-cli` uses a different transport and request shape — do not extend this for it.
+ */
+export interface GoogleSharedStreamOptions extends StreamOptions {
+    toolChoice?: "auto" | "none" | "any" | "required";
+    thinking?: {
+        enabled: boolean;
+        budgetTokens?: number;
+        level?: GoogleThinkingLevel;
+    };
+}
+/**
+ * Determines whether a streamed Gemini `Part` should be treated as "thinking".
+ *
+ * Protocol note (Gemini / Vertex AI thought signatures):
+ * - `thought: true` is the definitive marker for thinking content (thought summaries).
+ * - `thoughtSignature` is an encrypted representation of the model's internal thought process
+ *   used to preserve reasoning context across multi-turn interactions.
+ * - `thoughtSignature` can appear on ANY part type (text, functionCall, etc.) - it does NOT
+ *   indicate the part itself is thinking content.
+ * - For non-functionCall responses, the signature appears on the last part for context replay.
+ * - When persisting/replaying model outputs, signature-bearing parts must be preserved as-is;
+ *   do not merge/move signatures across parts.
+ *
+ * See: https://ai.google.dev/gemini-api/docs/thought-signatures
+ */
+export declare function isThinkingPart(part: Pick<Part, "thought" | "thoughtSignature">): boolean;
+/**
+ * Retain thought signatures during streaming.
+ *
+ * Some backends only send `thoughtSignature` on the first delta for a given part/block; later deltas may omit it.
+ * This helper preserves the last non-empty signature for the current block.
+ *
+ * Note: this does NOT merge or move signatures across distinct response parts. It only prevents
+ * a signature from being overwritten with `undefined` within the same streamed block.
+ */
+export declare function retainThoughtSignature(existing: string | undefined, incoming: string | undefined): string | undefined;
+/**
+ * Anthropic model models via Google APIs require explicit tool call IDs in function calls/responses.
+ */
+export declare function requiresToolCallId(modelId: string): boolean;
+/**
+ * Convert internal messages to Gemini Content[] format.
+ */
+export declare function convertMessages<T extends GoogleApiType>(model: Model<T>, context: Context): Content[];
+/**
+ * Convert tools to Gemini function declarations format.
+ *
+ * We prefer `parametersJsonSchema` (full JSON Schema: anyOf/oneOf/const/etc.).
+ *
+ * Anthropic model models via Cloud Code Assist require the legacy `parameters` field; the API
+ * translates it into Anthropic's `input_schema`. When using that path, we sanitize the
+ * schema to remove Google-unsupported JSON Schema keywords.
+ */
+export declare function convertTools(tools: Tool[], model: Model<"google-generative-ai" | "google-gemini-cli" | "google-vertex">): {
+    functionDeclarations: Record<string, unknown>[];
+}[] | undefined;
+/**
+ * Map tool choice string to Gemini FunctionCallingConfigMode.
+ */
+export declare function mapToolChoice(choice: string): FunctionCallingConfigMode;
+/**
+ * Map Gemini FinishReason to our StopReason.
+ */
+export declare function mapStopReason(reason: FinishReason): StopReason;
+/**
+ * Map string finish reason to our StopReason (for raw API responses).
+ */
+export declare function mapStopReasonString(reason: string): StopReason;
+export declare function nextToolCallId(name: string): string;
+/**
+ * Push the appropriate `text_end` / `thinking_end` event for the given block.
+ * Shared between the SDK-backed stream consumer and the gemini-cli SSE consumer so
+ * the end-of-block event shape stays in lockstep.
+ */
+export declare function pushBlockEndEvent(block: TextContent | ThinkingContent, contentIndex: number, output: AssistantMessage, stream: AssistantMessageEventStream): void;
+/**
+ * Push the three lifecycle events (`toolcall_start` / `toolcall_delta` / `toolcall_end`) for a
+ * fully-assembled `ToolCall`. Caller is responsible for appending the toolCall to `output.content`
+ * before invoking — this helper does not mutate `output.content`.
+ */
+export declare function pushToolCallEvents(toolCall: ToolCall, contentIndex: number, output: AssistantMessage, stream: AssistantMessageEventStream): void;
+/**
+ * Append a new text- or thinking-block to `output.content` and push the matching
+ * `text_start` / `thinking_start` event. `onBeforeStartEvent` lets the SSE consumer
+ * inject its `ensureStarted()` first-token side effect into the canonical event order.
+ */
+export declare function startTextOrThinkingBlock(isThinking: boolean, output: AssistantMessage, stream: AssistantMessageEventStream, onBeforeStartEvent?: () => void): TextContent | ThinkingContent;
+/**
+ * Drives the chunked `generateContentStream` iterator into an `AssistantMessage` and
+ * the corresponding `AssistantMessageEventStream`. Shared between `streamGoogle` and
+ * `streamGoogleVertex` — every observable event order and stop-reason rule is preserved.
+ *
+ * The caller still owns: `output` construction, timing fields (`duration`/`ttft`),
+ * `rawRequestDump`, the `client.models.generateContentStream(params)` call itself,
+ * pushing `start`/`done`/`error` events, and the surrounding try/catch that translates
+ * thrown errors into `output.stopReason`/`errorMessage`.
+ *
+ * This helper handles: the chunk loop, currentBlock flush transitions, usage metadata
+ * decoding (`calculateCost` included), tool-call id collision avoidance, finish-reason
+ * mapping, and the abort/stop-reason post-checks that re-throw to bubble into the
+ * caller's catch.
+ */
+export declare function consumeGoogleStream<T extends GoogleApiType>(args: {
+    googleStream: AsyncIterable<GenerateContentResponse>;
+    output: AssistantMessage;
+    stream: AssistantMessageEventStream;
+    model: Model<T>;
+    options: {
+        signal?: AbortSignal;
+        fetch?: unknown;
+    } | undefined;
+    callerFetch?: unknown;
+    adapterInvocation?: ProviderSafetyStopAdapterInvocation;
+    /** Vertex preserves `textSignature` on streamed text deltas; google-generative-ai does not. */
+    retainTextSignature?: boolean;
+    onFirstToken?: () => void;
+}): Promise<void>;
+/**
+ * Build the `GenerateContentParameters` payload for the public Gemini API and Vertex AI.
+ * Both surfaces accept the same `GenerateContentConfig` shape — every numeric/string knob,
+ * tool-config, thinking-config, and system-instruction conversion is identical.
+ *
+ * `google-gemini-cli` is NOT routed through here: its `CloudCodeAssistRequest` body has a
+ * distinct top-level shape (project/request/requestType) and a different thinking-config
+ * placement on `generationConfig`.
+ */
+export declare function buildGoogleGenerateContentParams<T extends "google-generative-ai" | "google-vertex">(model: Model<T>, context: Context, options: GoogleSharedStreamOptions): GenerateContentParameters;
+/**
+ * Drive the `streamGoogle` / `streamGoogleVertex` event flow: build the assistant message,
+ * push start/done/error events, run `consumeGoogleStream`, and translate thrown errors into
+ * the canonical `error` event shape.
+ *
+ * Caller-supplied `prepare()` runs inside the try-block so any failure (missing project,
+ * bad auth, etc.) is funneled through the same error path as a streaming failure.
+ */
+export interface GoogleGenAIRequestPlan {
+    params: GenerateContentParameters;
+    url: string;
+    headers: Record<string, string>;
+    fetch?: FetchImpl;
+}
+export declare function streamGoogleGenAI<T extends "google-generative-ai" | "google-vertex">(args: {
+    model: Model<T>;
+    options: GoogleSharedStreamOptions | undefined;
+    api: T;
+    retainTextSignature?: boolean;
+    prepare: () => GoogleGenAIRequestPlan | Promise<GoogleGenAIRequestPlan>;
+}): AssistantMessageEventStream;
+/**
+ * Lift the SDK's `params.config` fields out of `config` and place them where the
+ * Gemini / Vertex AI REST API expects them on the request body. Mirrors the
+ * generateContentParametersTo{Mldev,Vertex} transformation in @google/genai
+ * for the subset of fields this codebase actually sets.
+ *
+ * `abortSignal` is intentionally dropped — the SDK propagates it via `fetch.signal`,
+ * which our caller already wires up through `options.signal`.
+ */
+export declare function paramsToWireBody(params: GenerateContentParameters): Record<string, unknown>;

package/dist/types/providers/google-types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Local mirror of the subset of `@google/genai` types this package consumes.
+ *
+ * Field shapes match Gemini / Vertex AI wire format 1:1. Enum-shaped values are
+ * modelled as string literal unions so they pass through `JSON.stringify` and
+ * `JSON.parse` unchanged.
+ *
+ * Keep this file in sync with the actual request/response surface of:
+ *   - `POST {generativelanguage,aiplatform}.googleapis.com/.../models/{model}:streamGenerateContent?alt=sse`
+ *   - The Cloud Code Assist endpoint used by `google-gemini-cli.ts`
+ */
+/** Mirror of `@google/genai`'s `FinishReason` string enum. */
+export type FinishReason = "FINISH_REASON_UNSPECIFIED" | "STOP" | "MAX_TOKENS" | "SAFETY" | "RECITATION" | "LANGUAGE" | "OTHER" | "BLOCKLIST" | "PROHIBITED_CONTENT" | "SPII" | "MALFORMED_FUNCTION_CALL" | "IMAGE_SAFETY" | "IMAGE_PROHIBITED_CONTENT" | "IMAGE_RECITATION" | "IMAGE_OTHER" | "UNEXPECTED_TOOL_CALL" | "NO_IMAGE";
+/** Mirror of `@google/genai`'s `FunctionCallingConfigMode` string enum. */
+export type FunctionCallingConfigMode = "MODE_UNSPECIFIED" | "AUTO" | "NONE" | "ANY" | "VALIDATED";
+/** Mirror of `@google/genai`'s `ThinkingLevel` string enum. */
+export type ThinkingLevel = "THINKING_LEVEL_UNSPECIFIED" | "MINIMAL" | "LOW" | "MEDIUM" | "HIGH";
+/** Inline base64-encoded data part. */
+export interface InlineDataPart {
+    mimeType: string;
+    data: string;
+}
+/** Function call emitted by the model. */
+export interface FunctionCallPart {
+    name?: string;
+    args?: Record<string, unknown>;
+    id?: string;
+}
+/** Tool execution result fed back to the model. */
+export interface FunctionResponsePart {
+    name: string;
+    response: Record<string, unknown>;
+    parts?: Part[];
+    id?: string;
+}
+/**
+ * A single piece of a `Content` message. Mirrors the SDK's union by keeping
+ * every optional field — the model and the wire treat shape as discriminator.
+ */
+export interface Part {
+    text?: string;
+    thought?: boolean;
+    thoughtSignature?: string;
+    inlineData?: InlineDataPart;
+    functionCall?: FunctionCallPart;
+    functionResponse?: FunctionResponsePart;
+}
+/** Conversation turn. Roles: `"user"`, `"model"`, optionally absent for system instructions. */
+export interface Content {
+    role?: string;
+    parts?: Part[];
+}
+/** Thinking/reasoning configuration shared by Gemini 2.x and 3.x models. */
+export interface ThinkingConfig {
+    includeThoughts?: boolean;
+    thinkingBudget?: number;
+    thinkingLevel?: ThinkingLevel;
+}
+/** Function declaration entry inside `tools[].functionDeclarations`. */
+export interface FunctionDeclaration {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    parametersJsonSchema?: Record<string, unknown>;
+}
+/** Tool group as accepted at the request top level. */
+export interface ToolDeclaration {
+    functionDeclarations: Record<string, unknown>[];
+}
+/** Tool selection mode container. */
+export interface ToolConfig {
+    functionCallingConfig?: {
+        mode: FunctionCallingConfigMode;
+        allowedFunctionNames?: string[];
+    };
+}
+/**
+ * Generation/sampling and request-shape options passed via the SDK's `config`.
+ *
+ * Fields that the wire format places at the request body root (systemInstruction,
+ * tools, toolConfig, safetySettings, cachedContent) live here too — the
+ * transformer in `google-shared.ts` lifts them out when serializing.
+ */
+export interface GenerateContentConfig {
+    temperature?: number;
+    maxOutputTokens?: number;
+    topP?: number;
+    topK?: number;
+    candidateCount?: number;
+    stopSequences?: string[];
+    presencePenalty?: number;
+    frequencyPenalty?: number;
+    seed?: number;
+    responseMimeType?: string;
+    responseSchema?: Record<string, unknown>;
+    responseJsonSchema?: Record<string, unknown>;
+    responseModalities?: string[];
+    systemInstruction?: Content | {
+        role?: string;
+        parts: {
+            text: string;
+        }[];
+    };
+    tools?: ToolDeclaration[];
+    toolConfig?: ToolConfig;
+    safetySettings?: Array<Record<string, unknown>>;
+    cachedContent?: string;
+    thinkingConfig?: ThinkingConfig;
+    abortSignal?: AbortSignal;
+}
+/** Top-level argument to `generateContentStream`. */
+export interface GenerateContentParameters {
+    model: string;
+    contents: Content[];
+    config?: GenerateContentConfig;
+}
+/** Per-stream candidate envelope. */
+export interface Candidate {
+    content?: Content;
+    finishReason?: FinishReason;
+    index?: number;
+}
+/** Cumulative token accounting attached to the trailing chunk. */
+export interface UsageMetadata {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    thoughtsTokenCount?: number;
+    totalTokenCount?: number;
+    cachedContentTokenCount?: number;
+}
+/** Single SSE chunk's parsed JSON body. */
+export interface GenerateContentResponse {
+    candidates?: Candidate[];
+    usageMetadata?: UsageMetadata;
+    modelVersion?: string;
+    responseId?: string;
+    promptFeedback?: Record<string, unknown>;
+}

package/dist/types/providers/google-vertex.d.ts

@@ -0,0 +1,11 @@
+import type { StreamFunction } from "../types";
+import { type GoogleSharedStreamOptions } from "./google-shared";
+export interface GoogleVertexOptions extends GoogleSharedStreamOptions {
+    project?: string;
+    location?: string;
+}
+export declare const streamGoogleVertex: StreamFunction<"google-vertex">;
+/** Test seam: the Vertex API key as resolved from options plus trusted env. */
+export declare function resolveVertexApiKeyForTest(options?: GoogleVertexOptions): string | undefined;
+/** Test seam: the Vertex location as resolved from options plus trusted env. */
+export declare function resolveVertexLocationForTest(options?: GoogleVertexOptions): string;

package/dist/types/providers/google.d.ts

@@ -0,0 +1,4 @@
+import type { StreamFunction } from "../types";
+import { type GoogleSharedStreamOptions } from "./google-shared";
+export type GoogleOptions = GoogleSharedStreamOptions;
+export declare const streamGoogle: StreamFunction<"google-generative-ai">;

package/dist/types/providers/grammar.d.ts

@@ -0,0 +1 @@
+export declare function compactGrammarDefinition(syntax: "lark" | "regex", definition: string): string;

package/dist/types/providers/kimi.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Kimi Code provider - wraps OpenAI or Anthropic API based on format setting.
+ *
+ * Kimi offers both OpenAI-compatible and Anthropic-compatible APIs:
+ * - OpenAI: https://api.kimi.com/coding/v1/chat/completions
+ * - Anthropic: https://api.kimi.com/coding/v1/messages
+ *
+ * The Anthropic API is generally more stable and recommended.
+ * Note: Kimi calculates TPM rate limits based on max_tokens, not actual output.
+ */
+import type { Api, Context, Model } from "../types";
+import type { AssistantMessageEventStream } from "../utils/event-stream";
+import { type OpenAIAnthropicApiFormat, type OpenAIAnthropicShimOptions } from "./openai-anthropic-shim";
+export type KimiApiFormat = OpenAIAnthropicApiFormat;
+export interface KimiOptions extends OpenAIAnthropicShimOptions {
+    /** API format: "openai" or "anthropic". Default: "anthropic" */
+    format?: KimiApiFormat;
+}
+/**
+ * Stream from Kimi Code, routing to either OpenAI or Anthropic API based on format.
+ * Returns synchronously like other providers - async header fetching happens internally.
+ */
+export declare function streamKimi(model: Model<"openai-completions">, context: Context, options?: KimiOptions): AssistantMessageEventStream;
+/**
+ * Check if a model is a Kimi Code model.
+ */
+export declare function isKimiModel(model: Model<Api>): boolean;

package/dist/types/providers/kiro-api-key.d.ts

@@ -0,0 +1,50 @@
+import type { Model, StreamFunction } from "../types";
+export declare function isKiroApiKey(value: string | undefined): value is string;
+export declare function kiroApiRegion(options?: {
+    region?: string;
+}): string;
+export declare function kiroApiBaseUrl(region: string): string;
+export declare function toKiroModelId(modelId: string): string;
+export declare function kiroApiStaticModels(): Model<"kiro-codewhisperer-stream">[];
+/** Discover models this API key can use. Returns null when the key is missing. */
+export declare function fetchKiroApiModels(apiKey: string, region?: string): Promise<Model<"kiro-codewhisperer-stream">[]>;
+type KiroStreamEvent = {
+    type: "content";
+    data: string;
+} | {
+    type: "toolUse";
+    data: {
+        name: string;
+        toolUseId: string;
+        input: string;
+        stop?: boolean;
+    };
+} | {
+    type: "toolUseInput";
+    data: {
+        input: string;
+    };
+} | {
+    type: "toolUseStop";
+    data: {
+        stop: boolean;
+    };
+} | {
+    type: "usage";
+    data: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+} | {
+    type: "error";
+    data: {
+        error: string;
+        message?: string;
+    };
+};
+export declare function parseKiroApiEvents(buffer: string): {
+    events: KiroStreamEvent[];
+    remaining: string;
+};
+export declare const streamKiroApiKey: StreamFunction<"kiro-codewhisperer-stream">;
+export {};

package/dist/types/providers/kiro-codewhisperer.d.ts

@@ -0,0 +1,11 @@
+import type { Effort } from "../model-thinking";
+import type { StreamFunction, StreamOptions } from "../types";
+export interface KiroCodeWhispererOptions extends StreamOptions {
+    /** Effort level for Kiro API-key reasoning. */
+    reasoning?: Effort | boolean;
+    /** AWS region for the CodeWhisperer streaming endpoint. */
+    region?: string;
+    /** Profile ARN for enterprise IAM Identity Center accounts. */
+    profileArn?: string;
+}
+export declare const streamKiroCodeWhisperer: StreamFunction<"kiro-codewhisperer-stream">;

package/dist/types/providers/mock.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Mock provider for tests.
+ *
+ * Implements `Model<"mock">` + `streamMock` so test code can drive
+ * pi-agent-core / streamSimple-shaped consumers without an HTTP client.
+ *
+ * Usage:
+ *
+ *   import { createMockModel, registerMockApi } from "@vib-rato/ai/providers/mock";
+ *
+ *   // 1. Array of responses, one per call.
+ *   const mock = createMockModel({
+ *     responses: [
+ *       { content: [{ type: "toolCall", name: "read", arguments: { path: "/x" } }] },
+ *       { content: ["done"] },
+ *     ],
+ *   });
+ *
+ *   // 2. Async generator — full state-machine power, can await between turns.
+ *   const mock = createMockModel({
+ *     responses: (async function* () {
+ *       yield { content: [{ type: "toolCall", name: "fetch", arguments: { url } }] };
+ *       // wait for external coordination
+ *       await externalReady;
+ *       yield { content: ["got it"] };
+ *     })(),
+ *   });
+ *
+ *   // 3. Per-call handler (closure with access to the call).
+ *   const mock = createMockModel({
+ *     handler: (context) => ({ content: [`turn ${context.messages.length}`] }),
+ *   });
+ *
+ *   // 4. Use as a streamFn for agentLoop:
+ *   await agentLoop(prompts, context, config, undefined, mock.stream).result();
+ *
+ *   // 5. Or register globally and use stream():
+ *   registerMockApi();
+ *   stream(mock.model, context, options);
+ *
+ *   // Inspect calls afterwards.
+ *   expect(mock.calls).toHaveLength(2);
+ */
+import type { Api, AssistantMessage, Context, Model, SimpleStreamOptions, StopReason, Usage } from "../types";
+import { AssistantMessageEventStream } from "../utils/event-stream";
+import { type UnicodeEscapeEvidence } from "../utils/json-parse";
+/** The API string this provider serves. */
+export declare const MOCK_API: "mock";
+export type MockApi = typeof MOCK_API;
+/** Shorthand for a single content block. Strings become text blocks. */
+export type MockContent = string | {
+    type: "text";
+    text: string;
+} | {
+    type: "thinking";
+    thinking: string;
+} | {
+    type: "toolCall";
+    /** Optional explicit id; auto-generated when omitted. */
+    id?: string;
+    name: string;
+    /** Object form is preferred; strings are passed through verbatim. */
+    arguments: Record<string, unknown> | string;
+    /** Simulate a provider-flagged truncated call (cut off mid-arguments). */
+    incompleteArguments?: boolean;
+    /** Typed reason matching `ToolCall.incompleteArgumentsReason`. Defaults to `"truncated"`. */
+    incompleteArgumentsReason?: "truncated" | "malformed" | "conflicting" | "ambiguous";
+    /** Simulate a provider-flagged `\uXXXX`-escaped non-ASCII argument payload. */
+    escapedNonAsciiArguments?: boolean;
+    escapedUnicodeArgumentEvidence?: UnicodeEscapeEvidence;
+    thoughtSignature?: string;
+};
+/** One scripted response. */
+export interface MockResponse {
+    /** Content blocks to emit, in order. Strings become text blocks. */
+    content?: ReadonlyArray<MockContent>;
+    /** Stop reason. Defaults to `"toolUse"` when content has tool calls, else `"stop"`. */
+    stopReason?: StopReason;
+    /** Usage stats. Missing fields default to 0; missing `cost.total` is recomputed from components. */
+    usage?: Partial<Omit<Usage, "cost">> & {
+        cost?: Partial<Usage["cost"]>;
+    };
+    /** Pre-set responseId. */
+    responseId?: string;
+    /** Optional provider metadata copied onto the final assistant message. */
+    disabledFeatures?: string[];
+    providerPayload?: AssistantMessage["providerPayload"];
+    /** Optional typed provider failure metadata for retry/fallback tests. */
+    transportFailure?: AssistantMessage["transportFailure"];
+    /** If set, the stream emits a terminal error event instead of completing. */
+    throw?: string | Error;
+    /** Delay before any event is emitted. Honors the call's AbortSignal. */
+    delayMs?: number;
+    /**
+     * If set, the mock synthesizes a {@link ProviderResponseMetadata} and fires
+     * `options.onResponse` once before streaming events. Headers are forwarded
+     * verbatim (keys lowercased to match real provider plumbing).
+     */
+    responseHeaders?: Readonly<Record<string, string>>;
+    /** HTTP status code paired with {@link responseHeaders}. Defaults to 200. */
+    responseStatus?: number;
+    /** Pre-set requestId surfaced via {@link ProviderResponseMetadata.requestId}. */
+    responseRequestId?: string;
+}
+/** Handler resolved per call: static script or function. */
+export type MockHandler = MockResponse | ((context: Context, options?: SimpleStreamOptions) => MockResponse | Promise<MockResponse>);
+/**
+ * A source of handlers, one per call.
+ *
+ * - Arrays / iterables consume one entry per call (most ergonomic for scripts).
+ * - Async iterables (e.g. `async function*()`) let the test pause between calls,
+ *   coordinate with external events, or build state machines.
+ *
+ * The first call pulls the first entry, the second call pulls the second, and
+ * so on. When the source is exhausted, `MockModelOptions.handler` is used; if
+ * neither is set, the call rejects.
+ */
+export type MockResponseSource = Iterable<MockHandler> | AsyncIterable<MockHandler>;
+/** Recorded call for inspection. */
+export interface MockCall {
+    readonly context: Context;
+    readonly options?: SimpleStreamOptions;
+}
+/** Construction options. */
+export interface MockModelOptions {
+    /** Model id. Defaults to `"mock-model"`. */
+    id?: string;
+    /** Provider string used in the returned AssistantMessage. Defaults to `"mock"`. */
+    provider?: string;
+    /** A sequence of responses, one per call. Accepts arrays, generators, or any iterable. */
+    responses?: MockResponseSource;
+    /** Fallback handler used when `responses` is exhausted. */
+    handler?: MockHandler;
+    /** Cost per million tokens. Defaults to zeros. */
+    cost?: Model["cost"];
+    /** Context window. Defaults to 200_000. */
+    contextWindow?: number;
+    /** Max output tokens. Defaults to 32_768. */
+    maxTokens?: number;
+    /** Whether the model claims to support reasoning. Defaults to false. */
+    reasoning?: boolean;
+}
+/**
+ * A `Model<"mock">` that carries its own scripted state. Pass instances to
+ * `stream()` or agent configs, and use the same instance to inspect calls
+ * and feed additional handlers.
+ */
+export declare class MockModel implements Model<MockApi> {
+    readonly id: string;
+    readonly name: string;
+    readonly api: MockApi;
+    readonly provider: string;
+    readonly baseUrl = "mock://";
+    readonly reasoning: boolean;
+    readonly input: ("text" | "image")[];
+    readonly cost: Model["cost"];
+    readonly contextWindow: number;
+    readonly maxTokens: number;
+    /** Recorded calls in invocation order. */
+    readonly calls: MockCall[];
+    iterator?: Iterator<MockHandler> | AsyncIterator<MockHandler>;
+    exhausted: boolean;
+    readonly extras: MockHandler[];
+    fallback?: MockHandler;
+    toolCallCounter: number;
+    constructor(options?: MockModelOptions);
+    /** Back-compat alias: the model is its own handle. */
+    get model(): this;
+    /** A streamFn-compatible callable. Forward to `agentLoop` or pi `stream()`. */
+    stream: (_model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+    /**
+     * Append a handler to the internal queue consumed AFTER the constructor
+     * `responses` source is exhausted (but before the fallback). Use this for
+     * interactive tests that decide responses after the model is created.
+     */
+    push(response: MockHandler): void;
+    /** Reset recorded calls AND the extras queue. The constructor `responses` are NOT reset. */
+    reset(): void;
+}
+/** @deprecated Use {@link MockModel}; the class IS the handle. */
+export type MockModelHandle = MockModel;
+/** Check whether `model` was produced by `createMockModel`. */
+export declare function isMockModel(model: Model<Api>): model is MockModel;
+/** Construct a mock model. */
+export declare function createMockModel(options?: MockModelOptions): MockModel;
+/** Stream function for `Model<"mock">`. Matches the pi-ai per-provider stream signature. */
+export declare function streamMock(model: Model<Api>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+/** Convenience: register the mock provider with the global custom API registry. */
+export declare function registerMockApi(sourceId?: string): void;

package/dist/types/providers/ollama.d.ts

@@ -0,0 +1,41 @@
+import type { Context, Model, StreamFunction, StreamOptions, ToolChoice } from "../types";
+export interface OllamaChatOptions extends StreamOptions {
+    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    toolChoice?: ToolChoice;
+}
+type OllamaFunctionTool = {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+};
+type OllamaMessage = {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    images?: string[];
+    thinking?: string;
+    tool_calls?: Array<{
+        type: "function";
+        function: {
+            index?: number;
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+    }>;
+    tool_name?: string;
+};
+export declare function createChatBody(model: Model<"ollama-chat">, context: Context, options: OllamaChatOptions | undefined): {
+    model: string;
+    messages: OllamaMessage[];
+    tools?: OllamaFunctionTool[] | undefined;
+    think?: "high" | "low" | "medium" | boolean | undefined;
+    tool_choice?: "auto" | "none" | "required" | undefined;
+    options?: {
+        num_predict: number;
+    } | undefined;
+    stream: boolean;
+};
+export declare const streamOllama: StreamFunction<"ollama-chat">;
+export {};