indusagi 0.12.32 → 0.12.33

package/dist/types/facade/ml/kit/auth/types.d.ts

@@ -0,0 +1,67 @@
+import type { Api, Model } from "../../types.js";
+export type OAuthCredentials = {
+    /** The bearer token sent on API calls; it has a short lifetime. */
+    access: string;
+    /** Long-lived token used to mint a new access token once the current one expires. */
+    refresh: string;
+    /** Millisecond Unix timestamp at which the access token stops being valid. */
+    expires: number;
+    /** Millisecond Unix timestamp recording when the credential was issued. */
+    issuedAt?: number;
+    /** Identifier of the provider this credential belongs to. */
+    provider?: string;
+    [key: string]: unknown;
+};
+export declare function makeOAuthCredentials(access: string, refresh: string, expiresMs: number, extra?: Partial<OAuthCredentials>): OAuthCredentials;
+export type AuthProviderId = string;
+/** Compatibility spelling for {@link AuthProviderId}. Reach for AuthProviderId in new code. */
+export type OAuthProviderId = AuthProviderId;
+export type AuthInputPrompt = {
+    message: string;
+    placeholder?: string;
+    allowEmpty?: boolean;
+};
+/** Compatibility spelling for {@link AuthInputPrompt}. Reach for AuthInputPrompt in new code. */
+export type OAuthPrompt = AuthInputPrompt;
+export type AuthRedirectInfo = {
+    url: string;
+    instructions?: string;
+};
+export interface OAuthRefreshResult {
+    credentials: OAuthCredentials;
+    refreshed: boolean;
+}
+export interface OAuthFlowCallbacks {
+    onAuth: (info: AuthRedirectInfo) => void;
+    onPrompt: (prompt: AuthInputPrompt) => Promise<string>;
+    onManualCodeInput?: () => Promise<string>;
+}
+export interface OAuthFlowOptions {
+    onProgress?: (message: string) => void;
+    signal?: AbortSignal;
+}
+export type OAuthLoginCallbacks = OAuthFlowCallbacks & OAuthFlowOptions;
+export interface AuthProviderContract {
+    readonly id: OAuthProviderId;
+    readonly name: string;
+    /** Run the interactive sign-in and return credentials the caller should persist. */
+    login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+    /** Set when the flow stands up a local listener and can take a pasted code. */
+    usesCallbackServer?: boolean;
+    /** Swap a stale credential for a fresh one to store. */
+    refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials>;
+    /** Extract the string used as this provider's API key from a credential. */
+    getApiKey(credentials: OAuthCredentials): string;
+    /** Optional pass to tweak this provider's models — e.g. to point baseUrl at a tenant. */
+    modifyModels?(models: Model<Api>[], credentials: OAuthCredentials): Model<Api>[];
+}
+/** Compatibility spelling for {@link AuthProviderContract}. Reach for AuthProviderContract in new code. */
+export type OAuthProviderInterface = AuthProviderContract;
+/** Slim id/name/availability summary of a provider; the full contract is {@link AuthProviderContract}. */
+export interface OAuthProviderInfo {
+    id: OAuthProviderId;
+    name: string;
+    available: boolean;
+}
+export type OAuthTokenStatus = "valid" | "expired" | "missing";
+export declare function getTokenStatus(creds: OAuthCredentials | null | undefined): OAuthTokenStatus;

package/dist/types/facade/ml/kit/base-stream-handler.d.ts

@@ -0,0 +1,30 @@
+import type { AssistantMessage, StopReason } from "../types.js";
+import type { AssistantMessageEventStream } from "./event-stream.js";
+/** Shared state a stream handler operates on: the output message being built, the event stream it writes to, and an optional cancellation signal. */
+export interface StreamHandlerContext {
+    output: AssistantMessage;
+    stream: AssistantMessageEventStream;
+    signal?: AbortSignal;
+}
+/**
+ * Base template for provider-specific stream handlers. A subclass supplies
+ * {@link processStream} to map a provider's raw wire events onto the shared
+ * assistant-message stream, then signals completion through {@link done} or
+ * {@link fail}.
+ */
+export declare abstract class BaseStreamHandler<TContext extends StreamHandlerContext = StreamHandlerContext> {
+    protected readonly context?: TContext | undefined;
+    constructor(context?: TContext | undefined);
+    /** Subclass-provided routine that reads the provider stream and emits events. */
+    protected abstract processStream(): Promise<void>;
+    /** Begin draining the backing provider stream. */
+    run(): Promise<void>;
+    /** Close the stream cleanly: record the stop reason, then emit the final `done` event. */
+    protected done(reason: Extract<StopReason, "stop" | "length" | "toolUse">): void;
+    /**
+     * Close the stream after something went wrong. An aborted signal maps the
+     * stop reason to `aborted`; anything else maps it to `error`. The error
+     * text is recorded on the output before the terminal `error` event fires.
+     */
+    protected fail(error: unknown): void;
+}

package/dist/types/facade/ml/kit/event-stream.d.ts

@@ -0,0 +1,63 @@
+import type { AssistantMessage, AssistantMessageEvent, ToolCall } from "../types.js";
+export interface EventStreamOptions {
+    historyLimit?: number;
+}
+/**
+ * Generic producer/consumer channel: callers shove events in via `push` while
+ * downstream code reads them with `for await`. Whichever event matches
+ * `isComplete` flips the channel into a terminal state and settles a
+ * dedicated result promise (typed as `R`) using `extractResult`.
+ *
+ * Implementation-wise, every event lands in a single FIFO array. After each
+ * push (or when the channel is closed) we fire the optional "wake" callback
+ * that an idle iterator is parked on. The iterator itself maintains a private
+ * read cursor, flushes any backlog already sitting in the buffer, and only
+ * suspends on a freshly-armed wake promise once it has caught up to head and
+ * the channel hasn't been closed yet.
+ */
+export declare class EventStream<T, R = T> implements AsyncIterable<T> {
+    private isComplete;
+    private extractResult;
+    private options;
+    private buffer;
+    private closed;
+    private notify;
+    private finalResultPromise;
+    private resolveFinalResult;
+    private rejectFinalResult;
+    private history;
+    constructor(isComplete: (event: T) => boolean, extractResult: (event: T) => R, options?: EventStreamOptions);
+    /** Resume the iterator that is waiting on `notify`, when one exists. */
+    private wake;
+    push(event: T): void;
+    end(result?: R): void;
+    error(error: unknown): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    result(): Promise<R>;
+    resultWithTimeout(timeoutMs: number): Promise<R>;
+    filter(predicate: (event: T) => boolean): AsyncIterable<T>;
+    map<U>(mapper: (event: T) => U): AsyncIterable<U>;
+    getHistory(): readonly T[];
+    private pushHistory;
+}
+export declare class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+    constructor(options?: EventStreamOptions);
+    pushStart(partial: AssistantMessage): void;
+    pushTextStart(contentIndex: number, partial: AssistantMessage): void;
+    pushTextDelta(contentIndex: number, delta: string, partial: AssistantMessage): void;
+    pushTextEnd(contentIndex: number, content: string, partial: AssistantMessage): void;
+    pushThinkingStart(contentIndex: number, partial: AssistantMessage): void;
+    pushThinkingDelta(contentIndex: number, delta: string, partial: AssistantMessage): void;
+    pushThinkingEnd(contentIndex: number, content: string, partial: AssistantMessage): void;
+    pushToolCallStart(contentIndex: number, partial: AssistantMessage): void;
+    pushToolCallDelta(contentIndex: number, delta: string, partial: AssistantMessage): void;
+    pushToolCallEnd(contentIndex: number, toolCall: ToolCall, partial: AssistantMessage): void;
+    pushDone(reason: "stop" | "length" | "toolUse", message: AssistantMessage): void;
+    pushError(reason: "aborted" | "error", error: AssistantMessage): void;
+}
+/**
+ * Factory that hands back a fresh {@link AssistantMessageEventStream}
+ * instance. Using it (instead of `new`-ing the class yourself) keeps
+ * consumer code free of a direct dependency on the concrete constructor.
+ */
+export declare function createAssistantMessageEventStream(options?: EventStreamOptions): AssistantMessageEventStream;

package/dist/types/facade/ml/kit/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./base-stream-handler.js";
+export * from "./event-stream.js";
+export * from "./json-parse.js";
+export * from "./message-transform.js";
+export * from "./output-factory.js";
+export * from "./provider-adapter.js";
+export * from "./provider-client-builder.js";
+export * from "./provider-constants.js";
+export * from "./provider-consolidation.js";
+export * from "./provider-errors.js";
+export * from "./stream-event-helper.js";
+export * from "./stream-handler-types.js";
+export * from "./streaming-state-manager.js";
+export * from "./tool-converter.js";

package/dist/types/facade/ml/kit/json-parse.d.ts

@@ -0,0 +1,23 @@
+export interface StreamingJsonParseOptions {
+    fallbackValue?: unknown;
+    fallback?: unknown;
+    allowPartial?: boolean;
+    strict?: boolean;
+    trimInput?: boolean;
+}
+export interface StreamingJsonParseResult<T> {
+    value: T;
+    parsed: boolean;
+    ok?: boolean;
+    usedPartialParser: boolean;
+    error?: string;
+}
+export declare function parseStreamingJsonWithDiagnostics<T = any>(partialJson: string | undefined, options?: StreamingJsonParseOptions): StreamingJsonParseResult<T>;
+/**
+ * Convenience wrapper that returns just the decoded value from a possibly
+ * mid-stream JSON snippet. Internally it leans on the diagnostic variant —
+ * trying a strict `JSON.parse`, then a lenient partial-JSON pass, and finally
+ * yielding the configured fallback — so callers always get something usable
+ * back even when the input is still being streamed.
+ */
+export declare function parseStreamingJson<T = any>(partialJson: string | undefined, options?: StreamingJsonParseOptions): T;

package/dist/types/facade/ml/kit/message-transform.d.ts

@@ -0,0 +1,32 @@
+import type { TextContent, ImageContent } from "../types.js";
+/**
+ * Utility functions for converting message content back and forth between a
+ * flat string and an array of content blocks.
+ */
+/**
+ * Reduce content to plain text. Strings pass through unchanged; for a block
+ * array, the text blocks are concatenated with newline separators and any
+ * image blocks are discarded.
+ */
+export declare function messageContentToString(content: string | (TextContent | ImageContent)[]): string;
+/**
+ * Tell whether the content contains at least one image block.
+ */
+export declare function messageHasImages(content: string | (TextContent | ImageContent)[]): boolean;
+/**
+ * Return just the text blocks. A bare string is promoted to one text block.
+ */
+export declare function extractTextBlocks(content: string | (TextContent | ImageContent)[]): TextContent[];
+/**
+ * Return just the image blocks; a plain string produces an empty list.
+ */
+export declare function extractImageBlocks(content: string | (TextContent | ImageContent)[]): ImageContent[];
+/**
+ * Remove control characters so the text is wire-safe. NUL bytes are dropped
+ * first, followed by the rest of the C0 control range together with DEL.
+ */
+export declare function sanitizeContentString(text: string): string;
+/**
+ * Normalize newlines: turn every CRLF or standalone CR into a single LF.
+ */
+export declare function normalizeLineEndings(text: string): string;

package/dist/types/facade/ml/kit/output-factory.d.ts

@@ -0,0 +1,8 @@
+import type { Api, AssistantMessage, Model } from "../types.js";
+/**
+ * Create the initial empty assistant message that a streaming response builds
+ * upon: no content yet, the model's api/provider/id copied across, zeroed
+ * usage counters, a placeholder `stop` reason, and a timestamp of now. Each
+ * provider fills it in as events come through.
+ */
+export declare function createAssistantMessageOutput<TApi extends Api>(model: Model<TApi>): AssistantMessage;

package/dist/types/facade/ml/kit/overflow.d.ts

@@ -0,0 +1,9 @@
+import type { AssistantMessage } from "../types.js";
+export interface OverflowPatternConfig {
+    pattern: RegExp;
+    suggestion: string;
+}
+export declare const OVERFLOW_PATTERN_CONFIG: OverflowPatternConfig[];
+export declare function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean;
+export declare function getOverflowPatterns(): RegExp[];
+export declare function getOverflowSuggestion(errorMessage: string | undefined): string | undefined;

package/dist/types/facade/ml/kit/provider-adapter.d.ts

@@ -0,0 +1,56 @@
+import type { Api, Context, Model, StreamOptions } from "../types.js";
+import type { AssistantMessageEventStream } from "./event-stream.js";
+import type { StreamingStateManager } from "./streaming-state-manager.js";
+/**
+ * Generic adapter interface for streaming providers.
+ * Encapsulates provider-specific client, request building, and stream processing.
+ */
+export interface ProviderAdapter<TOptions extends StreamOptions = StreamOptions> {
+    /** API identifier (e.g., "anthropic-messages"). */
+    readonly api: Api;
+    /** Provider name (e.g., "anthropic"). */
+    readonly provider: string;
+    /** Model identifier. */
+    readonly model: Model<Api>;
+    /** Optional provider-specific options. */
+    readonly options?: TOptions;
+    /** Context (system prompt, messages, tools). */
+    readonly context: Context;
+    /** Stream to push events to. */
+    readonly stream: AssistantMessageEventStream;
+    /** Optional abort signal. */
+    readonly signal?: AbortSignal;
+    /** Streaming state manager (tracks output, usage, stop reason). */
+    state: StreamingStateManager;
+    /** Initialize the adapter (e.g., create client). */
+    initialize(): Promise<void> | void;
+    /** Build provider-specific request parameters. */
+    buildRequest(): unknown;
+    /** Execute the request and stream events. */
+    executeStream(): Promise<void>;
+    /** Cleanup resources after streaming completes. */
+    cleanup(): Promise<void> | void;
+}
+/**
+ * Base adapter with shared lifecycle and helper methods.
+ */
+export declare abstract class BaseProviderAdapter<TOptions extends StreamOptions = StreamOptions> implements ProviderAdapter<TOptions> {
+    readonly model: Model<Api>;
+    readonly context: Context;
+    readonly stream: AssistantMessageEventStream;
+    readonly options?: TOptions | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly api: Api;
+    readonly provider: string;
+    constructor(model: Model<Api>, context: Context, stream: AssistantMessageEventStream, options?: TOptions | undefined, signal?: AbortSignal | undefined);
+    /** To be set by subclasses during initialization. */
+    state: StreamingStateManager;
+    abstract initialize(): Promise<void> | void;
+    abstract buildRequest(): unknown;
+    abstract executeStream(): Promise<void>;
+    cleanup(): Promise<void> | void;
+    /** Check if aborted. */
+    protected isAborted(): boolean;
+    /** Emit error if aborted. */
+    protected throwIfAborted(): void;
+}

package/dist/types/facade/ml/kit/provider-client-builder.d.ts

@@ -0,0 +1,36 @@
+import type { Api } from "../types.js";
+/**
+ * Generic client configuration for provider HTTP clients.
+ */
+export interface ClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    defaultHeaders?: Record<string, string>;
+    timeout?: number;
+}
+/**
+ * Builder interface for creating provider clients.
+ */
+export interface ClientBuilder<TClient> {
+    build(config: ClientConfig): TClient;
+}
+/**
+ * Anthropic client builder.
+ */
+export declare class AnthropicClientBuilder implements ClientBuilder<any> {
+    build(config: ClientConfig): any;
+}
+/**
+ * OpenAI client builder.
+ */
+export declare class OpenAIClientBuilder implements ClientBuilder<any> {
+    build(config: ClientConfig): any;
+}
+/**
+ * Shared client factory that resolves builders by API.
+ */
+export declare class ProviderClientFactory {
+    private static builders;
+    static register<TClient>(api: Api, builder: ClientBuilder<TClient>): void;
+    static create<TClient>(api: Api, config: ClientConfig): TClient;
+}

package/dist/types/facade/ml/kit/provider-consolidation.d.ts

@@ -0,0 +1,3 @@
+import type { StopReason } from "../types.js";
+export declare function normalizeToolCallId(id: string, maxLengthOrModel?: number | unknown, ..._rest: unknown[]): string;
+export declare function mapStopReason(reason: string | null | undefined, provider?: string): StopReason;

package/dist/types/facade/ml/kit/provider-constants.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared constants for AI streaming providers.
+ */
+/** Default timeout for provider HTTP requests (milliseconds). */
+export declare const DEFAULT_PROVIDER_TIMEOUT = 30000;
+/** Default maximum number of retry attempts. */
+export declare const DEFAULT_MAX_RETRIES = 3;
+/** Base delay for exponential backoff (milliseconds). */
+export declare const DEFAULT_RETRY_DELAY_MS = 250;
+/** Maximum tokens in text content before truncation warnings. */
+export declare const DEFAULT_MAX_TEXT_TOKENS = 50000;
+/** Maximum size of thinking blocks before truncation (bytes). */
+export declare const DEFAULT_MAX_THINKING_BYTES = 100000;
+/** Standard system prompt for tool-use scenarios. */
+export declare const DEFAULT_TOOL_SYSTEM_PROMPT = "You are a helpful assistant with access to tools.";
+/** Anthropic-specific defaults. */
+export declare const ANTHROPIC_DEFAULT_MAX_TOKENS = 4096;
+export declare const ANTHROPIC_DEFAULT_THINKING_BUDGET = 10000;
+/** OpenAI-specific defaults. */
+export declare const OPENAI_DEFAULT_MAX_TOKENS = 4096;
+export declare const OPENAI_DEFAULT_TEMPERATURE = 0.7;
+/** Google-specific defaults. */
+export declare const GOOGLE_DEFAULT_MAX_TOKENS = 8192;
+export declare const GOOGLE_DEFAULT_TEMPERATURE = 0.8;
+/** Bedrock-specific defaults. */
+export declare const BEDROCK_DEFAULT_MAX_TOKENS = 4096;
+export declare const BEDROCK_DEFAULT_TEMPERATURE = 0.7;
+/** Tool-related defaults. */
+export declare const DEFAULT_TOOL_CALL_TIMEOUT = 60000;
+export declare const DEFAULT_MAX_TOOLS_PER_REQUEST = 128;
+/** Streaming batch sizes. */
+export declare const STREAMING_BATCH_SIZE_TEXT = 100;
+export declare const STREAMING_BATCH_SIZE_THINKING = 50;
+export declare const STREAMING_BATCH_SIZE_TOOL_CALL = 20;

package/dist/types/facade/ml/kit/provider-errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Common helpers used across streaming adapters when surfacing failures
+ * out of provider-specific error shapes into our unified domain types.
+ */
+import type { StopReason } from "../types.js";
+/**
+ * Canonical, provider-agnostic identifiers used to tag failure modes coming
+ * back from upstream LLM endpoints.
+ */
+export declare enum ProviderErrorCode {
+    /** Authentication failed (invalid API key). */
+    AUTHENTICATION_FAILED = "AUTHENTICATION_FAILED",
+    /** Rate limit exceeded. */
+    RATE_LIMITED = "RATE_LIMITED",
+    /** Request timed out. */
+    TIMEOUT = "TIMEOUT",
+    /** Network connection error. */
+    NETWORK_ERROR = "NETWORK_ERROR",
+    /** Invalid request parameters. */
+    INVALID_REQUEST = "INVALID_REQUEST",
+    /** Provider service unavailable. */
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
+    /** Content policy violation. */
+    CONTENT_FILTERED = "CONTENT_FILTERED",
+    /** Unknown or unexpected error. */
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Error type emitted by adapters once a raw provider error has been
+ * normalised; carries a coded reason plus the original payload for callers
+ * that want to drill deeper.
+ */
+export declare class ProviderError extends Error {
+    readonly code: ProviderErrorCode;
+    readonly originalError?: unknown | undefined;
+    constructor(message: string, code: ProviderErrorCode, originalError?: unknown | undefined);
+}
+/**
+ * Translates the assorted stop-reason strings different providers emit into
+ * the small closed StopReason enum the rest of the stack relies on.
+ */
+export declare function mapProviderStopReason(reason: string | null | undefined, provider: string): StopReason;
+/**
+ * Renders a human-readable string for any error value, tagging it with the
+ * provider name and embedding the error code when one is available.
+ */
+export declare function formatProviderError(error: unknown, providerName: string): string;
+/**
+ * Heuristic for whether a failure is worth another attempt: classified codes
+ * map directly, while generic errors are sniffed by message text.
+ */
+export declare function isRetryableError(error: unknown): boolean;

package/dist/types/facade/ml/kit/sanitize-unicode.d.ts

@@ -0,0 +1,2 @@
+export declare function sanitizeSurrogates(text: string): string;
+export declare function sanitizeUnknownUnicode<T>(value: T): T;

package/dist/types/facade/ml/kit/stream-event-helper.d.ts

@@ -0,0 +1,38 @@
+import type { AssistantMessage, TextContent, ThinkingContent, ToolCall } from "../types.js";
+import type { AssistantMessageEventStream } from "./event-stream.js";
+/** The content-block kinds that may appear while a response is being streamed. */
+export type StreamBlock = TextContent | ThinkingContent | ToolCall;
+/**
+ * Resolves which content block a streaming delta targets. Providers tag each
+ * block with an `index`; this tracker uses that tag to find the matching block
+ * (or its position) within a partially built assistant message.
+ */
+export declare class BlockTracker<TBlock extends StreamBlock = StreamBlock> {
+    private readonly blocks;
+    constructor(output: AssistantMessage);
+    findByIndex(index: number): (TBlock & {
+        index?: number;
+    }) | undefined;
+    findPositionByIndex(index: number): number;
+}
+/**
+ * Convenience facade over an {@link AssistantMessageEventStream}. Each method
+ * relays one lifecycle call and automatically tacks on the latest partial
+ * output, so provider handlers don't have to thread that argument through by
+ * hand every time.
+ */
+export declare class StreamEventHelper {
+    private readonly stream;
+    private readonly output;
+    constructor(stream: AssistantMessageEventStream, output: AssistantMessage);
+    start(): void;
+    textStart(contentIndex: number): void;
+    textDelta(contentIndex: number, delta: string): void;
+    textEnd(contentIndex: number, content: string): void;
+    thinkingStart(contentIndex: number): void;
+    thinkingDelta(contentIndex: number, delta: string): void;
+    thinkingEnd(contentIndex: number, content: string): void;
+    toolCallStart(contentIndex: number): void;
+    toolCallDelta(contentIndex: number, delta: string): void;
+    toolCallEnd(contentIndex: number, toolCall: ToolCall): void;
+}

package/dist/types/facade/ml/kit/stream-handler-types.d.ts

@@ -0,0 +1,46 @@
+import type { Api, AssistantMessage, Context, Model, StreamOptions } from "../types.js";
+import type { AssistantMessageEventStream } from "./event-stream.js";
+import type { StreamingStateManager } from "./streaming-state-manager.js";
+/**
+ * Type definitions reused across the various provider stream-handler classes.
+ */
+/**
+ * The full working set a handler operates with for one run: which model to
+ * call, the request context, the event stream to emit on, caller-supplied
+ * options, an optional abort signal, and the mutable state tracker.
+ */
+export interface StreamHandlerExecutionContext {
+    model: Model<Api>;
+    context: Context;
+    stream: AssistantMessageEventStream;
+    options?: StreamOptions;
+    signal?: AbortSignal;
+    state: StreamingStateManager;
+}
+/**
+ * A loosely typed request bag; individual providers refine it to their shape.
+ */
+export interface ProviderRequest {
+    [key: string]: unknown;
+}
+/**
+ * A loosely typed response bag; individual providers refine it to their shape.
+ */
+export interface ProviderResponse {
+    [key: string]: unknown;
+}
+/**
+ * Strongly typed scaffold for provider handlers. The model, context, stream,
+ * options, and abort signal are stored on construction, leaving subclasses to
+ * supply only {@link execute}.
+ */
+export declare abstract class TypedStreamHandler<TOptions extends StreamOptions = StreamOptions> {
+    protected readonly model: Model<Api>;
+    protected readonly context: Context;
+    protected readonly stream: AssistantMessageEventStream;
+    protected readonly options?: TOptions | undefined;
+    protected readonly signal?: AbortSignal | undefined;
+    constructor(model: Model<Api>, context: Context, stream: AssistantMessageEventStream, options?: TOptions | undefined, signal?: AbortSignal | undefined);
+    protected createStateManager(initialOutput: AssistantMessage): StreamingStateManager;
+    abstract execute(): AssistantMessageEventStream;
+}

package/dist/types/facade/ml/kit/streaming-state-manager.d.ts

@@ -0,0 +1,42 @@
+import type { AssistantMessage, StopReason, Usage } from "../types.js";
+/**
+ * Centralizes the mutable bits of an in-flight stream — the output message as
+ * it accumulates, usage counters, the stop reason, and a completion flag.
+ * Provider handlers lean on this single holder rather than tracking those
+ * pieces independently.
+ */
+export declare class StreamingStateManager {
+    /** The assistant message that grows in place as events arrive. */
+    readonly output: AssistantMessage;
+    private _stopReason;
+    private _isComplete;
+    /**
+     * @param initialOutput - Starting assistant message; this instance edits it directly.
+     */
+    constructor(initialOutput: AssistantMessage);
+    /**
+     * Fold the supplied usage values into the output's running totals.
+     *
+     * @param update - Partial set of usage counters to apply.
+     */
+    setUsage(update: Partial<Usage>): void;
+    /**
+     * Note why streaming stopped and reflect that choice onto the output.
+     *
+     * @param reason - The stop reason to remember.
+     */
+    setStopReason(reason: StopReason): void;
+    /** The most recently set stop reason. */
+    get stopReason(): StopReason;
+    /** Mark the stream as done. */
+    complete(): void;
+    /** True once the stream has been marked done. */
+    get isComplete(): boolean;
+    /**
+     * Mark the stream as failed: completes it, switches the stop reason to
+     * `error`, and records the failure text on the output.
+     *
+     * @param errorMessage - Human-readable description of the failure.
+     */
+    error(errorMessage: string): void;
+}

package/dist/types/facade/ml/kit/tool-converter.d.ts

@@ -0,0 +1,49 @@
+import type { Tool } from "../types.js";
+/**
+ * Shared conversion helpers for tool schemas across providers.
+ *
+ * This module provides utilities for converting between generic tool definitions
+ * and provider-specific tool schemas.
+ */
+/**
+ * Normalize tool name to provider-specific format.
+ *
+ * @param name - Original tool name.
+ * @param maxLength - Maximum length for the normalized name (default: 64).
+ * @returns Normalized tool name.
+ *
+ * Default implementation removes special characters and truncates to maxLength.
+ */
+export declare function normalizeToolName(name: string, maxLength?: number): string;
+/**
+ * Provider-agnostic tool schema shape.
+ */
+export interface ProviderToolSchema {
+    /** Tool name. */
+    name: string;
+    /** Tool description. */
+    description: string;
+    /** Tool parameters (JSON Schema). */
+    parameters: unknown;
+}
+/**
+ * Convert a generic tool to provider tool schema.
+ *
+ * @param tool - Generic tool definition.
+ * @returns Provider-specific tool schema.
+ */
+export declare function toProviderTool(tool: Tool): ProviderToolSchema;
+/**
+ * Convert a provider tool schema back to generic tool.
+ *
+ * @param schema - Provider-specific tool schema.
+ * @returns Generic tool definition.
+ */
+export declare function fromProviderTool(schema: ProviderToolSchema): Tool;
+/**
+ * Convert an array of generic tools to provider format.
+ *
+ * @param tools - Array of generic tool definitions.
+ * @returns Array of provider-specific tool schemas.
+ */
+export declare function convertTools(tools: Tool[]): ProviderToolSchema[];

package/dist/types/facade/ml/kit/typebox-helpers.d.ts

@@ -0,0 +1,24 @@
+import { type TSchema, type TUnsafe } from "@sinclair/typebox";
+type StringEnumOptions<T extends readonly string[]> = {
+    description?: string;
+    default?: T[number];
+};
+/**
+ * Constructs a TypeBox schema describing a fixed list of allowed string values,
+ * serialised in the plain `{ type: "string", enum: [...] }` shape. Several
+ * backends (notably Google's generative APIs) reject the richer `anyOf` /
+ * `const` JSON-Schema output that TypeBox would otherwise generate from
+ * `Type.Union` of `Type.Literal`s, so this helper is the safe wire-format.
+ *
+ * @example
+ * const Color = StringEnum(["red", "green", "blue"], { description: "Pick a color" });
+ * type Color = Static<typeof Color>; // "red" | "green" | "blue"
+ */
+export declare function StringEnum<T extends readonly string[]>(values: T, options?: StringEnumOptions<T>): TUnsafe<T[number]>;
+/**
+ * Returns a freshly-cloned, plain-object copy of the given schema so that the
+ * downstream validator compiler can ingest it without choking on non-POJO
+ * inputs that providers or tooling sometimes hand us.
+ */
+export declare function normalizeSchemaForValidation(schema: TSchema): TSchema;
+export {};