@miraiclip/assistant 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -10,6 +10,12 @@ interface ToolCall {
     id: string;
     name: string;
     arguments: Record<string, unknown>;
+    /**
+     * Opaque data the adapter that produced the call needs back when the
+     * conversation is replayed (Gemini thought signatures, Anthropic thinking
+     * blocks). Keep it with the call; other adapters ignore it.
+     */
+    meta?: Record<string, unknown>;
 }
 type ChatMessage = {
     role: "system";
@@ -59,18 +65,28 @@ interface ChatOptions {
     /** Streaming text, as it arrives (adapters that can't stream call it once). */
     onText?: (delta: string) => void;
 }
+interface ModelEntry {
+    id: string;
+    label?: string;
+}
 interface ChatModelInfo {
     /** Adapter id, e.g. "openai". Alphanumeric with - or _. */
     id: string;
     label: string;
     /** Models this adapter serves; the first is the default. */
-    models?: {
+    models?: ModelEntry[];
+    /** For a model that routes to several providers (`routedChatModel`): which ones. */
+    providers?: {
         id: string;
-        label?: string;
+        label: string;
     }[];
 }
 interface ChatModel extends ChatModelInfo {
     complete(request: ChatRequest, options?: ChatOptions): Promise<ChatResponse>;
+    /** Every model the account behind this adapter can use, live from the vendor (for model pickers). */
+    listModels?(options?: {
+        signal?: AbortSignal;
+    }): Promise<ModelEntry[]>;
 }
 /** An error from a model vendor, carrying its HTTP status when there was one. */
 declare class ChatModelError extends Error {
@@ -82,6 +98,16 @@ type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
 /** Check an adapter's shape once, at registration. */
 declare function defineChatModel<M extends ChatModel>(model: M): M;
 
+/**
+ * Plumbing the vendor adapters share: POST with retries on rate limits and
+ * server errors, server-sent-event reading, and tool-argument parsing.
+ */
+
+/** Parse a tool call's JSON arguments; unparseable JSON is reported to the model as a tool error. */
+declare function parseToolArguments(raw: string): Record<string, unknown>;
+/** How long the server asked us to wait (Retry-After header, or "try again in 1.2s / 350ms"), else exponential backoff. */
+declare function retryDelayMs(res: Pick<Response, "headers">, message: string, attempt: number): number;
+
 /**
  * OpenAI adapter, over the Chat Completions API with function calling.
  *
@@ -99,7 +125,7 @@ interface OpenAIChatModelOptions {
         label?: string;
     }[];
     /** API key. Omit for local servers that don't need one. Keep it server-side (see `createChatHandler`). */
-    apiKey?: string;
+    apiKey?: string | undefined;
     /** Default https://api.openai.com/v1. Any OpenAI-compatible base URL works. */
     baseUrl?: string;
     organization?: string;
@@ -115,6 +141,13 @@ interface OpenAIChatModelOptions {
      * backing off 1 s, 2 s, 4 s… (capped at 30 s). Default 4; 0 disables.
      */
     maxRetries?: number;
+    /**
+     * The request field for the output cap: "max_completion_tokens" (default;
+     * OpenAI) or "max_tokens" (what most other compatible servers read).
+     */
+    maxTokensField?: "max_completion_tokens" | "max_tokens";
+    /** Ask for token usage at the end of a stream (default true; turn off for servers that reject `stream_options`). */
+    streamUsage?: boolean;
     /** Adapter id / label (default "openai" / "OpenAI"), e.g. "ollama" when pointing elsewhere. */
     id?: string;
     label?: string;
@@ -141,56 +174,349 @@ type OpenAIMessage = {
 };
 /** Neutral messages → Chat Completions messages. */
 declare function toOpenAIMessages(messages: readonly ChatMessage[]): OpenAIMessage[];
-/** Parse a tool call's JSON arguments; unparseable JSON is reported to the model as a tool error. */
-declare function parseToolArguments(raw: string): Record<string, unknown>;
-/** How long the server asked us to wait (Retry-After header, or "try again in 1.2s / 350ms"), else exponential backoff. */
-declare function retryDelayMs(res: Pick<Response, "headers">, message: string, attempt: number): number;
 declare function openAIChatModel(options: OpenAIChatModelOptions): ChatModel;
 
+/**
+ * Anthropic adapter, over the Messages API with tool use.
+ *
+ * System messages become the top-level `system` prompt; tool results are
+ * grouped into one user turn, as the API expects. When extended thinking is
+ * on (`params: { thinking: … }`), the thinking blocks of a tool-using turn
+ * ride on the first tool call's `meta` and are sent back on the next request,
+ * which the API requires.
+ */
+
+interface AnthropicChatModelOptions {
+    /** Model id, e.g. "claude-sonnet-5-5". Required: model names change faster than this package. */
+    model: string;
+    /** Other models the app may pick per request (`ChatRequest.model`). */
+    models?: {
+        id: string;
+        label?: string;
+    }[];
+    /** API key. Keep it server-side (see `createChatHandler`) unless it's the user's own key in their own browser (`browser`). */
+    apiKey?: string | undefined;
+    /** Default https://api.anthropic.com (requests go to `{baseUrl}/v1/messages`). */
+    baseUrl?: string;
+    /** `anthropic-version` header (default "2023-06-01"). */
+    version?: string;
+    /** `anthropic-beta` flags, joined with commas. */
+    betas?: string[];
+    headers?: Record<string, string>;
+    /** Default request fields merged into every call (e.g. `{ thinking: { type: "enabled", budget_tokens: 4000 } }`). */
+    params?: Record<string, unknown>;
+    /** The API requires an output cap; used when a request sets none (default 8192). */
+    maxOutputTokens?: number;
+    /** Stream responses (default true). */
+    stream?: boolean;
+    /** Retries on 429, 5xx and 529 (overloaded), as the server asks. Default 4; 0 disables. */
+    maxRetries?: number;
+    /**
+     * Calling from a browser with the user's own key: sends the header the API
+     * needs to allow cross-origin requests. Never ship your own key this way.
+     */
+    browser?: boolean;
+    /** Adapter id / label (default "anthropic" / "Anthropic"). */
+    id?: string;
+    label?: string;
+    fetch?: FetchLike;
+}
+type Block = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+} | {
+    type: "thinking";
+    thinking: string;
+    signature: string;
+} | {
+    type: "redacted_thinking";
+    data: string;
+};
+type AnthropicMessage = {
+    role: "user" | "assistant";
+    content: Block[];
+};
+/** Neutral messages → `{ system, messages }` for the Messages API. */
+declare function toAnthropicMessages(messages: readonly ChatMessage[]): {
+    system: string;
+    messages: AnthropicMessage[];
+};
+declare function anthropicChatModel(options: AnthropicChatModelOptions): ChatModel;
+
+/**
+ * Google Gemini adapter, over the Gemini API's `generateContent` with
+ * function calling.
+ *
+ * Tools are sent as full JSON Schema (`parametersJsonSchema`), so the same
+ * schemas the other adapters use work unchanged. Gemini's thought signatures
+ * (required when thinking models call tools) ride on each tool call's `meta`
+ * and are sent back exactly as received.
+ */
+
+interface GeminiChatModelOptions {
+    /** Model id, e.g. "gemini-3.8-flash". Required: model names change faster than this package. */
+    model: string;
+    /** Other models the app may pick per request (`ChatRequest.model`). */
+    models?: {
+        id: string;
+        label?: string;
+    }[];
+    /** Gemini API key. Keep it server-side (see `createChatHandler`) unless it's the user's own key in their own browser. */
+    apiKey?: string | undefined;
+    /** Default https://generativelanguage.googleapis.com/v1beta. */
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    /** Default request fields merged into every call; `generationConfig` is merged key by key (e.g. `{ generationConfig: { temperature: 0.2 } }`). */
+    params?: Record<string, unknown>;
+    /** Stream responses (default true). */
+    stream?: boolean;
+    /** Retries on 429 and 5xx, as the server asks. Default 4; 0 disables. */
+    maxRetries?: number;
+    /** Adapter id / label (default "gemini" / "Google Gemini"). */
+    id?: string;
+    label?: string;
+    fetch?: FetchLike;
+}
+type Part = {
+    text?: string;
+    thought?: boolean;
+    thoughtSignature?: string;
+    functionCall?: {
+        id?: string;
+        name: string;
+        args?: Record<string, unknown>;
+    };
+    functionResponse?: {
+        id?: string;
+        name: string;
+        response: Record<string, unknown>;
+    };
+};
+type GeminiContent = {
+    role: "user" | "model";
+    parts: Part[];
+};
+/** Neutral messages → `{ systemInstruction, contents }` for `generateContent`. */
+declare function toGeminiContents(messages: readonly ChatMessage[]): {
+    system: string;
+    contents: GeminiContent[];
+};
+declare function geminiChatModel(options: GeminiChatModelOptions): ChatModel;
+
+type ProviderApi = "openai" | "anthropic" | "gemini";
+interface AiProviderInfo {
+    /** Id used in configs, env names and "provider/model" references. */
+    id: string;
+    label: string;
+    /** Which wire format it speaks. */
+    api: ProviderApi;
+    /** API root; `openai-compatible` has none (you give it). */
+    baseUrl?: string;
+    /** Whether calls need an API key (local servers don't). */
+    needsKey: boolean;
+    /** Runs on the user's machine (Ollama, LM Studio): reachable from that machine only. */
+    local?: boolean;
+    /** Where a user creates a key. */
+    keyUrl?: string;
+    /** Env var prefix: `{PREFIX}_API_KEY`, `{PREFIX}_MODEL`, `{PREFIX}_BASE_URL`, `{PREFIX}_MODELS`. */
+    env: string;
+    /** Used when no model is named. Providers without one need a model picked (env or UI). */
+    defaultModel?: string;
+    /** A few good picks to show before the live list loads. */
+    models?: ModelEntry[];
+    /** Accepts calls straight from a browser (CORS) with the user's own key. */
+    browser?: boolean;
+    /** OpenAI-format servers: the output-cap field and whether `stream_options` is accepted. */
+    maxTokensField?: "max_completion_tokens" | "max_tokens";
+    streamUsage?: boolean;
+}
+/**
+ * The built-in provider catalog. Model ids are suggestions as of release; the
+ * live list comes from each provider (`ChatModel.listModels`).
+ */
+declare const AI_PROVIDERS: readonly AiProviderInfo[];
+/** A provider from the catalog, or undefined. */
+declare function aiProvider(id: string): AiProviderInfo | undefined;
+interface CreateChatModelOptions {
+    /** A catalog id (`AI_PROVIDERS`): "openai", "anthropic", "gemini", "openrouter", "ollama", "openai-compatible", … */
+    provider: string;
+    apiKey?: string | undefined;
+    /** Model id (default: the provider's `defaultModel`; required for providers without one). */
+    model?: string | undefined;
+    /** Other models to offer (default: the catalog's suggestions). */
+    models?: ModelEntry[];
+    /** Override the API root (required for "openai-compatible"). */
+    baseUrl?: string | undefined;
+    headers?: Record<string, string>;
+    /** Default request fields for every call (vendor-specific). */
+    params?: Record<string, unknown>;
+    stream?: boolean;
+    maxRetries?: number;
+    /** Calling from the browser with the user's own key (sets what the vendor needs for CORS). */
+    browser?: boolean;
+    /** Adapter id / label (default: the provider's). */
+    id?: string;
+    label?: string;
+    fetch?: FetchLike;
+}
+/** One `ChatModel` for any provider in the catalog. */
+declare function createChatModel(options: CreateChatModelOptions): ChatModel;
+interface ChatModelsFromEnvOptions {
+    /** Only these providers (default: all). */
+    providers?: string[];
+    /** Told about providers that have a key but couldn't be set up (e.g. no model). */
+    onSkip?: (provider: string, reason: string) => void;
+    fetch?: FetchLike;
+}
+/**
+ * A model for every provider configured in `env` (`process.env`, Vite's
+ * `loadEnv`, a Worker's bindings):
+ *
+ *   {PREFIX}_API_KEY   enables a hosted provider (GEMINI also reads GOOGLE_API_KEY)
+ *   {PREFIX}_MODEL     its default model (required where the catalog has none)
+ *   {PREFIX}_MODELS    more models to offer, comma-separated
+ *   {PREFIX}_BASE_URL  another API root (a proxy, a gateway, a regional endpoint)
+ *
+ * Local servers (OLLAMA, LMSTUDIO) are enabled by their _MODEL or _BASE_URL.
+ * OPENAI_BASE_URL alone keeps its old meaning: an OpenAI-compatible server
+ * (label OPENAI_LABEL), key optional. Order follows the catalog, so the
+ * first entry makes a sensible default.
+ */
+declare function chatModelsFromEnv(env: Record<string, string | undefined>, options?: ChatModelsFromEnvOptions): ChatModel[];
+/** "anthropic/claude-sonnet-5-5" → { provider: "anthropic", model: "claude-sonnet-5-5" } when the prefix is a known id. */
+declare function splitModelRef(ref: string, providerIds: Iterable<string>): {
+    provider?: string;
+    model: string;
+};
+interface RoutedChatModelOptions {
+    id?: string;
+    label?: string;
+    /** Adapter id used when a request names no provider (default: the first). */
+    default?: string;
+}
+/**
+ * Several providers as one `ChatModel`. Its models are "provider/model"
+ * (`anthropic/claude-sonnet-5-5`, `openrouter/meta-llama/…`); a request's
+ * `model` picks the adapter and the model. A bare model id goes to the
+ * adapter that lists it, else to the default adapter; no model → the default
+ * adapter's default model.
+ */
+declare function routedChatModel(models: readonly ChatModel[], options?: RoutedChatModelOptions): ChatModel;
+
 /**
  * Keys stay on the server: run the real model adapter in your backend behind
  * `createChatHandler`, and give the browser `remoteChatModel(endpoint)` — a
  * proxy with the same `ChatModel` shape. The agent loop and the tools run in
  * the browser, next to the project; only model calls cross the network.
  *
- *   GET  {base}/       → { id, label, models }
+ *   GET  {base}/       → { id, label, models, providers?, userKeys? }
+ *   GET  {base}/models → { models } (live from the vendor when it can list them)
  *   POST {base}/chat   { request: ChatRequest } →
  *        application/x-ndjson, one JSON object per line:
  *        { "type": "text", "delta": "…" }   (as it streams)
  *        { "type": "done", "response": ChatResponse }
  *        { "type": "error", "error": "…", "status": 401 }
- *   errors before streaming → { error } with 400 / 404 / 413, or the vendor's status
+ *   errors before streaming → { error } with 400 / 401 / 403 / 404 / 413, or the vendor's status
+ *
+ * Bring your own key (`userKeys`): a request may carry the user's own
+ * provider and key in headers (`x-ai-provider`, `x-ai-key`, optionally
+ * `x-ai-base-url`). The handler builds a model for that one request and
+ * forgets the key — it's never stored or logged. Use it for plans where
+ * customers pay their AI vendor directly.
  *
  * Fetch-API handler (`Request` → `Response`): mounts in Node 18+, edge
  * runtimes, Next, Hono, Express (via an adapter).
  */
 
+/** Header names a request uses to bring the user's own key. */
+declare const USER_KEY_HEADERS: {
+    readonly provider: "x-ai-provider";
+    readonly key: "x-ai-key";
+    readonly baseUrl: "x-ai-base-url";
+};
+/** The user's own provider settings, as the browser sends them. */
+interface UserCredentials {
+    provider: string;
+    apiKey?: string;
+    /** Only honored when the server allows it (`userKeys.allowBaseUrl`). */
+    baseUrl?: string;
+}
+interface UserKeyOptions {
+    /** Providers users may bring a key for (default: every hosted provider in the catalog). */
+    providers?: string[];
+    /**
+     * Let users send their own API root (OpenAI-compatible servers, gateways).
+     * Off by default: your server would call whatever URL a user sends.
+     */
+    allowBaseUrl?: boolean;
+    /** Refuse requests without the user's own key, even when the server has a model. */
+    required?: boolean;
+    /** Build the model for a user's key (default `createChatModel`): add headers, pin params, wrap with limits. */
+    create?: (options: CreateChatModelOptions, request: Request) => ChatModel;
+    fetch?: FetchLike;
+}
 interface ChatHandlerOptions {
     /** Path prefix the handler is mounted at, e.g. "/api/assistant". */
     basePath?: string;
     /** Reject request bodies larger than this (default 2 MB). */
     maxBodyBytes?: number;
-    /** Return a Response to refuse a request (auth, rate limits); undefined to allow. */
+    /** Return a Response to refuse a request (auth, rate limits, plan checks); undefined to allow. */
     authorize?: (request: Request) => Promise<Response | undefined> | Response | undefined;
     /** Adjust each request server-side (pin a model, cap tokens, add instructions). */
     prepare?: (request: ChatRequest) => ChatRequest;
+    /** Accept the user's own provider key per request (see the module note). Off by default. */
+    userKeys?: boolean | UserKeyOptions;
+}
+/** What `GET {base}/` tells the browser about bring-your-own-key. */
+interface UserKeyInfo {
+    providers: Pick<AiProviderInfo, "id" | "label" | "needsKey" | "keyUrl" | "defaultModel" | "models">[];
+    allowBaseUrl: boolean;
+    required: boolean;
+}
+/**
+ * @param model The server's own model (its keys, from env or config), or
+ *   `null` when every user brings their own key (`userKeys` must be on).
+ */
+declare function createChatHandler(model: ChatModel | null, options?: ChatHandlerOptions): (request: Request) => Promise<Response | null>;
+/** What the server said about itself (`GET {base}/`). */
+interface RemoteModelInfo {
+    id: string;
+    label: string;
+    models?: ModelEntry[];
+    providers?: {
+        id: string;
+        label: string;
+    }[];
+    userKeys?: UserKeyInfo;
+    /** The server has no model of its own (or requires user keys): calls need the user's key. */
+    needsKey?: boolean;
 }
-declare function createChatHandler(model: ChatModel, options?: ChatHandlerOptions): (request: Request) => Promise<Response | null>;
 interface RemoteChatModelOptions {
     fetch?: FetchLike;
     headers?: Record<string, string>;
     /** Skip the GET for model info (id/label/models default to "remote"). */
-    info?: {
-        id: string;
-        label: string;
-        models?: {
-            id: string;
-            label?: string;
-        }[];
-    };
+    info?: RemoteModelInfo;
+    /**
+     * The user's own provider key, read on every call (so a settings change
+     * applies at once). Return nothing to use the server's model.
+     */
+    credentials?: () => UserCredentials | null | undefined;
 }
-/** The model a backend serves, as a browser-side `ChatModel`. */
-declare function remoteChatModel(endpoint: string, options?: RemoteChatModelOptions): Promise<ChatModel>;
+/** Headers carrying the user's own key, for any request to a `createChatHandler` server. */
+declare function userKeyHeaders(credentials: UserCredentials | null | undefined): Record<string, string>;
+/** The model a backend serves, as a browser-side `ChatModel` (plus what the server said about itself in `info`). */
+declare function remoteChatModel(endpoint: string, options?: RemoteChatModelOptions): Promise<ChatModel & {
+    info: RemoteModelInfo;
+}>;
 
 interface RateLimitOptions {
     /** Tokens per rolling minute across every caller of this model (input + output). */
@@ -245,7 +571,8 @@ declare function defineTool(tool: AssistantTool): AssistantTool;
 /**
  * Adopt tools that come as definitions plus one runner — e.g.
  * `@miraiclip/audio-sources`' `audioToolDefinitions` + `runAudioTool`.
- * Accepts `{ name, description, input_schema }` or OpenAI function tools.
+ * Accepts `{ name, description, input_schema }`, OpenAI function tools or
+ * Gemini function declarations.
  */
 declare function toolsFromDefinitions(definitions: readonly unknown[], run: (name: string, input: Record<string, unknown>, ctx: ToolContext) => Promise<{
     ok: boolean;
@@ -404,4 +731,4 @@ declare function scriptedChatModel(steps: ScriptStep[], options?: {
     requests: ChatRequest[];
 };
 
-export { type Assistant, type AssistantEvent, type AssistantOptions, type AssistantTool, type AssistantTurn, BACKGROUND_TEMPLATE, type ChatHandlerOptions, type ChatMessage, type ChatModel, ChatModelError, type ChatModelInfo, type ChatOptions, type ChatRequest, type ChatResponse, type ChatUsage, type CommitResult, DEFAULT_INSTRUCTIONS, type EditorToolsOptions, type FetchLike, type ForkOptions, type OpenAIChatModelOptions, type RateLimitOptions, type RecordingProject, type RemoteChatModelOptions, type ScriptStep, type ToolCall, type ToolContext, type ToolOutput, type ToolSpec, type TurnOptions, type UnknownFields, applyChecked, applyCommandsSchema, commitFork, createAssistant, createChatHandler, defineChatModel, defineTool, describeCommands, describeForAssistant, editorTools, forkProject, openAIChatModel, parseToolArguments, rateLimitedChatModel, remoteChatModel, retryDelayMs, scriptedChatModel, toOpenAIMessages, toolsFromDefinitions, unknownFields, withExplicitIds };
+export { AI_PROVIDERS, type AiProviderInfo, type AnthropicChatModelOptions, type Assistant, type AssistantEvent, type AssistantOptions, type AssistantTool, type AssistantTurn, BACKGROUND_TEMPLATE, type ChatHandlerOptions, type ChatMessage, type ChatModel, ChatModelError, type ChatModelInfo, type ChatModelsFromEnvOptions, type ChatOptions, type ChatRequest, type ChatResponse, type ChatUsage, type CommitResult, type CreateChatModelOptions, DEFAULT_INSTRUCTIONS, type EditorToolsOptions, type FetchLike, type ForkOptions, type GeminiChatModelOptions, type ModelEntry, type OpenAIChatModelOptions, type ProviderApi, type RateLimitOptions, type RecordingProject, type RemoteChatModelOptions, type RemoteModelInfo, type RoutedChatModelOptions, type ScriptStep, type ToolCall, type ToolContext, type ToolOutput, type ToolSpec, type TurnOptions, USER_KEY_HEADERS, type UnknownFields, type UserCredentials, type UserKeyInfo, type UserKeyOptions, aiProvider, anthropicChatModel, applyChecked, applyCommandsSchema, chatModelsFromEnv, commitFork, createAssistant, createChatHandler, createChatModel, defineChatModel, defineTool, describeCommands, describeForAssistant, editorTools, forkProject, geminiChatModel, openAIChatModel, parseToolArguments, rateLimitedChatModel, remoteChatModel, retryDelayMs, routedChatModel, scriptedChatModel, splitModelRef, toAnthropicMessages, toGeminiContents, toOpenAIMessages, toolsFromDefinitions, unknownFields, userKeyHeaders, withExplicitIds };