@zpi-dev/agent-sdk 0.0.0-stage → 0.1.60

package/dist/types/ai/src/providers/discovery.d.ts

@@ -0,0 +1,14 @@
+import type { ProviderApi } from "../types.js";
+import type { DiscoveredModel, ProviderPresetId } from "./registry.js";
+export interface ModelDiscoveryInput {
+    preset?: ProviderPresetId;
+    api?: ProviderApi;
+    baseUrl?: string;
+    apiKey: string;
+}
+export interface ModelDiscoveryResult {
+    models: DiscoveredModel[];
+    source: "remote" | "catalog";
+    warning?: string;
+}
+export declare function fetchProviderModels(input: ModelDiscoveryInput, fetcher?: typeof fetch): Promise<ModelDiscoveryResult>;

package/dist/types/ai/src/providers/registry.d.ts

@@ -0,0 +1,155 @@
+import type { Model, ModelCompat, ProviderApi } from "../types.js";
+export interface DiscoveredModel {
+    id: string;
+    name?: string;
+    input?: ("text" | "image" | "video" | "pdf")[];
+    reasoning?: boolean;
+    contextWindow?: number;
+    maxTokens?: number;
+    compat?: ModelCompat;
+    thinkingLevelMap?: Model["thinkingLevelMap"];
+    defaultThinkingLevel?: Model["defaultThinkingLevel"];
+    availability?: "listed" | "unverified";
+    samplingParams?: Model["samplingParams"];
+    metadataSource?: "remote" | "catalog" | "defaults";
+}
+export declare const providerPresets: readonly [{
+    readonly id: "openai-chatgpt";
+    readonly name: "OpenAI（ChatGPT）";
+    readonly family: "openai";
+    readonly baseUrl: "https://api.openai.com/v1";
+    readonly envKeys: readonly [];
+    readonly catalog: "openai-chatgpt";
+}, {
+    readonly id: "openai-api";
+    readonly name: "OpenAI（API）";
+    readonly family: "openai";
+    readonly baseUrl: "https://api.openai.com/v1";
+    readonly envKeys: readonly ["OPENAI_API_KEY"];
+    readonly catalog: "openai-chatgpt";
+}, {
+    readonly id: "deepseek";
+    readonly name: "DeepSeek";
+    readonly family: "deepseek";
+    readonly baseUrl: "https://api.deepseek.com";
+    readonly envKeys: readonly ["DEEPSEEK_API_KEY"];
+    readonly catalog: "deepseek";
+}, {
+    readonly id: "zhipu-coding";
+    readonly name: "智谱（Coding Plan）";
+    readonly family: "zhipu";
+    readonly baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4";
+    readonly envKeys: readonly ["ZHIPU_API_KEY", "ZHIPU_CODING_API_KEY", "ZAI_CODING_CN_API_KEY"];
+    readonly catalog: "zai-coding-cn";
+}, {
+    readonly id: "zhipu-api";
+    readonly name: "智谱（API）";
+    readonly family: "zhipu";
+    readonly baseUrl: "https://open.bigmodel.cn/api/paas/v4";
+    readonly envKeys: readonly ["ZHIPU_PAYGO_API_KEY", "ZHIPU_STANDARD_API_KEY"];
+    readonly catalog: "zai";
+}, {
+    readonly id: "minimax-coding";
+    readonly name: "MiniMax（Coding Plan）";
+    readonly family: "minimax";
+    readonly baseUrl: "https://api.minimax.cn/v1";
+    readonly envKeys: readonly ["MINIMAX_API_KEY"];
+    readonly catalog: "minimax-cn";
+}, {
+    readonly id: "minimax-api";
+    readonly name: "MiniMax（API）";
+    readonly family: "minimax";
+    readonly baseUrl: "https://api.minimax.cn/v1";
+    readonly envKeys: readonly ["MINIMAX_PAYGO_API_KEY"];
+    readonly catalog: "minimax-cn";
+}, {
+    readonly id: "mimo-coding";
+    readonly name: "MiMo（Token Plan）";
+    readonly family: "mimo";
+    readonly baseUrl: "https://token-plan-cn.xiaomimimo.com/v1";
+    readonly envKeys: readonly ["MIMO_API_KEY", "XIAOMI_TOKEN_PLAN_CN_API_KEY"];
+    readonly catalog: "xiaomi-token-plan-cn";
+}, {
+    readonly id: "mimo-api";
+    readonly name: "MiMo（API）";
+    readonly family: "mimo";
+    readonly baseUrl: "https://api.xiaomimimo.com/v1";
+    readonly envKeys: readonly ["MIMO_PAYGO_API_KEY", "XIAOMI_API_KEY"];
+    readonly catalog: "xiaomi";
+}];
+export type ProviderPresetId = (typeof providerPresets)[number]["id"];
+export declare function getProviderPreset(id: string): {
+    readonly id: "openai-chatgpt";
+    readonly name: "OpenAI（ChatGPT）";
+    readonly family: "openai";
+    readonly baseUrl: "https://api.openai.com/v1";
+    readonly envKeys: readonly [];
+    readonly catalog: "openai-chatgpt";
+} | {
+    readonly id: "openai-api";
+    readonly name: "OpenAI（API）";
+    readonly family: "openai";
+    readonly baseUrl: "https://api.openai.com/v1";
+    readonly envKeys: readonly ["OPENAI_API_KEY"];
+    readonly catalog: "openai-chatgpt";
+} | {
+    readonly id: "deepseek";
+    readonly name: "DeepSeek";
+    readonly family: "deepseek";
+    readonly baseUrl: "https://api.deepseek.com";
+    readonly envKeys: readonly ["DEEPSEEK_API_KEY"];
+    readonly catalog: "deepseek";
+} | {
+    readonly id: "zhipu-coding";
+    readonly name: "智谱（Coding Plan）";
+    readonly family: "zhipu";
+    readonly baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4";
+    readonly envKeys: readonly ["ZHIPU_API_KEY", "ZHIPU_CODING_API_KEY", "ZAI_CODING_CN_API_KEY"];
+    readonly catalog: "zai-coding-cn";
+} | {
+    readonly id: "zhipu-api";
+    readonly name: "智谱（API）";
+    readonly family: "zhipu";
+    readonly baseUrl: "https://open.bigmodel.cn/api/paas/v4";
+    readonly envKeys: readonly ["ZHIPU_PAYGO_API_KEY", "ZHIPU_STANDARD_API_KEY"];
+    readonly catalog: "zai";
+} | {
+    readonly id: "minimax-coding";
+    readonly name: "MiniMax（Coding Plan）";
+    readonly family: "minimax";
+    readonly baseUrl: "https://api.minimax.cn/v1";
+    readonly envKeys: readonly ["MINIMAX_API_KEY"];
+    readonly catalog: "minimax-cn";
+} | {
+    readonly id: "minimax-api";
+    readonly name: "MiniMax（API）";
+    readonly family: "minimax";
+    readonly baseUrl: "https://api.minimax.cn/v1";
+    readonly envKeys: readonly ["MINIMAX_PAYGO_API_KEY"];
+    readonly catalog: "minimax-cn";
+} | {
+    readonly id: "mimo-coding";
+    readonly name: "MiMo（Token Plan）";
+    readonly family: "mimo";
+    readonly baseUrl: "https://token-plan-cn.xiaomimimo.com/v1";
+    readonly envKeys: readonly ["MIMO_API_KEY", "XIAOMI_TOKEN_PLAN_CN_API_KEY"];
+    readonly catalog: "xiaomi-token-plan-cn";
+} | {
+    readonly id: "mimo-api";
+    readonly name: "MiMo（API）";
+    readonly family: "mimo";
+    readonly baseUrl: "https://api.xiaomimimo.com/v1";
+    readonly envKeys: readonly ["MIMO_PAYGO_API_KEY", "XIAOMI_API_KEY"];
+    readonly catalog: "xiaomi";
+} | undefined;
+export declare function presetModels(id: string, api?: ProviderApi): DiscoveredModel[];
+export declare function usesChatGPTAuth(preset?: string): boolean;
+export declare function isLegacyOpenAIModel(id: string): boolean;
+export declare function providerApis(preset?: string): readonly ProviderApi[];
+export declare function providerApi(preset?: string, api?: ProviderApi): ProviderApi;
+export declare function providerBaseUrl(preset: string, api?: ProviderApi): string;
+export declare function discoverProviderCredentials(env: Record<string, string | undefined>): {
+    preset: "deepseek" | "mimo-api" | "mimo-coding" | "minimax-api" | "minimax-coding" | "openai-api" | "openai-chatgpt" | "zhipu-api" | "zhipu-coding";
+    envKey: "DEEPSEEK_API_KEY" | "MIMO_API_KEY" | "MIMO_PAYGO_API_KEY" | "MINIMAX_API_KEY" | "MINIMAX_PAYGO_API_KEY" | "OPENAI_API_KEY" | "XIAOMI_API_KEY" | "XIAOMI_TOKEN_PLAN_CN_API_KEY" | "ZAI_CODING_CN_API_KEY" | "ZHIPU_API_KEY" | "ZHIPU_CODING_API_KEY" | "ZHIPU_PAYGO_API_KEY" | "ZHIPU_STANDARD_API_KEY";
+    apiKey: string;
+}[];

package/dist/types/ai/src/stream.d.ts

@@ -0,0 +1,5 @@
+import type { Model, SimpleStreamOptions, TranscriptContext } from "./types.js";
+/** Provider and wire-protocol selection stays inside zpi-ai. Credentials resolve for every request. */
+export declare function streamSimple(model: Model, context: TranscriptContext, options?: SimpleStreamOptions & {
+    getApiKey?: (rejectedApiKey?: string) => Promise<string>;
+}): import("./types.js").AssistantMessageEventStream;

package/dist/types/ai/src/types.d.ts

@@ -0,0 +1,394 @@
+import type { TSchema } from "typebox";
+import type { AssistantMessageEventStream } from "./utils/event-stream.js";
+export type { AssistantMessageEventStream } from "./utils/event-stream.js";
+export type ProviderApi = "anthropic-messages" | "openai-completions" | "openai-responses";
+export type Api = ProviderApi | (string & {});
+export type CacheRetention = "none" | "short" | "long";
+export type ProviderEnv = Record<string, string>;
+export type ProviderHeaders = Record<string, string | null>;
+export interface ThinkingBudgets {
+    minimal?: number;
+    low?: number;
+    medium?: number;
+    high?: number;
+}
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | JsonObject;
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type ThinkingLevel = "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | (string & {});
+export interface ReasoningConfig {
+    levels: string[];
+    map: string;
+}
+export interface OpenAICompletionsCompat {
+    thinkingFormat?: "deepseek" | "zai";
+    structuredOutput?: "prompt" | "json_object" | "json_schema";
+    maxTokensField?: "max_tokens" | "max_completion_tokens";
+    supportsDeveloperRole?: boolean;
+    supportsReasoningEffort?: boolean;
+    supportsUsageInStreaming?: boolean;
+    requiresReasoningContentOnAssistantMessages?: boolean;
+}
+export declare const openAICompletionsCompatKeys: readonly ["thinkingFormat", "structuredOutput", "maxTokensField", "supportsDeveloperRole", "supportsReasoningEffort", "supportsUsageInStreaming", "requiresReasoningContentOnAssistantMessages"];
+/** Compatibility settings for Anthropic Messages-compatible APIs. */
+export interface AnthropicMessagesCompat {
+    /**
+     * Whether the provider accepts per-tool `eager_input_streaming`.
+     * When false, the Anthropic provider omits `tools[].eager_input_streaming`
+     * and sends the legacy `fine-grained-tool-streaming-2025-05-14` beta header
+     * for tool-enabled requests.
+     * Default: true.
+     */
+    supportsEagerToolInputStreaming?: boolean;
+    /** Whether the provider supports Anthropic long cache retention (`cache_control.ttl: "1h"`). Default: true. */
+    supportsLongCacheRetention?: boolean;
+    /**
+     * Whether to send the `x-session-affinity` header from `options.sessionId`
+     * when caching is enabled. Required for providers like Fireworks that use
+     * session affinity for prompt cache routing (requests to the same replica
+     * maximize cache hits).
+     * Default: false.
+     */
+    sendSessionAffinityHeaders?: boolean;
+    /** Session-affinity format. `"openrouter"` sends `x-session-id`; when unset, sends `x-session-affinity`. */
+    sessionAffinityFormat?: "openrouter";
+    /**
+     * Whether the provider supports Anthropic-style `cache_control` markers on
+     * tool definitions. When false, `cache_control` is omitted from tool params.
+     * Some Anthropic-compatible providers (e.g., Fireworks) do not support this
+     * field on tools and may reject or ignore it.
+     * Default: true.
+     */
+    supportsCacheControlOnTools?: boolean;
+    /**
+     * Whether the model accepts the Anthropic `temperature` request field.
+     * Claude Opus 4.7+ rejects non-default temperature values.
+     * Default: true.
+     */
+    supportsTemperature?: boolean;
+    /**
+     * Whether to force adaptive thinking (`thinking.type: "adaptive"` plus
+     * `output_config.effort`) regardless of the model id. Built-in models that
+     * require adaptive thinking set this in generated metadata. Custom
+     * Anthropic-compatible providers can set this to `true` for any model whose
+     * upstream requires the adaptive format. Set to `false` to
+     * opt out on overridden built-in models.
+     * Default: false.
+     */
+    forceAdaptiveThinking?: boolean;
+    /** Whether to replay empty thinking signatures as `signature: ""` instead of converting thinking to text. Default: false. */
+    allowEmptySignature?: boolean;
+    /** Whether the provider supports Anthropic strict tool schemas. Default: false; generated Anthropic models enable it explicitly. */
+    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;
+    /**
+     * Models Anthropic accepts in `fallbacks` for server-side refusal fallback,
+     * with local pricing metadata for returned fallback responses. When absent or
+     * empty, callers must omit `fallbacks`; Anthropic rejects the field for models
+     * with no permitted fallback targets.
+     */
+    allowedFallbackModels?: AnthropicAllowedFallbackModel[];
+}
+export interface AnthropicAllowedFallbackModel {
+    provider: string;
+    model: string;
+    cost: Model["cost"];
+}
+export type ModelCompat = OpenAICompletionsCompat & AnthropicMessagesCompat;
+export declare const anthropicMessagesCompatKeys: readonly ["supportsEagerToolInputStreaming", "supportsLongCacheRetention", "sendSessionAffinityHeaders", "sessionAffinityFormat", "supportsCacheControlOnTools", "supportsTemperature", "forceAdaptiveThinking", "allowEmptySignature", "supportsStrictTools", "supportsMidConvoEffort", "supportsMidConvoSystemMessages", "supportsMidConvoToolChanges", "allowedFallbackModels"];
+export interface Model<TApi extends Api = Api> {
+    id: string;
+    name: string;
+    api: TApi;
+    provider: string;
+    baseUrl: string;
+    auth?: "chatgpt";
+    input: ("text" | "image")[];
+    reasoning: boolean;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        tiers?: {
+            inputTokensAbove: number;
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+        }[];
+    };
+    contextWindow: number;
+    maxTokens: number;
+    headers?: Record<string, string>;
+    compat?: ModelCompat;
+    thinkingLevelMap?: Partial<Record<"off" | ThinkingLevel, string | JsonObject | null>>;
+    reasoningConfig?: ReasoningConfig;
+    defaultThinkingLevel?: "off" | ThinkingLevel;
+    samplingParams?: Record<string, unknown>;
+}
+export interface TextContent {
+    type: "text";
+    text: string;
+    textSignature?: string;
+    phase?: "commentary" | "partial_answer" | "final_answer";
+}
+export interface ThinkingContent {
+    type: "thinking";
+    thinking: string;
+    thinkingSignature?: string;
+    redacted?: boolean;
+}
+export interface ImageContent {
+    name?: string;
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export interface ToolCall {
+    type: "toolCall";
+    id: string;
+    name: string;
+    arguments: JsonObject;
+    thoughtSignature?: string;
+    namespace?: string;
+}
+export interface Tool<TParameters extends TSchema = TSchema> {
+    name: string;
+    description: string;
+    parameters: TParameters;
+    constrainedSampling?: {
+        type: "json_schema";
+        strict: "prefer" | "require";
+    };
+}
+export interface CacheControl {
+    type: "ephemeral";
+}
+export interface SystemMessage {
+    cacheControl?: CacheControl;
+    role: "system";
+    content: string | TextContent[];
+    timestamp: number;
+    sections?: Record<string, string | null>;
+    toolsAdded?: Tool[];
+    toolsRemoved?: {
+        name: string;
+    }[];
+}
+export interface ImageAttachment {
+    id: string;
+    name: string;
+    mimeType: string;
+    width: number;
+    height: number;
+    size: number;
+    warning?: string;
+}
+export interface FileAttachment {
+    id: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    path: string;
+}
+export type Attachment = ImageAttachment | FileAttachment;
+export interface UserGuide {
+    text: string;
+    fileReferences: string[];
+    attachments: Attachment[];
+}
+export interface UserMessage {
+    /** Stable identity for queued input; never sent as provider message content. */
+    inputId?: string;
+    /** Display-only provenance for a real user input accepted inside an existing run. */
+    userGuide?: UserGuide;
+    cacheControl?: CacheControl;
+    synthetic?: boolean;
+    role: "user";
+    content: string | (TextContent | ImageContent)[];
+    timestamp: number;
+}
+export interface Usage {
+    input: number;
+    /** Total generated tokens, including reasoning; `reasoning` is a breakdown, not an addition. */
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cacheWrite1h?: number;
+    reasoning?: number;
+    totalTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+}
+export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
+export interface ContextBreakdownItem {
+    source: "messages" | "system_tools" | "system_prompt" | "skills" | "other";
+    chars: number;
+}
+export interface AssistantMessage {
+    cacheControl?: CacheControl;
+    role: "assistant";
+    content: (TextContent | ThinkingContent | ToolCall)[];
+    api: Api;
+    provider: string;
+    model: string;
+    responseModel?: string;
+    responseId?: string;
+    providerThinkingLevel?: string;
+    thinkingLevel?: "off" | ThinkingLevel;
+    usage: Usage;
+    usageAvailable?: boolean;
+    cacheUsageAvailable?: boolean;
+    contextBreakdown?: ContextBreakdownItem[];
+    stopReason: StopReason;
+    errorMessage?: string;
+    errorDetails?: ModelFailure;
+    rawStopReason?: string;
+    diagnostics?: import("./utils/diagnostics.js").AssistantMessageDiagnostic[];
+    endTurn?: boolean;
+    timestamp: number;
+}
+export interface ModelFailure {
+    /** Undefined when structured facts cannot classify the failure. */
+    retryable?: boolean;
+    code?: string;
+    idleMs?: number;
+    timeoutMs?: number;
+    status?: number;
+    retryAfterMs?: number;
+}
+export interface ModelRetryStatus {
+    /** Defaults to automatic recovery when omitted by a provider. */
+    origin?: "manual" | "auto";
+    attempt: number;
+    maxRetries: number;
+    retryDelayMs: number;
+    errorStatus: number | null;
+}
+export interface ModelWaitStatus {
+    phase: "first_response" | "stream";
+    startedAt: number;
+}
+export interface ToolResultMessage {
+    cacheControl?: CacheControl;
+    role: "toolResult";
+    toolCallId: string;
+    toolName: string;
+    content: (TextContent | ImageContent)[];
+    details?: JsonValue;
+    isError: boolean;
+    timestamp: number;
+}
+export type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
+export interface Context {
+    systemPrompt?: string;
+    messages: Message[];
+    tools?: Tool[];
+}
+declare const transcriptBrand: unique symbol;
+export type TranscriptContext = {
+    messages: Message[];
+    readonly [transcriptBrand]: true;
+};
+/** A provider-reported token count paired with its own content interval, never wall-clock elapsed time. */
+export interface ModelPerformanceSample {
+    requestMs?: number;
+    ttftMs?: number;
+    outputTokens?: number;
+    generationMs?: number;
+}
+export interface StreamOptions {
+    /** Request-local media omission statistics; omitted when the request fits. Never sent to the provider. */
+    onMediaProjection?: (stats: import("./utils/media-policy.js").MediaBudgetStats) => void;
+    /** Move the tail cache breakpoint before the final request-local prompt on protocols with explicit boundaries. */
+    skipCacheWrite?: boolean;
+    /** Transient measurements from actual provider attempts; an empty sample starts a fresh attempt. */
+    onPerformance?: (sample: ModelPerformanceSample) => void;
+    /** Best available provider retention. Legacy OpenAI automatic caching cannot be disabled with "none". */
+    cacheRetention?: CacheRetention;
+    metadata?: Record<string, unknown>;
+    env?: ProviderEnv;
+    signal?: AbortSignal;
+    sessionId?: string;
+    apiKey?: string;
+    /** Optional conversation-owned Responses connection; dispose it with the conversation. */
+    responsesSession?: import("./api/responses-session.js").ResponsesSession;
+    /** Prepare request state with generate:false; never performs model generation or HTTP fallback. */
+    responsesWarmup?: boolean;
+    fetch?: typeof globalThis.fetch;
+    headers?: Record<string, string | null>;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    /** First meaningful model event deadline; defaults to 120s, <= 0 disables it. */
+    streamFirstResponseTimeoutMs?: number;
+    /** Model-event idle deadline after output starts; defaults to 300s, <= 0 disables it. */
+    streamIdleTimeoutMs?: number;
+    /** Absolute recovery deadline, independent of model-event activity. */
+    streamDeadlineMs?: number;
+    /** Retry this request without cancelling the enclosing agent turn. */
+    retrySignal?: AbortSignal;
+    /** Transient waiting state; emitted only after 15s without a meaningful model event. */
+    onModelWait?: (status: ModelWaitStatus | null) => void;
+    maxRetries?: number;
+    maxRetryDelayMs?: number;
+    onRetry?: (status: ModelRetryStatus | null) => void;
+    samplingParams?: Record<string, unknown>;
+    onPayload?: (payload: unknown, model: Model) => unknown | undefined | Promise<unknown | undefined>;
+    onResponse?: (response: {
+        status: number;
+        headers: Record<string, string>;
+    }, model: Model) => void | Promise<void>;
+}
+export interface SimpleStreamOptions extends StreamOptions {
+    reasoning?: "off" | ThinkingLevel;
+    thinkingBudgets?: ThinkingBudgets;
+    toolChoice?: "auto" | "none";
+}
+export type StreamFunction<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> = (model: Model<TApi>, context: TranscriptContext, options?: TOptions) => AssistantMessageEventStream;
+export type AssistantMessageEvent = {
+    type: "start";
+    partial: AssistantMessage;
+} | {
+    type: "reset";
+    partial: AssistantMessage;
+} | {
+    type: "text_start" | "thinking_start" | "toolcall_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "text_delta" | "thinking_delta" | "toolcall_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "text_end" | "thinking_end";
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    type: "toolcall_end";
+    contentIndex: number;
+    toolCall: ToolCall;
+    partial: AssistantMessage;
+} | {
+    type: "done";
+    reason: "stop" | "length" | "toolUse";
+    message: AssistantMessage;
+} | {
+    type: "error";
+    reason: "error" | "aborted";
+    error: AssistantMessage;
+};

package/dist/types/ai/src/utils/abort.d.ts

@@ -0,0 +1,2 @@
+/** Cancel a caller's wait without discarding shared work such as a rotating credential refresh. */
+export declare function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T>;

package/dist/types/ai/src/utils/context-breakdown.d.ts

@@ -0,0 +1,3 @@
+import type { ContextBreakdownItem, JsonObject } from "../types.js";
+/** ZCode's breakdown uses request content character proportions, independent of server token totals. */
+export declare function measureContextBreakdown(payload: JsonObject): ContextBreakdownItem[];

package/dist/types/ai/src/utils/cost.d.ts

@@ -0,0 +1,2 @@
+import type { Api, Model, Usage } from "../types.js";
+export declare function calculateCost<TApi extends Api>(model: Model<TApi>, usage: Usage): Usage["cost"];

package/dist/types/ai/src/utils/diagnostics.d.ts

@@ -0,0 +1,16 @@
+import type { JsonObject } from "../types.js";
+export interface DiagnosticErrorInfo {
+    name?: string;
+    message: string;
+    stack?: string;
+    code?: string | number;
+}
+export interface AssistantMessageDiagnostic {
+    type: string;
+    timestamp: number;
+    error?: DiagnosticErrorInfo;
+    details?: JsonObject;
+}
+export declare function appendAssistantMessageDiagnostic<T extends {
+    diagnostics?: AssistantMessageDiagnostic[];
+}>(message: T, diagnostic: AssistantMessageDiagnostic): void;

package/dist/types/ai/src/utils/error-body.d.ts

@@ -0,0 +1,24 @@
+export declare const MAX_PROVIDER_ERROR_BODY_CHARS = 4000;
+export interface NormalizedProviderError {
+    /** HTTP status code, when one could be extracted from the SDK error object. */
+    status?: number;
+    /** Raw HTTP body reason, already trimmed and truncated to the cap. */
+    body?: string;
+    /** `error.message`, or `safeJsonStringify(error)` for a non-`Error` throw. */
+    message: string;
+    /** True when `message` already contains the body (no separate body to add). */
+    messageCarriesBody: boolean;
+}
+export declare function normalizeProviderError(error: unknown): NormalizedProviderError;
+/**
+ * Compose a display string from a normalized error. When the message already
+ * carries the body (Anthropic / `@google/genai` happy path) or no body/status
+ * was extracted, the message is returned unchanged. Otherwise the status and
+ * body are surfaced, with an optional provider prefix.
+ *
+ * - no prefix: `"<status>: <body>"`
+ * - prefix:    `"<prefix> (<status>): <body>"`
+ */
+export declare function formatProviderError(norm: NormalizedProviderError, prefix?: string): string;
+export declare function truncateErrorText(text: string, maxChars: number): string;
+export declare function safeJsonStringify(value: unknown): string;

package/dist/types/ai/src/utils/estimate.d.ts

@@ -0,0 +1,16 @@
+import type { ImageContent, Message, TextContent, TranscriptContext, Usage } from "../types.js";
+export interface ContextUsageEstimate {
+    /** Estimated total context tokens. */
+    tokens: number;
+    /** Tokens reported by the most recent applicable assistant usage block. */
+    usageTokens: number;
+    /** Estimated tokens after the most recent applicable assistant usage block. */
+    trailingTokens: number;
+    /** Index of the applicable message that provided usage, or null when none exists. */
+    lastUsageIndex: number | null;
+}
+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: TranscriptContext | readonly Message[]): ContextUsageEstimate;

package/dist/types/ai/src/utils/event-stream.d.ts

@@ -0,0 +1,15 @@
+import type { AssistantMessage, AssistantMessageEvent } from "../types.js";
+/** Single-consumer protocol stream. The final result is independent of iteration. */
+export declare class AssistantMessageEventStream implements AsyncIterable<AssistantMessageEvent> {
+    private queue;
+    private head;
+    private waiter?;
+    private ended;
+    private resolveResult;
+    private finalResult;
+    push(event: AssistantMessageEvent): void;
+    end(result?: AssistantMessage): void;
+    result(): Promise<AssistantMessage>;
+    [Symbol.asyncIterator](): AsyncIterator<AssistantMessageEvent>;
+}
+export declare function createAssistantMessageEventStream(): AssistantMessageEventStream;

package/dist/types/ai/src/utils/guard-model-stream.d.ts

@@ -0,0 +1,3 @@
+import type { AssistantMessageEventStream, Model, SimpleStreamOptions } from "../types.js";
+/** ZCode's iterator watchdog adapted to ZPI's model-event boundary, including custom providers. */
+export declare function guardModelStream(model: Model, create: (options: SimpleStreamOptions) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>, options?: SimpleStreamOptions): AssistantMessageEventStream;

package/dist/types/ai/src/utils/headers.d.ts

@@ -0,0 +1 @@
+export declare function headersToRecord(headers: Headers): Record<string, string>;

package/dist/types/ai/src/utils/json-parse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Repairs malformed JSON string literals by:
+ * - escaping raw control characters inside strings
+ * - doubling backslashes before invalid escape characters
+ */
+export declare function repairJson(json: string): string;
+export declare function parseJsonWithRepair<T>(json: string): T;