@code-yeongyu/senpi-ai 2026.9.30 → 2026.10.1-2

package/dist/types.d.ts

@@ -21,13 +21,17 @@ export type { SessionAffinityFormat } from "./openai-responses-compat.ts";
 export type OpenAIResponsesCompat = BaseOpenAIResponsesCompat & {
     /** Whether the model supports message-anchored `additional_tools` input items. Default: false. */
     supportsAdditionalTools?: boolean;
+    /** Whether the exact model accepts developer or system messages after the conversation has started. When false, later system messages are folded into the leading system message. Default: false; the generated model catalog enables it for verified models. */
+    supportsMidConvoSystemMessages?: boolean;
 };
 export type { AssistantMessageEventStream } from "./utils/event-stream.ts";
 export type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-codex-responses" | "cursor-agent" | "devin-agent" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex" | "pi-messages";
 export type Api = KnownApi | (string & {});
-export type KnownImagesApi = "openrouter-images" | "openai-images";
-export type ImagesApi = KnownImagesApi | (string & {});
-export type KnownProvider = "alibaba-token-plan" | "amazon-bedrock" | "ant-ling" | "anthropic" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "bai" | "openai-codex" | "chatgpt-subscription" | "ollama" | "cursor" | "radius" | "nvidia" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "opengateway" | "zai" | "zai-coding-cn" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "together" | "baseten" | "opencode" | "opencode-go" | "kimi-coding" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "qwen-token-plan" | "qwen-token-plan-cn" | "qwen-token-plan-individual" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp" | "venice";
+export type KnownImageApi = "openrouter-images" | "openai-images";
+export type ImageApi = KnownImageApi | (string & {});
+export type KnownClassifierApi = "typesafe-system-one" | "cloudflare-workers-ai-system-one" | "llama-cpp-classify";
+export type ClassifierApi = KnownClassifierApi | (string & {});
+export type KnownProvider = "alibaba-token-plan" | "amazon-bedrock" | "ant-ling" | "anthropic" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "bai" | "openai-codex" | "chatgpt-subscription" | "ollama" | "cursor" | "radius" | "typesafe" | "nvidia" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "opengateway" | "zai" | "zai-coding-cn" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "together" | "baseten" | "opencode" | "opencode-go" | "kimi-coding" | "meta" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "qwen-token-plan" | "qwen-token-plan-cn" | "qwen-token-plan-individual" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp" | "venice";
 export type ProviderId = KnownProvider | string;
 export type KnownImagesProvider = "openai" | "openrouter";
 export type ImagesProviderId = KnownImagesProvider | string;
@@ -61,6 +65,11 @@ export interface ThinkingBudgets {
     max?: number;
 }
 export type CacheRetention = "none" | "short" | "long";
+/**
+ * Best-effort prompt cache lifetime in seconds for each retention tier a request can ask for.
+ * A missing tier means the lifetime is unknown; pi does not warm such caches.
+ */
+export type ModelPromptCache = Partial<Record<Exclude<CacheRetention, "none">, number>>;
 export type Transport = "sse" | "websocket" | "websocket-cached" | "auto";
 /** Provider-scoped environment overrides. Values take precedence over process.env. */
 export type ProviderEnv = Record<string, string>;
@@ -151,6 +160,12 @@ export interface ProviderRequestOptions<TModel = Model<Api>> {
     maxRetryDelayMs?: number;
 }
 export interface StreamOptions extends ProviderRequestOptions<Model<Api>> {
+    /**
+     * Optional observer for each parsed provider stream event before Pi normalization.
+     * Event data is adapter-owned and must be treated as read-only.
+     * Adapter support is explicit; unsupported adapters do not invoke it.
+     */
+    onProviderStreamEvent?: (data: unknown, model: Model<Api>) => void | Promise<void>;
     temperature?: number;
     /**
      * Arbitrary sampling parameters merged into the request body as-is, after the named request
@@ -240,21 +255,33 @@ export type ApiStreamOptions<TApi extends Api> = TApi extends keyof ApiOptionsMa
  * `Provider.stream()` via `ApiStreamOptions`.
  */
 export interface ProviderStreams {
-    stream(model: Model<Api>, context: Context, options?: StreamOptions): AssistantMessageEventStream;
-    streamSimple(model: Model<Api>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+    stream(model: Model<Api>, context: TranscriptContext, options?: StreamOptions): AssistantMessageEventStream;
+    streamSimple(model: Model<Api>, context: TranscriptContext, options?: SimpleStreamOptions): AssistantMessageEventStream;
     fetchDeferred?(model: Model<Api>, handle: DeferredHandle, options?: DeferredFetchOptions): AssistantMessageEventStream;
     cancelDeferred?(model: Model<Api>, handle: DeferredHandle, options?: DeferredCancelOptions): Promise<void>;
 }
 /**
  * The uniform contract of an image-generation API implementation module:
  * every image API module under `src/api/` exports exactly `generateImages`,
- * so the module itself satisfies this interface. Lazy wrappers and image
- * provider factories pass these around as values.
+ * so the module itself satisfies this interface. Lazy wrappers and
+ * `createProvider({ images })` pass these around as values.
  */
 export interface ProviderImages {
-    generateImages(model: ImagesModel<ImagesApi>, context: ImagesContext, options?: ImagesOptions): Promise<AssistantImages>;
+    generateImages(model: ImageModel<ImageApi>, context: ImagesContext, options?: ImagesOptions): Promise<AssistantImages>;
 }
-export interface ImagesOptions extends ProviderRequestOptions<ImagesModel<ImagesApi>> {
+/** The uniform contract implemented by classifier API modules. */
+export interface ProviderClassifier {
+    classify(model: ClassifierModel<ClassifierApi>, context: ClassifierContext, options?: ClassifierOptions): Promise<ClassifierResult>;
+}
+export interface ClassifierOptions extends ProviderRequestOptions<ClassifierModel<ClassifierApi>> {
+    /**
+     * Divides the answer logits by this value before they are normalized into probabilities.
+     * Values above 1 soften the distribution; values below 1 sharpen it. Must be positive.
+     * APIs that cannot apply it ignore it.
+     */
+    temperature?: number;
+}
+export interface ImagesOptions extends ProviderRequestOptions<ImageModel<ImageApi>> {
     /**
      * Optional metadata to include in API requests.
      * Providers extract the fields they understand and ignore the rest.
@@ -295,9 +322,10 @@ export interface SimpleStreamOptions extends StreamOptions {
     serviceTier?: ServiceTierPreference;
 }
 /** Tier preferences a caller can express; providers map `"auto"` to their default lane. */
-export type ServiceTierPreference = "auto" | "flex" | "priority";
-export type StreamFunction<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> = (model: Model<TApi>, context: Context, options?: TOptions) => AssistantMessageEventStream;
-export type ImagesFunction<TApi extends ImagesApi = ImagesApi, TOptions extends ImagesOptions = ImagesOptions> = (model: ImagesModel<TApi>, context: ImagesContext, options?: TOptions) => Promise<AssistantImages>;
+export type ServiceTierPreference = "auto" | "flex" | "priority" | "ultrafast";
+export type StreamFunction<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> = (model: Model<TApi>, context: TranscriptContext, options?: TOptions) => AssistantMessageEventStream;
+export type ImagesFunction<TOptions extends ImagesOptions = ImagesOptions> = (model: ImageModel<ImageApi>, context: ImagesContext, options?: TOptions) => Promise<AssistantImages>;
+export type ClassifierFunction<TOptions extends ClassifierOptions = ClassifierOptions> = (model: ClassifierModel<ClassifierApi>, context: ClassifierContext, options?: TOptions) => Promise<ClassifierResult>;
 export interface TextSignatureV1 {
     v: 1;
     id: string;
@@ -337,7 +365,7 @@ export interface ToolCall {
     type: "toolCall";
     id: string;
     name: string;
-    arguments: Record<string, any>;
+    arguments: JsonObject;
     /** Set by text tool-call middleware when a truncated call could not be recovered. Carriers of `incomplete` MUST NOT be executed. */
     incomplete?: true;
     /** Error explaining why an incomplete tool call could not be recovered. */
@@ -403,9 +431,23 @@ export interface PromptCacheDiagnostics {
     comparisonReusableTokens?: number;
 }
 export type StopReason = "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";
-export type JsonValue = null | boolean | number | string | JsonValue[] | {
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | JsonObject;
+export type JsonObject = {
     [key: string]: JsonValue;
 };
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type IsExactlyJsonValue<T> = [T] extends [JsonValue] ? ([JsonValue] extends [T] ? true : false) : false;
+type IsJsonProperty<T> = IsAny<T> extends true ? false : unknown extends T ? false : [Exclude<T, undefined>] extends [never] ? true : IsJsonCompatible<Exclude<T, undefined>>;
+type InvalidJsonKeys<T extends object> = {
+    [TKey in keyof T]-?: TKey extends string | number ? (IsJsonProperty<T[TKey]> extends true ? never : TKey) : TKey;
+}[keyof T];
+type IsJsonCompatible<T> = IsAny<T> extends true ? false : unknown extends T ? false : IsExactlyJsonValue<T> extends true ? true : T extends null | boolean | number | string ? true : T extends undefined ? false : T extends readonly (infer TItem)[] ? IsJsonCompatible<TItem> : T extends (...args: never[]) => unknown ? false : T extends object ? [InvalidJsonKeys<T>] extends [never] ? true : false : false;
+/** The JSON representation of a typed in-memory value. Optional object properties remain optional. */
+export type JsonRepresentation<T> = IsAny<T> extends true ? JsonValue : unknown extends T ? JsonValue : [T] extends [JsonValue] ? T : T extends readonly unknown[] ? {
+    [TKey in keyof T]: JsonRepresentation<Exclude<T[TKey], undefined>>;
+} : T extends object ? {
+    [TKey in keyof T]: JsonRepresentation<Exclude<T[TKey], undefined>>;
+} : never;
 export interface DeferredHandle {
     provider: string;
     modelId: string;
@@ -423,6 +465,33 @@ export type AssistantStopDetails = {
 } | {
     type: "sensitive";
 };
+/**
+ * System instructions and tool declarations at one point in the transcript.
+ *
+ * The leading system message is the system prompt. Later system messages change it:
+ * `content` adds instructions from that point on, `sections` replace or remove named
+ * prompt sections, and `toolsAdded`/`toolsRemoved` change the tool set. Replaying
+ * every system message in order yields the current prompt and tools. Providers that
+ * accept system messages mid-conversation send each one in place; other providers
+ * rebuild the leading system message from the replayed state.
+ */
+export interface SystemMessage {
+    role: "system";
+    /** Instruction text. On the leading message this is the base prompt; later, additional instructions. */
+    content: string | TextContent[];
+    /**
+     * Named, ordered prompt sections rendered verbatim after `content`. The leading message
+     * declares them; later messages replace sections by name, and `null` removes one. Keep
+     * each section self-delimiting (a tag, a heading) so the model can relate an update to
+     * the original. Avoid integer-like names; JSON objects reorder those.
+     */
+    sections?: Record<string, string | null>;
+    /** Complete definitions of tools that become available at this point. */
+    toolsAdded?: Tool[];
+    /** Tools that stop being available at this point. */
+    toolsRemoved?: ToolReference[];
+    timestamp: number;
+}
 export interface UserMessage {
     role: "user";
     content: string | (TextContent | ImageContent)[];
@@ -445,6 +514,8 @@ export interface AssistantMessage {
     responseId?: string;
     /** Exact provider-native effort level used for this response. Absent for legacy or unmanaged responses. */
     providerThinkingLevel?: string;
+    /** Pi thinking level the agent loop requested for this response. Absent outside the agent loop and for legacy responses. */
+    thinkingLevel?: ModelThinkingLevel;
     diagnostics?: AssistantMessageDiagnostic[];
     /** Provider prompt-cache comparison against the previous response of the same model, when reported. */
     promptCacheDiagnostics?: PromptCacheDiagnostics;
@@ -465,24 +536,45 @@ export interface AssistantMessage {
     endTurn?: boolean;
     timestamp: number;
 }
-export interface ToolResultMessage<TDetails = any> {
+/** A tool call that another tool made while it ran, for example from a codemode script. */
+export interface NestedToolCallRecord {
+    id: string;
+    name: string;
+    /** Omitted when over the size limits; `argumentsBytes` then gives their size. */
+    arguments?: JsonObject;
+    /** UTF-8 size of the arguments as JSON, set when `arguments` is omitted. */
+    argumentsBytes?: number;
+    /** `unfinished`: the call was still running when the calling tool finished. */
+    status: "ok" | "error" | "unfinished";
+    durationMs?: number;
+    /** Error text, truncated. */
+    error?: string;
+}
+/** Bounded record of the nested calls a tool made. Results are not recorded. */
+export interface NestedToolCalls {
+    calls: NestedToolCallRecord[];
+    /** False when calls were dropped, arguments omitted, or calls had not finished. */
+    complete: boolean;
+}
+export type ToolResultMessage<TDetails = JsonValue> = IsJsonCompatible<TDetails> extends true ? {
     role: "toolResult";
     toolCallId: string;
     toolName: string;
     content: (TextContent | ImageContent)[];
-    details?: TDetails;
+    details?: JsonRepresentation<TDetails>;
     /** Usage from the tool execution itself, if available. Not part of main LLM context accounting. */
     usage?: Usage;
+    /** Calls this tool made to other tools. Kept for the session record; not sent to the model. */
+    nestedCalls?: NestedToolCalls;
     /**
-     * Names from `Context.tools` that became available after this result.
-     * Providers with native deferred tool loading use this as the load point;
-     * other providers ignore it and use `Context.tools` normally.
+     * Names from `Context.tools` that became available after this result. Fork tool-search
+     * native deferred loading (tool_reference / tool_search / kimi) uses this as the load point.
      */
     addedToolNames?: string[];
     isError: boolean;
     timestamp: number;
-}
-export type Message = UserMessage | AssistantMessage | ToolResultMessage | ConfigurationUpdateMessage;
+} : never;
+export type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage | ConfigurationUpdateMessage;
 export type ImagesInputContent = TextContent | ImageContent;
 export type ImagesOutputContent = TextContent | ImageContent;
 export interface ImagesContext {
@@ -490,8 +582,8 @@ export interface ImagesContext {
 }
 export type ImagesStopReason = "stop" | "error" | "aborted";
 export interface AssistantImages {
-    api: ImagesApi;
-    provider: ImagesProviderId;
+    api: ImageApi;
+    provider: ProviderId;
     model: string;
     output: ImagesOutputContent[];
     responseId?: string;
@@ -502,6 +594,57 @@ export interface AssistantImages {
     errorMessage?: string;
     timestamp: number;
 }
+export interface ClassifierChoiceQuestion {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string>;
+}
+export interface ClassifierScoreQuestion {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+}
+export interface ClassifierBoolQuestion {
+    type: "bool";
+    instructions: string;
+    criteria: {
+        true: string;
+        false: string;
+    };
+}
+export type ClassifierQuestion = ClassifierChoiceQuestion | ClassifierScoreQuestion | ClassifierBoolQuestion;
+export interface ClassifierContext {
+    state: JsonObject;
+    questions: Record<string, ClassifierQuestion>;
+}
+export interface ClassifierChoiceAnswer {
+    type: "choice";
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence: number;
+}
+export interface ClassifierScoreAnswer {
+    type: "score";
+    score: number;
+    confidence: number;
+}
+export interface ClassifierBoolAnswer {
+    type: "bool";
+    probability: number;
+}
+export type ClassifierAnswer = ClassifierChoiceAnswer | ClassifierScoreAnswer | ClassifierBoolAnswer;
+export type ClassifierStopReason = "stop" | "error" | "aborted";
+export interface ClassifierResult {
+    api: ClassifierApi;
+    provider: ProviderId;
+    model: string;
+    answers: Record<string, ClassifierAnswer>;
+    /** Token usage and its cost at the model's catalog price, when the service reports token counts. */
+    usage?: Usage;
+    stopReason: ClassifierStopReason;
+    errorMessage?: string;
+    timestamp: number;
+}
 import type { TSchema } from "typebox";
 export interface FreeformToolFormat {
     type: "grammar";
@@ -532,6 +675,15 @@ export interface Tool<TParameters extends TSchema = TSchema> {
     freeform?: FreeformToolFormat;
     constrainedSampling?: false | ConstrainedSamplingConfig;
 }
+export interface ToolReference {
+    name: string;
+}
+/**
+ * Request input accepted by the public stream entry points (`Models.stream()`,
+ * `streamSimple()`, ...). `systemPrompt` and `tools` are shorthand for a leading
+ * system message; `normalizeContext()` folds them into one before the request
+ * reaches a provider.
+ */
 export interface Context {
     systemPrompt?: string;
     messages: Message[];
@@ -543,6 +695,19 @@ export interface Context {
      */
     activeToolNames?: string[];
 }
+declare const transcriptContextBrand: unique symbol;
+/**
+ * Normalized request context passed to providers and API implementations. The
+ * prompt and tool declarations are carried by the transcript's system messages.
+ * Only `normalizeContext()` produces this type, so a raw `Context` cannot reach
+ * provider code by accident.
+ */
+export type TranscriptContext = {
+    messages: Message[];
+    /** Carried from `Context.activeToolNames` by `normalizeContext()` (senpi#2095); absent means every declared tool is callable. */
+    activeToolNames?: string[];
+    readonly [transcriptContextBrand]: true;
+};
 /**
  * Event protocol for AssistantMessageEventStream.
  *
@@ -676,7 +841,11 @@ export interface OpenAICompletionsCompat {
     supportsThinkingTokenBudget?: boolean;
     /** Whether the provider supports OpenAI custom tools with Lark/regex grammar formats. When false, grammar-constrained tools fall back to normal function tools. Default: false; the generated model catalog enables it for capable models. */
     supportsOpenAIGrammarTools?: boolean;
-    /** Whether the provider supports the `strict` field in tool definitions. Default: true. */
+    /** Whether the exact model accepts system or developer messages after the conversation has started. When false, later system messages are folded into the leading system message. Default: false; the generated model catalog enables it for verified models. */
+    supportsMidConvoSystemMessages?: boolean;
+    /** Whether system messages can introduce additional tools mid-conversation. Requires `supportsMidConvoSystemMessages`. Default: false; the generated model catalog enables it for capable models. */
+    supportsMidConvoToolAdditions?: boolean;
+    /** Whether the provider supports the `strict` field in tool definitions. Default: false; generated capable models enable it explicitly. */
     supportsStrictMode?: boolean;
     /**
      * Provider-specific JSON Schema flavor for tool parameters. `"moonshot-mfjs"`
@@ -693,7 +862,7 @@ export interface OpenAICompletionsCompat {
     cacheControlFormat?: "anthropic";
     /** Whether to send session-affinity data from `options.sessionId`. Default: true for OpenRouter endpoints, false otherwise. */
     sendSessionAffinityHeaders?: boolean;
-    /** Provider-specific deferred tool serialization mode. */
+    /** Provider-specific deferred tool serialization mode (fork tool-search native loading). */
     deferredToolsMode?: "kimi";
     /** Session-affinity header format: `openai` sends `session_id`, `x-client-request-id`, and `x-session-affinity`; `openai-nosession` sends `x-client-request-id` and `x-session-affinity`; `openrouter` sends `x-session-id`. Does not affect the `prompt_cache_key` body param, which is governed by cache retention. Default: auto-detected. */
     sessionAffinityFormat?: SessionAffinityFormat;
@@ -783,6 +952,10 @@ export interface AnthropicMessagesCompat {
     supportsStrictTools?: boolean;
     /** Whether the exact model transport supports effort-only system messages and thinking binding controls. Default: false. */
     supportsMidConvoEffort?: boolean;
+    /** Whether the exact model accepts system-role messages inside the conversation. When false, later system messages are folded into the top-level system prompt. Default: false. */
+    supportsMidConvoSystemMessages?: boolean;
+    /** Whether the exact model accepts mid-conversation `tool_addition` and `tool_removal` blocks. Requires `supportsMidConvoSystemMessages`. Default: false. */
+    supportsMidConvoToolChanges?: boolean;
     /**
      * How to replay thinking blocks that have no usable Anthropic signature.
      * `"text"` demotes them to text; `"empty-signature"` preserves Anthropic's
@@ -818,6 +991,11 @@ export interface BedrockCompat {
     /** Whether the model supports Bedrock strict tool schemas. Default: false. */
     supportsStrictMode?: boolean;
 }
+/** Compatibility settings for the Mistral chat API. */
+export interface MistralConversationsCompat {
+    /** Whether the exact model accepts system messages after the conversation has started. When false, later system messages are folded into the leading system message. Default: false. */
+    supportsMidConvoSystemMessages?: boolean;
+}
 /**
  * OpenRouter provider routing preferences.
  * Controls which upstream providers OpenRouter routes requests to.
@@ -911,14 +1089,70 @@ export interface ModelCost extends ModelCostRates {
     /** Request-wide pricing tiers. The highest matching input threshold applies to the full request. */
     tiers?: ModelCostTier[];
 }
+export interface ModelImageResizeOptions {
+    maxWidth?: number;
+    maxHeight?: number;
+    /** Maximum base64-encoded payload size in bytes. */
+    maxBytes?: number;
+    jpegQuality?: number;
+}
+export interface ModelImageInputLimits {
+    /** Cache-safe resize profile applied before a new image enters conversation history. */
+    resize?: ModelImageResizeOptions;
+    /** Maximum images accepted in one provider message. */
+    maxPerMessage?: number;
+    /** Maximum images accepted across one provider request. */
+    maxPerRequest?: number;
+}
+export interface ModelInputLimits {
+    /** Maximum serialized provider request size in bytes. */
+    maxRequestBytes?: number;
+    images?: ModelImageInputLimits;
+}
+/** Fields shared by every catalog entry, regardless of what you can do with it. */
+export interface BaseModel<TApi extends string> {
+    id: string;
+    name: string;
+    api: TApi;
+    provider: ProviderId;
+    baseUrl: string;
+    /** `"video"` rides the image block for models that declare it (see `isVideoMimeType`). */
+    input: ("text" | "image" | "video")[];
+    /** Provider input limits and cache-safe preprocessing metadata. */
+    inputLimits?: ModelInputLimits;
+    cost: ModelCost;
+    headers?: Record<string, string>;
+}
 export interface ImagesModelCost extends ModelCost {
     /** $/million image input tokens (reference and edit inputs). Falls back to `input` when absent. */
     imageInput?: number;
 }
-export interface ImagesModel<TApi extends ImagesApi> extends Omit<Model<Api>, "api" | "provider" | "reasoning" | "contextWindow" | "maxTokens" | "compat" | "cost"> {
-    api: TApi;
-    provider: ImagesProviderId;
+/** Image-generation model: usable with `generateImages()` only. */
+export interface ImageModel<TApi extends ImageApi> extends BaseModel<TApi> {
+    type: "image";
+    /** Output modalities. Always includes `"image"`; `"text"` means the model can also return text blocks. */
     output: ("text" | "image")[];
     cost: ImagesModelCost;
 }
+/** Fork alias of {@link KnownImageApi}. */
+export type KnownImagesApi = KnownImageApi;
+/** Fork alias of {@link ImageApi}. */
+export type ImagesApi = ImageApi;
+/** Fork alias of {@link ImageModel}; entries must carry `type: "image"`. */
+export type ImagesModel<TApi extends ImageApi = ImageApi> = ImageModel<TApi>;
+/** Structured classifier model: usable with `classify()` only. */
+export interface ClassifierModel<TApi extends ClassifierApi> extends BaseModel<TApi> {
+    type: "classifier";
+    contextWindow: number;
+}
+/** Model shape for each model type. */
+export interface ModelTypeMap {
+    chat: Model<Api>;
+    image: ImageModel<ImageApi>;
+    classifier: ClassifierModel<ClassifierApi>;
+}
+/** What a catalog entry is for. Decides which `Models` operation accepts it. */
+export type ModelType = keyof ModelTypeMap;
+/** Anything a provider can list. Narrow with `isModelType()`. */
+export type AnyModel = ModelTypeMap[ModelType];
 //# sourceMappingURL=types.d.ts.map

package/dist/utils/diagnostics.d.ts

@@ -1,3 +1,4 @@
+import type { JsonObject } from "../types.ts";
 export interface DiagnosticErrorInfo {
     name?: string;
     message: string;
@@ -8,11 +9,11 @@ export interface AssistantMessageDiagnostic {
     type: string;
     timestamp: number;
     error?: DiagnosticErrorInfo;
-    details?: Record<string, unknown>;
+    details?: JsonObject;
 }
 export declare function formatThrownValue(value: unknown): string;
 export declare function extractDiagnosticError(error: unknown): DiagnosticErrorInfo;
-export declare function createAssistantMessageDiagnostic(type: string, error: unknown, details?: Record<string, unknown>): AssistantMessageDiagnostic;
+export declare function createAssistantMessageDiagnostic(type: string, error: unknown, details?: JsonObject): AssistantMessageDiagnostic;
 export declare function appendAssistantMessageDiagnostic<T extends {
     diagnostics?: AssistantMessageDiagnostic[];
 }>(message: T, diagnostic: AssistantMessageDiagnostic): void;

package/dist/utils/estimate.d.ts

@@ -1,4 +1,4 @@
-import type { Context, ImageContent, Message, TextContent, Usage } from "../types.ts";
+import type { ImageContent, Message, TextContent, TranscriptContext, Usage } from "../types.ts";
 export interface ContextUsageEstimate {
     /** Estimated total context tokens. */
     tokens: number;
@@ -13,5 +13,5 @@ export declare function calculateContextTokens(usage: Usage): number;
 export declare function estimateTextTokens(text: string): number;
 export declare function estimateTextAndImageContentTokens(content: string | Array<TextContent | ImageContent>): number;
 export declare function estimateMessageTokens(message: Message): number;
-export declare function estimateContextTokens(context: Context | readonly Message[]): ContextUsageEstimate;
+export declare function estimateContextTokens(context: TranscriptContext | readonly Message[]): ContextUsageEstimate;
 //# sourceMappingURL=estimate.d.ts.map

package/dist/utils/estimate.js

@@ -1,3 +1,5 @@
+import { getSystemMessageText } from "./text.js";
+import { getCurrentTools } from "./transcript.js";
 const CHARS_PER_TOKEN = 4;
 const ESTIMATED_IMAGE_CHARS = 4800;
 export function calculateContextTokens(usage) {
@@ -27,6 +29,11 @@ export function estimateTextAndImageContentTokens(content) {
 }
 export function estimateMessageTokens(message) {
     let chars = 0;
+    if (message.role === "system") {
+        return (estimateTextTokens(getSystemMessageText(message)) +
+            estimateToolsTokens(message.toolsAdded) +
+            estimateToolsTokens(message.toolsRemoved));
+    }
     if (message.role === "user")
         return estimateTextAndImageContentTokens(message.content);
     if (message.role === "toolResult")
@@ -70,11 +77,12 @@ function getLastAssistantUsageInfo(messages) {
     }
     return usageInfo;
 }
-function estimateMessages(messages) {
+export function estimateContextTokens(context) {
+    const messages = "messages" in context ? context.messages : context;
     const usageInfo = getLastAssistantUsageInfo(messages);
     if (usageInfo) {
         const usageTokens = calculateContextTokens(usageInfo.usage);
-        let trailingTokens = 0;
+        let trailingTokens = estimateLazilyAddedToolsTokens(messages, usageInfo.index);
         for (let i = usageInfo.index + 1; i < messages.length; i++) {
             trailingTokens += estimateMessageTokens(messages[i]);
         }
@@ -85,37 +93,21 @@ function estimateMessages(messages) {
         tokens += estimateMessageTokens(message);
     return { tokens, usageTokens: 0, trailingTokens: tokens, lastUsageIndex: null };
 }
+/**
+ * Tools a later tool result activated (`addedToolNames`, fork lazy activation) are declared in the
+ * leading system message, before the last billed usage, yet were never billed: count them as trailing.
+ */
+function estimateLazilyAddedToolsTokens(messages, lastUsageIndex) {
+    const addedNames = new Set(messages
+        .slice(lastUsageIndex + 1)
+        .flatMap((message) => (message.role === "toolResult" ? (message.addedToolNames ?? []) : [])));
+    if (addedNames.size === 0)
+        return 0;
+    return estimateToolsTokens(getCurrentTools(messages).filter((tool) => addedNames.has(tool.name)));
+}
 function estimateToolsTokens(tools) {
     if (!tools || tools.length === 0)
         return 0;
     return estimateTextTokens(safeJsonStringify(tools));
 }
-function isMessageArray(value) {
-    return Array.isArray(value);
-}
-export function estimateContextTokens(context) {
-    if (isMessageArray(context))
-        return estimateMessages(context);
-    const estimate = estimateMessages(context.messages);
-    if (estimate.lastUsageIndex !== null) {
-        const addedNames = new Set(context.messages
-            .slice(estimate.lastUsageIndex + 1)
-            .filter((message) => message.role === "toolResult")
-            .flatMap((message) => message.addedToolNames ?? []));
-        const addedToolTokens = estimateToolsTokens(context.tools?.filter((tool) => addedNames.has(tool.name)));
-        return {
-            tokens: estimate.tokens + addedToolTokens,
-            usageTokens: estimate.usageTokens,
-            trailingTokens: estimate.trailingTokens + addedToolTokens,
-            lastUsageIndex: estimate.lastUsageIndex,
-        };
-    }
-    const prefixTokens = (context.systemPrompt ? estimateTextTokens(context.systemPrompt) : 0) + estimateToolsTokens(context.tools);
-    return {
-        tokens: estimate.tokens + prefixTokens,
-        usageTokens: estimate.usageTokens,
-        trailingTokens: estimate.trailingTokens + prefixTokens,
-        lastUsageIndex: estimate.lastUsageIndex,
-    };
-}
 //# sourceMappingURL=estimate.js.map

package/dist/utils/headers.d.ts

@@ -1,4 +1,4 @@
 import type { ProviderHeaders } from "../types.ts";
 export declare function headersToRecord(headers: Headers): Record<string, string>;
-export declare function providerHeadersToRecord(headers: ProviderHeaders | undefined): Record<string, string> | undefined;
+export declare function providerHeadersToRecord(...headerSources: (ProviderHeaders | undefined)[]): Record<string, string> | undefined;
 //# sourceMappingURL=headers.d.ts.map

package/dist/utils/headers.js

@@ -5,14 +5,16 @@ export function headersToRecord(headers) {
     }
     return result;
 }
-export function providerHeadersToRecord(headers) {
-    if (!headers)
-        return undefined;
-    const result = {};
-    for (const [key, value] of Object.entries(headers)) {
-        if (value !== null)
-            result[key] = value;
+export function providerHeadersToRecord(...headerSources) {
+    const merged = new Map();
+    for (const source of headerSources) {
+        for (const [name, value] of Object.entries(source ?? {})) {
+            const normalizedName = name.toLowerCase();
+            merged.delete(normalizedName);
+            if (value !== null)
+                merged.set(normalizedName, [name, value]);
+        }
     }
-    return Object.keys(result).length > 0 ? result : undefined;
+    return merged.size > 0 ? Object.fromEntries(merged.values()) : undefined;
 }
 //# sourceMappingURL=headers.js.map

package/dist/utils/model-operations.d.ts

@@ -0,0 +1,11 @@
+import type { AnyModel, Api, AssistantImages, ClassifierApi, ClassifierModel, ClassifierResult, ImageApi, ImageModel, Model, ModelType, ModelTypeMap } from "../types.ts";
+/** The type of a model. Models without `type` are chat models. */
+export declare function getModelType(model: AnyModel): ModelType;
+/** Runtime-checked model type narrowing, including legacy chat models without `type`. */
+export declare function isModelType<TType extends ModelType>(model: AnyModel, type: TType): model is ModelTypeMap[TType];
+export declare function assertChatModel(model: AnyModel): asserts model is Model<Api>;
+export declare function assertImageModel(model: AnyModel): asserts model is ImageModel<ImageApi>;
+export declare function assertClassifierModel(model: AnyModel): asserts model is ClassifierModel<ClassifierApi>;
+export declare function imageErrorResult(model: ImageModel<ImageApi>, error: unknown, aborted?: boolean): AssistantImages;
+export declare function classifierErrorResult(model: ClassifierModel<ClassifierApi>, error: unknown, aborted?: boolean): ClassifierResult;
+//# sourceMappingURL=model-operations.d.ts.map