indusagi 0.13.7 → 0.13.8

package/dist/types/facade/ml/adapters/google.d.ts

@@ -0,0 +1,15 @@
+import { type ThinkingConfig } from "@google/genai";
+import type { SimpleStreamOptions, StreamFunction, StreamOptions } from "../types.js";
+import { type GoogleThinkingLevel } from "./google-shared.js";
+export interface GoogleOptions extends StreamOptions {
+    toolChoice?: "auto" | "none" | "any";
+    thinking?: {
+        enabled: boolean;
+        budgetTokens?: number;
+        level?: GoogleThinkingLevel;
+        /** @internal already-computed thinking config, reused as-is when present */
+        _resolved?: ThinkingConfig;
+    };
+}
+export declare const streamGoogle: StreamFunction<"google-generative-ai", GoogleOptions>;
+export declare const streamSimpleGoogle: StreamFunction<"google-generative-ai", SimpleStreamOptions>;

package/dist/types/facade/ml/adapters/kimi.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Adapter for Moonshot AI's Kimi models.
+ *
+ * Two providers are handled here:
+ *   - `kimi`        — the general Kimi API at https://api.kimi.moonshot.cn/v1
+ *   - `kimi-coding` — the coding-focused Kimi Code endpoint (a paid tier)
+ *
+ * Both speak an OpenAI-compatible chat-completions protocol.
+ */
+import type { SimpleStreamOptions, StreamFunction, StreamOptions } from "../types.js";
+export interface KimiOptions extends StreamOptions {
+    reasoningLevel?: "none" | "low" | "medium" | "high";
+}
+/**
+ * Streaming entry point for Kimi (OpenAI-compatible chat completions).
+ */
+export declare const streamKimi: StreamFunction<"kimi-openai-compatible", KimiOptions>;
+/**
+ * Convenience entry point that derives Kimi options from SimpleStreamOptions.
+ */
+export declare const streamSimpleKimi: StreamFunction<"kimi-openai-compatible", SimpleStreamOptions>;

package/dist/types/facade/ml/adapters/mock.d.ts

@@ -0,0 +1,9 @@
+import type { SimpleStreamOptions, StreamFunction, StreamOptions } from "../types.js";
+interface MockStreamOptions extends StreamOptions {
+    mockDelayMs?: number;
+    mockText?: string;
+    mockToolName?: string;
+}
+export declare const streamMock: StreamFunction<"mock-ai", MockStreamOptions>;
+export declare const streamSimpleMock: StreamFunction<"mock-ai", SimpleStreamOptions>;
+export {};

package/dist/types/facade/ml/adapters/nvidia.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Adapter for NVIDIA's hosted inference API.
+ *
+ * Endpoint: https://integrate.api.nvidia.com/v1 (OpenAI-compatible)
+ * Credentials are read from the NVIDIA_API_KEY environment variable.
+ */
+import type { SimpleStreamOptions, StreamFunction, StreamOptions } from "../types.js";
+export interface NvidiaOptions extends StreamOptions {
+    topP?: number;
+}
+export declare const streamNvidia: StreamFunction<"nvidia-openai-compatible", NvidiaOptions>;
+export declare const streamSimpleNvidia: StreamFunction<"nvidia-openai-compatible", SimpleStreamOptions>;

package/dist/types/facade/ml/adapters/openai-codex-responses.d.ts

@@ -0,0 +1,8 @@
+import type { SimpleStreamOptions, StreamFunction, StreamOptions } from "../types.js";
+export interface OpenAICodexResponsesOptions extends StreamOptions {
+    reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+    reasoningSummary?: "auto" | "concise" | "detailed" | "off" | "on" | null;
+    textVerbosity?: "low" | "medium" | "high";
+}
+export declare const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses", OpenAICodexResponsesOptions>;
+export declare const streamSimpleOpenAICodexResponses: StreamFunction<"openai-codex-responses", SimpleStreamOptions>;

package/dist/types/facade/ml/adapters/openai-completions.d.ts

@@ -0,0 +1,24 @@
+import type { ChatCompletionMessageParam } from "openai/resources/chat/completions.js";
+import type { Context, Model, OpenAICompletionsCompat, SimpleStreamOptions, StreamFunction, StreamOptions } from "../types.js";
+export interface OpenAICompletionsOptions extends StreamOptions {
+    toolChoice?: "auto" | "none" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh";
+    retryPolicy?: {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+    };
+}
+export declare class OpenAICompatibilityAdapter {
+    private readonly model;
+    constructor(model: Model<"openai-completions">);
+    resolveCompat(): OpenAICompletionsCompat;
+    normalizeToolCallId(id: string): string;
+}
+export declare const streamOpenAICompletions: StreamFunction<"openai-completions", OpenAICompletionsOptions>;
+export declare const streamSimpleOpenAICompletions: StreamFunction<"openai-completions", SimpleStreamOptions>;
+export declare function convertMessages(model: Model<"openai-completions">, context: Context, compat: Required<OpenAICompletionsCompat>): ChatCompletionMessageParam[];

package/dist/types/facade/ml/adapters/openai-responses-shared.d.ts

@@ -0,0 +1,25 @@
+import type { Tool as OpenAITool, ResponseCreateParamsStreaming, ResponseInput, ResponseStreamEvent } from "openai/resources/responses/responses.js";
+import type { Api, AssistantMessage, Context, Model, Tool, Usage } from "../types.js";
+import type { AssistantMessageEventStream } from "../kit/event-stream.js";
+import { type ProviderLifecycleHooks } from "./simple-options.js";
+export interface OpenAIResponsesStreamOptions {
+    serviceTier?: ResponseCreateParamsStreaming["service_tier"];
+    applyServiceTierPricing?: (usage: Usage, serviceTier: ResponseCreateParamsStreaming["service_tier"] | undefined) => void;
+}
+export interface OpenAIRequestExecutionOptions<TRequest = unknown, TResponse = unknown> {
+    hooks?: ProviderLifecycleHooks<TRequest, TResponse>;
+    retryPolicy?: {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+    };
+}
+export declare function executeOpenAIRequest<TRequest, TResponse>(request: TRequest, executor: () => Promise<TResponse>, options?: OpenAIRequestExecutionOptions<TRequest, TResponse>): Promise<TResponse>;
+export interface ConvertResponsesMessagesOptions {
+    includeSystemPrompt?: boolean;
+}
+export interface ConvertResponsesToolsOptions {
+    strict?: boolean | null;
+}
+export declare function convertResponsesMessages<TApi extends Api>(model: Model<TApi>, context: Context, allowedToolCallProviders: ReadonlySet<string>, options?: ConvertResponsesMessagesOptions): ResponseInput;
+export declare function convertResponsesTools(tools: Tool[], options?: ConvertResponsesToolsOptions): OpenAITool[];
+export declare function processResponsesStream<TApi extends Api>(openaiStream: AsyncIterable<ResponseStreamEvent>, output: AssistantMessage, stream: AssistantMessageEventStream, model: Model<TApi>, options?: OpenAIResponsesStreamOptions): Promise<void>;

package/dist/types/facade/ml/adapters/openai-responses.d.ts

@@ -0,0 +1,12 @@
+import type { ResponseCreateParamsStreaming } from "openai/resources/responses/responses.js";
+import type { SimpleStreamOptions, StreamFunction, StreamOptions } from "../types.js";
+export interface OpenAIResponsesOptions extends StreamOptions {
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh";
+    reasoningSummary?: "auto" | "detailed" | "concise" | null;
+    serviceTier?: ResponseCreateParamsStreaming["service_tier"];
+}
+/**
+ * Streaming entry point for the OpenAI Responses API.
+ */
+export declare const streamOpenAIResponses: StreamFunction<"openai-responses", OpenAIResponsesOptions>;
+export declare const streamSimpleOpenAIResponses: StreamFunction<"openai-responses", SimpleStreamOptions>;

package/dist/types/facade/ml/adapters/openai-scaffold.d.ts

@@ -0,0 +1,3 @@
+import { type SimpleStreamOptions, type StreamFunction, type StreamOptions } from "../types.js";
+export declare const streamOpenAICompletionsScaffold: StreamFunction<"openai-completions", StreamOptions>;
+export declare const streamSimpleOpenAICompletionsScaffold: StreamFunction<"openai-completions", SimpleStreamOptions>;

package/dist/types/facade/ml/adapters/register-builtins.d.ts

@@ -0,0 +1,2 @@
+export declare function registerBuiltInApiProviders(): void;
+export declare function resetApiProviders(): void;

package/dist/types/facade/ml/adapters/simple-options.d.ts

@@ -0,0 +1,39 @@
+import type { Api, Model, SimpleStreamOptions, StreamOptions, ThinkingBudgets, ThinkingLevel } from "../types.js";
+export interface ProviderLifecycleHooks<TRequest = unknown, TResponse = unknown> {
+    onBeforeRequest?: (request: TRequest) => void | Promise<void>;
+    onAfterResponse?: (response: TResponse) => void | Promise<void>;
+    onError?: (error: unknown) => void | Promise<void>;
+}
+export interface RetryPolicy {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs?: number;
+    /**
+     * When present, abort is checked between attempts and before each backoff
+     * sleep. A live request is short-circuited the moment its signal fires —
+     * but the presence of a signal no longer suppresses transient retries.
+     */
+    signal?: AbortSignal;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /**
+     * Returns the server-requested cooldown (e.g. a parsed `Retry-After`
+     * header) in milliseconds, or `null` when the error carries no such hint.
+     * When provided, it takes priority over exponential backoff (still clamped
+     * by `maxDelayMs`).
+     */
+    getRetryAfterMs?: (error: unknown) => number | null;
+}
+export declare class SimpleOptionsProviderError extends Error {
+    readonly code: "rate_limit" | "timeout" | "network" | "validation" | "auth" | "unknown";
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code?: "rate_limit" | "timeout" | "network" | "validation" | "auth" | "unknown", cause?: unknown | undefined);
+}
+export declare function normalizeProviderError(error: unknown): SimpleOptionsProviderError;
+export declare function executeWithRetry<T>(operation: () => Promise<T>, policy: RetryPolicy): Promise<T>;
+export declare function buildBaseOptions(model: Model<Api>, options?: SimpleStreamOptions, apiKey?: string): StreamOptions;
+export declare function clampReasoning(effort: ThinkingLevel | undefined): Exclude<ThinkingLevel, "xhigh"> | undefined;
+export declare function mapThinkingLevel(level: ThinkingLevel | undefined, provider?: "supports-xhigh" | "clamp-xhigh"): ThinkingLevel | Exclude<ThinkingLevel, "xhigh"> | undefined;
+export declare function adjustMaxTokensForThinking(baseMaxTokens: number, modelMaxTokens: number, reasoningLevel: ThinkingLevel, customBudgets?: ThinkingBudgets): {
+    maxTokens: number;
+    thinkingBudget: number;
+};

package/dist/types/facade/ml/adapters/simple-options.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/ml/adapters/transform-messages.d.ts

@@ -0,0 +1,23 @@
+import type { Api, AssistantMessage, Message, Model } from "../types.js";
+export interface MessageTransformContext<TApi extends Api> {
+    model: Model<TApi>;
+    normalizeToolCallId?: (id: string, model: Model<TApi>, source: AssistantMessage) => string;
+    debug?: (stage: string, details?: unknown) => void;
+}
+export interface MessageTransformation<TApi extends Api> {
+    name: string;
+    apply(messages: Message[], context: MessageTransformContext<TApi>): Message[];
+}
+export declare class MessageTransformationPipeline<TApi extends Api> {
+    private transformations;
+    addTransformation(transformation: MessageTransformation<TApi>): this;
+    transform(messages: Message[], context: MessageTransformContext<TApi>): Message[];
+}
+/**
+ * Push a conversation through the shared transformation pipeline so it can be
+ * sent to any provider safely. Tool-call identifiers are the tricky part: some
+ * providers hand back long ids that include characters like `|`, while others
+ * only accept short word-character ids. The `normalizeToolCallId` callback
+ * bridges those formats whenever messages cross a model or provider boundary.
+ */
+export declare function transformMessages<TApi extends Api>(messages: Message[], model: Model<TApi>, normalizeToolCallId?: (id: string, model: Model<TApi>, source: AssistantMessage) => string): Message[];

package/dist/types/facade/ml/api-registry.d.ts

@@ -0,0 +1,49 @@
+import type { Api, AssistantMessageEventStream, Context, Model, SimpleStreamOptions, StreamFunction, StreamOptions } from "./types.js";
+export type ApiStreamFunction = (model: Model<Api>, context: Context, options?: StreamOptions) => AssistantMessageEventStream;
+export type ApiStreamSimpleFunction = (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+export interface ApiProvider<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> {
+    api: TApi;
+    stream: StreamFunction<TApi, TOptions>;
+    streamSimple: StreamFunction<TApi, SimpleStreamOptions>;
+}
+export interface ApiProviderMetadata {
+    sourceId?: string;
+    version?: string;
+    enabled: boolean;
+    registeredAt: number;
+    updatedAt: number;
+}
+export interface RegisteredApiProvider {
+    provider: ApiProviderInternal;
+    metadata: ApiProviderMetadata;
+}
+export interface ApiProviderInternal {
+    api: Api;
+    stream: ApiStreamFunction;
+    streamSimple: ApiStreamSimpleFunction;
+}
+export interface RegisterApiProviderOptions {
+    sourceId?: string;
+    version?: string;
+    enabled?: boolean;
+}
+export declare class ProviderRegistry {
+    private readonly registry;
+    register<TApi extends Api, TOptions extends StreamOptions>(provider: ApiProvider<TApi, TOptions>, options?: RegisterApiProviderOptions): void;
+    get(api: Api): ApiProviderInternal | undefined;
+    getWithMetadata(api: Api): RegisteredApiProvider | undefined;
+    list(includeDisabled?: boolean): ApiProviderInternal[];
+    enable(api: Api): boolean;
+    disable(api: Api): boolean;
+    unregisterBySource(sourceId: string): void;
+    clear(): void;
+}
+export declare const providerRegistry: ProviderRegistry;
+export declare function registerApiProvider<TApi extends Api, TOptions extends StreamOptions>(provider: ApiProvider<TApi, TOptions>, sourceIdOrOptions?: string | RegisterApiProviderOptions): void;
+export declare function getApiProvider(api: Api): ApiProviderInternal | undefined;
+export declare function getApiProviderWithMetadata(api: Api): RegisteredApiProvider | undefined;
+export declare function getApiProviders(includeDisabled?: boolean): ApiProviderInternal[];
+export declare function enableApiProvider(api: Api): boolean;
+export declare function disableApiProvider(api: Api): boolean;
+export declare function unregisterApiProviders(sourceId: string): void;
+export declare function clearApiProviders(): void;

package/dist/types/facade/ml/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/facade/ml/env-api-keys.d.ts

@@ -0,0 +1,19 @@
+import type { KnownProvider } from "./types.js";
+export interface EnvApiKeyResolution {
+    provider: string;
+    apiKey?: string;
+    isAuthenticatedMarker: boolean;
+    isValid: boolean;
+}
+/**
+ * Resolve a provider's credential from the process environment.
+ *
+ * Most providers map to a single env var (such as OPENAI_API_KEY); a few use
+ * custom logic (Bedrock and Vertex return the SDK marker, Copilot/Anthropic
+ * accept token fallbacks). Returns undefined when nothing usable is configured.
+ */
+export declare function getEnvApiKey(provider: KnownProvider): string | undefined;
+export declare function getEnvApiKey(provider: string): string | undefined;
+export declare function isLikelyValidApiKey(value: string | undefined): boolean;
+export declare function resolveEnvApiKey(provider: KnownProvider | string): EnvApiKeyResolution;
+export declare function rotateEnvApiKey(provider: KnownProvider | string, fallback?: string): string | undefined;

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

@@ -0,0 +1,27 @@
+export * from "./api-registry.js";
+export * from "./env-api-keys.js";
+export * from "./models.generated.js";
+export * from "./models.js";
+export * from "./adapters/mock.js";
+export * from "./adapters/openai-scaffold.js";
+export * from "./adapters/anthropic.js";
+export * from "./adapters/azure-openai-responses.js";
+export * from "./adapters/google.js";
+export * from "./adapters/google-vertex.js";
+export * from "./adapters/openai-completions.js";
+export * from "./adapters/openai-responses.js";
+export * from "./adapters/openai-responses-shared.js";
+export * from "./adapters/openai-codex-responses.js";
+export * from "./adapters/amazon-bedrock.js";
+export * from "./adapters/kimi.js";
+export * from "./adapters/nvidia.js";
+export { executeGoogleRequest, convertTools, isThinkingPart, retainThoughtSignature, requiresToolCallId, mapToolChoice, mapStopReason, mapStopReasonString, type GoogleThinkingLevel, } from "./adapters/google-shared.js";
+export * from "./adapters/simple-options.js";
+export * from "./adapters/register-builtins.js";
+export * from "./stream.js";
+export * from "./types.js";
+export * from "./kit/index.js";
+export * from "./kit/auth/index.js";
+export * from "./kit/overflow.js";
+export * from "./kit/typebox-helpers.js";
+export * from "./kit/validation.js";

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

@@ -0,0 +1,17 @@
+/**
+ * Sign-in flow for Anthropic accounts (Claude Pro / Max) over OAuth + PKCE.
+ */
+import type { OAuthCredentials, OAuthProviderInterface } from "./types.js";
+/**
+ * Walk a user through Anthropic OAuth sign-in.
+ *
+ * @param onAuthUrl - Invoked with the authorization URL so the caller can open it.
+ * @param onPromptCode - Invoked to collect the authorization code from the user.
+ */
+export declare function loginAnthropic(onAuthUrl: (url: string) => void, onPromptCode: () => Promise<string>): Promise<OAuthCredentials>;
+/**
+ * Exchange an Anthropic refresh token for a renewed credential.
+ */
+export declare function refreshAnthropicToken(refreshToken: string): Promise<OAuthCredentials>;
+export declare function isAnthropicOAuthCredentialsValid(credentials: OAuthCredentials): boolean;
+export declare const anthropicOAuthProvider: OAuthProviderInterface;

package/dist/types/facade/ml/kit/auth/github-copilot.d.ts

@@ -0,0 +1,22 @@
+/**
+ * GitHub Copilot sign-in via the OAuth device-authorization grant.
+ */
+import type { OAuthCredentials, OAuthProviderInterface } from "./types.js";
+type LoginOptions = {
+    onAuth: (url: string, instructions?: string) => void;
+    onPrompt: (prompt: {
+        message: string;
+        placeholder?: string;
+        allowEmpty?: boolean;
+    }) => Promise<string>;
+    onProgress?: (message: string) => void;
+    signal?: AbortSignal;
+};
+export declare function normalizeDomain(raw: string): string | null;
+/** Module-level entry point for resolving the Copilot API base URL. */
+export declare function getGitHubCopilotBaseUrl(token?: string, enterpriseDomain?: string): string;
+export declare function refreshGitHubCopilotToken(refreshToken: string, enterpriseDomain?: string): Promise<OAuthCredentials>;
+export declare function loginGitHubCopilot(options: LoginOptions): Promise<OAuthCredentials>;
+export declare function isGitHubCopilotOAuthCredentialsValid(credentials: OAuthCredentials): boolean;
+export declare const githubCopilotOAuthProvider: OAuthProviderInterface;
+export {};

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

@@ -0,0 +1,50 @@
+/**
+ * Central place for OAuth-based provider authentication.
+ *
+ * Brings together sign-in, token renewal, and the provider registry for the
+ * providers that authenticate over OAuth:
+ * - Anthropic (Claude Pro / Max)
+ * - GitHub Copilot
+ * - ChatGPT (Codex)
+ * - Kimi (Moonshot AI)
+ */
+export { anthropicOAuthProvider, loginAnthropic, refreshAnthropicToken } from "./anthropic.js";
+export { getGitHubCopilotBaseUrl, githubCopilotOAuthProvider, loginGitHubCopilot, normalizeDomain, refreshGitHubCopilotToken, } from "./github-copilot.js";
+export { loginOpenAICodex, openaiCodexOAuthProvider, refreshOpenAICodexToken } from "./openai-codex.js";
+export { loginKimi, refreshKimiToken } from "./kimi.js";
+export * from "./types.js";
+import type { OAuthCredentials, OAuthProviderId, OAuthProviderInfo, OAuthProviderInterface, OAuthRefreshResult } from "./types.js";
+/**
+ * Look up a registered OAuth provider by its id.
+ */
+export declare function getOAuthProvider(id: OAuthProviderId): OAuthProviderInterface | undefined;
+/**
+ * Add (or replace) an OAuth provider in the registry.
+ */
+export declare function registerOAuthProvider(provider: OAuthProviderInterface): void;
+/**
+ * List every OAuth provider currently in the registry.
+ */
+export declare function getOAuthProviders(): OAuthProviderInterface[];
+/**
+ * @deprecated Prefer getOAuthProviders(), which returns the full provider objects.
+ */
+export declare function getOAuthProviderInfoList(): OAuthProviderInfo[];
+/**
+ * Renew a credential through whichever provider owns it.
+ * @deprecated Call getOAuthProvider(id).refreshToken() directly instead.
+ */
+export declare function refreshOAuthToken(providerId: OAuthProviderId, credentials: OAuthCredentials): Promise<OAuthCredentials>;
+/**
+ * Resolve a provider's API key from its stored OAuth credential, renewing the
+ * credential first when it has already expired.
+ *
+ * @returns The API key plus the (possibly refreshed) credential, or null when no
+ *          credential exists for the provider.
+ * @throws When a refresh is needed but fails.
+ */
+export declare function getOAuthApiKey(providerId: OAuthProviderId, credentials: Record<string, OAuthCredentials>): Promise<{
+    newCredentials: OAuthCredentials;
+    apiKey: string;
+} | null>;
+export declare function ensureFreshOAuthCredentials(providerId: OAuthProviderId, credentials: OAuthCredentials): Promise<OAuthRefreshResult>;

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

@@ -0,0 +1,23 @@
+/**
+ * Kimi (Moonshot AI) authenticates with an API key — there is no OAuth path.
+ *
+ * Provide the key through the KIMI_API_KEY or MOONSHOT_API_KEY environment
+ * variables, or hand it directly to the CLI with --api-key.
+ *
+ * Where to obtain a key:
+ *   Standard Kimi:  https://www.moonshot.cn/
+ *   Kimi Code:      https://www.kimi.com/code/en
+ */
+import type { OAuthCredentials } from "./types.js";
+/**
+ * Placeholder login that never succeeds: Kimi is key-based, not OAuth-based.
+ * Kept on the surface for symmetry; prefer getEnvApiKey("kimi") in practice.
+ * @throws Always — there is no OAuth flow for Kimi.
+ */
+export declare function loginKimi(): Promise<OAuthCredentials>;
+/**
+ * Not applicable — API keys do not expire, so there is nothing to refresh.
+ * @throws Always
+ */
+export declare function refreshKimiToken(_refreshToken: string): Promise<OAuthCredentials>;
+export declare function isKimiApiKeyStyleCredential(credentials: OAuthCredentials): boolean;

package/dist/types/facade/ml/kit/auth/oauth-page.d.ts

@@ -0,0 +1,2 @@
+export declare function oauthSuccessHtml(message: string): string;
+export declare function oauthErrorHtml(message: string, details?: string): string;

package/dist/types/facade/ml/kit/auth/openai-codex.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Sign-in flow for ChatGPT (Codex) accounts over OAuth.
+ *
+ * NOTE: this module reaches for Node's crypto and http modules to run the local
+ * OAuth callback server, so it is meant for CLI use and will not work in a browser.
+ */
+import type { OAuthCredentials, OAuthPrompt, OAuthProviderInterface } from "./types.js";
+/**
+ * Drive the ChatGPT (Codex) OAuth sign-in end to end.
+ *
+ * @param options.onAuth - Called once at the start with the authorize URL (and any
+ *   instructions) so the caller can surface or open it.
+ * @param options.onPrompt - Fallback path for collecting a hand-pasted code, used
+ *   only when onManualCodeInput is not supplied.
+ * @param options.onProgress - Optional callback for intermediate status text.
+ * @param options.onManualCodeInput - Optional promise that yields a code the user
+ *   pasted. We wait on it and the local callback server together and take whichever
+ *   answer arrives first, so a paste box and the browser round-trip can coexist.
+ * @param options.originator - Originator tag sent to OpenAI; defaults to the value
+ *   resolved by this module.
+ */
+export declare function loginOpenAICodex(options: {
+    onAuth: (info: {
+        url: string;
+        instructions?: string;
+    }) => void;
+    onPrompt: (prompt: OAuthPrompt) => Promise<string>;
+    onProgress?: (message: string) => void;
+    onManualCodeInput?: () => Promise<string>;
+    originator?: string;
+}): Promise<OAuthCredentials>;
+/**
+ * Renew a ChatGPT (Codex) OAuth credential from its refresh token.
+ */
+export declare function refreshOpenAICodexToken(refreshToken: string): Promise<OAuthCredentials>;
+export declare const openaiCodexOAuthProvider: OAuthProviderInterface;

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

@@ -0,0 +1,12 @@
+/**
+ * PKCE (RFC 7636) primitives implemented on top of the Web Crypto API so the
+ * same module works under Node.js 20+ and in browser runtimes alike.
+ */
+/**
+ * Generate a PKCE verifier and the matching S256 challenge.
+ * Built on Web Crypto so it remains runtime-agnostic.
+ */
+export declare function generatePKCE(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;

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;
+}