@miraiclip/assistant 0.1.2 → 0.3.0

package/dist/index.d.ts

@@ -10,6 +10,18 @@ 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>;
+}
+/** An image the model looks at (a rendered preview a tool returns): base64 bytes and their type. */
+interface ChatImage {
+    mimeType: string;
+    /** Base64, no `data:` prefix. */
+    data: string;
 }
 type ChatMessage = {
     role: "system";
@@ -21,11 +33,14 @@ type ChatMessage = {
     role: "assistant";
     content: string;
     toolCalls?: ToolCall[];
-} | {
+}
+/** `images`: pictures that come with the result (e.g. rendered frames), for models that can see. */
+ | {
     role: "tool";
     toolCallId: string;
     name: string;
     content: string;
+    images?: ChatImage[];
 };
 /** A tool as the model sees it: name, description and a JSON Schema for its input. */
 interface ToolSpec {
@@ -59,18 +74,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 +107,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 +134,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,14 +150,33 @@ 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;
     fetch?: FetchLike;
 }
+type OpenAIPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+};
 type OpenAIMessage = {
     role: "system" | "user";
     content: string;
+} | {
+    role: "user";
+    content: OpenAIPart[];
 } | {
     role: "assistant";
     content: string | null;
@@ -141,56 +195,364 @@ 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 ImageBlock = {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+};
+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: "text";
+        text: string;
+    } | ImageBlock)[];
+} | {
+    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>;
+    };
+    inlineData?: {
+        mimeType: string;
+        data: string;
+    };
+};
+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). */
@@ -224,16 +586,32 @@ interface UnknownFields {
 /** Unknown payload fields for a command, judged against the best-matching schema branch. */
 declare function unknownFields(schema: unknown, payload: unknown): UnknownFields | null;
 
+/**
+ * Checks an html clip's template the way the renderer will read it: as XML
+ * (it rasterizes through an SVG `foreignObject`). Markup that isn't
+ * well-formed renders nothing, silently, so the assistant rejects it up front
+ * with an error the model can fix.
+ */
+/** Why the markup won't parse as XML, or undefined when it's well-formed. */
+declare function markupProblem(markup: string): string | undefined;
+/** `asset:<id>` references in a template. */
+declare function assetRefs(markup: string): string[];
+
 /** What a tool's `run` gets. `project` is the turn's working copy. */
 interface ToolContext {
     project: Project;
     signal?: AbortSignal;
 }
-/** A tool's answer. `changes` are human-readable lines for the app's "what changed" list. */
+/**
+ * A tool's answer. `changes` are human-readable lines for the app's "what
+ * changed" list. `images` go to the model with the result, so it can look at
+ * what it made (rendered frames); models that can't see get the text only.
+ */
 type ToolOutput = {
     ok: true;
     result?: unknown;
     changes?: string[];
+    images?: ChatImage[];
 } | {
     ok: false;
     error: unknown;
@@ -245,7 +623,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;
@@ -263,6 +642,13 @@ interface EditorToolsOptions {
     transitionKinds?: string[];
     /** The command catalog to offer in apply_commands (default: the built-ins). Pass `project.commandCatalog()` when you register custom commands. */
     commandCatalog?: Record<string, unknown>;
+    /**
+     * Runs the continuous-shot check over the document (e.g. `checkShot` from `@miraiclip/server-export`, or the app's
+     * in-browser equivalent). The `check_sequence` tool is offered only when this is given, because the check needs a browser.
+     */
+    checkSequence?: (doc: ProjectDocument, options: {
+        clipId?: string;
+    }) => Promise<unknown>;
 }
 /**
  * The tools that edit a Miraiclip project: read state, look up a command's
@@ -315,12 +701,75 @@ type CommitResult = {
 /** Replay a fork's commands onto the real project as one undoable step. */
 declare function commitFork(project: Project, fork: RecordingProject, label?: string): CommitResult;
 
+/**
+ * Skills: playbooks for bigger jobs (a launch video, captions, a reformat),
+ * loaded by the model only when a request needs one.
+ *
+ * The system prompt lists each skill's name and description. The model calls
+ * `load_skill` to read one, and `read_skill_file` for the reference files it
+ * points to, so the prompt stays small however many skills there are. An app
+ * can also start a request with a skill already loaded (`TurnOptions.skills`),
+ * e.g. from a button.
+ *
+ * Skills are plain Markdown with a front matter (`name`, `description`), the
+ * same shape as Claude Code skills. `MIRAICLIP_SKILLS` are the Miraiclip
+ * plugin's skills, in their editor versions.
+ */
+interface AssistantSkill {
+    /** Lowercase letters, digits and dashes, e.g. "captions". */
+    name: string;
+    /** When to use it, in one or two sentences. The model picks skills by this. */
+    description: string;
+    /** The playbook (Markdown, without the front matter). */
+    instructions: string;
+    /** Reference files the playbook points to, by relative path ("reference/craft.md"). */
+    files?: Readonly<Record<string, string>>;
+}
+declare function defineSkill(skill: AssistantSkill): AssistantSkill;
+/** Split `---\nkey: value\n---\nbody` into its fields and body. Values may be quoted. */
+declare function parseFrontMatter(markdown: string): {
+    data: Record<string, string>;
+    body: string;
+};
+/** One skill from its Markdown (front matter `name` and `description`). */
+declare function parseSkill(markdown: string, options?: {
+    name?: string;
+    description?: string;
+    files?: Record<string, string>;
+}): AssistantSkill;
+interface SkillsFromFilesOptions {
+    /**
+     * Which file in a skill folder is the playbook, in order of preference.
+     * Default `["SKILL.md"]`. The Miraiclip plugin keeps the Claude Code
+     * version in SKILL.md and the in-editor version in EDITOR.md, so an editor
+     * passes `["EDITOR.md"]` (folders without one are skipped). The other
+     * entry file's front matter fills in a missing name or description.
+     */
+    entry?: string[];
+}
+/**
+ * Skills from a folder of skill folders, given as `{ path: text }` — e.g.
+ * Vite's `import.meta.glob("./skills/**\/*.md", { query: "?raw", import: "default", eager: true })`.
+ * Every other `.md` in a skill's folder becomes one of its files.
+ */
+declare function skillsFromFiles(files: Record<string, string>, options?: SkillsFromFilesOptions): AssistantSkill[];
+/** The skill list for the system prompt. */
+declare function describeSkills(skills: readonly AssistantSkill[]): string;
+/** `load_skill` and `read_skill_file` for these skills. */
+declare function skillTools(skills: readonly AssistantSkill[]): AssistantTool[];
+
 interface AssistantOptions {
     model: ChatModel;
     /** Default `editorTools()`. Add your own (audio, captions, stock media…). */
     tools?: AssistantTool[];
     /** Extra system instructions (brand voice, house rules). */
     instructions?: string;
+    /**
+     * Playbooks the model can load when a request needs one (e.g.
+     * `MIRAICLIP_SKILLS`). Adds `load_skill` and `read_skill_file` to the tools
+     * and lists each skill's name and description in the system prompt.
+     */
+    skills?: readonly AssistantSkill[];
     /** Model round-trips per request (default 12). */
     maxSteps?: number;
     /** Model id when the adapter serves several. */
@@ -342,6 +791,8 @@ type AssistantEvent = {
     ok: boolean;
     changes?: string[];
     error?: string;
+    /** Images the tool returned (previews, storyboards) — the model sees them too; apps may show them. */
+    images?: ChatImage[];
 } | {
     type: "step";
     index: number;
@@ -357,6 +808,13 @@ interface TurnOptions {
     onEvent?: (event: AssistantEvent) => void;
     /** History label for the undo step (default "Assistant: <request>"). */
     label?: string;
+    /**
+     * Skills to load up front for this request, by name (e.g. the user picked
+     * "Captions" in the app). Their playbooks go into the system prompt, so the
+     * model starts on them without a `load_skill` call. Unknown names are
+     * ignored.
+     */
+    skills?: readonly string[];
 }
 interface AssistantTurn {
     /** The model's final answer to the user. */
@@ -387,6 +845,9 @@ interface Assistant {
 declare const DEFAULT_INSTRUCTIONS = "You are the editing assistant inside a video editor. You change the user's project by calling tools; every change you make lands as ONE undo step when you finish, so act confidently.\n\nHow to work:\n- The current project is summarized below. Clip, track and asset ids there are what tools expect. Call get_state to re-read it after big changes.\n- Prefer the high-level tools when they fit (add_transition, animate_clip, add_effect, set_effects_enabled, set_background, trim_clip, set_keyframes, close_gaps, and any audio or media tools). Call tools directly; apply_commands takes only editing commands like \"clip/add\", never tool names. Use apply_commands for everything else, batching related commands; look up a command's payload with get_command_schema the first time you use it, and use only the fields it lists.\n- Fading a picture (text, image, logo, video) in or out is animate_clip (in / out: fade). fadeInUs / fadeOutUs are audio fades. \"Fade the video in at the start / out at the end\" means the first clip's entrance and the last clip's exit.\n- Constant values are set directly with clip/set-property: rotation (\"rotate 45\u00B0\", \"tilt\"), volume (\"lower to 30%\", \"louder\"), position, size, opacity. Only values that CHANGE over a time range (\"duck the music between 10 and 15 s\", \"fade to silence between 18 and 20 s\", \"spin one full turn\", \"pan across\") are keyframes: set_keyframes, with times in timeline seconds. Remove an animation with keyframe/clear.\n- \"Cuts\" are the ones listed in the project summary; use their times (e.g. one sound per cut).\n- \"Add N more seconds of footage\" adds a new clip (clip/add with trimStartUs for the source point) after the last one; it does not stretch an existing clip.\n- Caption looks (box behind the text, outline, shadow, colors, word preset) are the caption clip's style (clip/set-property { style }).\n- \"The whole video\" means from 0 to the composition length (trim_clip startSeconds / endSeconds).\n- A solid color background behind everything is set_background (add, recolor, remove). Other html clips are recolored through the params their template uses (shown in the clip details). A new track goes on top unless track/add gets index 0 (the bottom).\n- \"Replace X with Y\" removes X and adds Y in the same turn, whichever tool adds Y (audio tools take replaceClipId, which does both).\n- Solo / mute / lock / hide a track with track/set-property (solo, muted, locked, hidden). \"Solo X\" is solo: true on X, not muting the others.\n- Relative requests (\"bigger\", \"louder\", \"a bit brighter\", \"twice as big\") start from the current values in the clip details below: make a visible change in the asked direction (about 25% for \"bigger\"/\"smaller\", \u00D72 for \"twice\").\n- When something is selected, \"this\", \"it\", \"the clip\" and any request that names no target mean ONLY the selection, even with words like \"at the end\" (the end of that clip). Edit nothing else. \"Here\" / \"now\" / \"this point\" mean the playhead. \"Clips\" without a kind mean the video clips on the main video track.\n- \"Again\" / \"also\" / \"another\" mean keep the original and add a copy (clip/duplicate, or clip/add with the same asset); never move the original. \"Instead\" means move or replace.\n- Removing a clip leaves a gap; when asked to close it, also run close_gaps (or trim_clip with ripple).\n- Commands use integer microseconds (1 second = 1000000). High-level tools take seconds.\n- Positions (transform x, y) are fractions of the frame: 0.5, 0.5 is the center.\n- Only reference media that exists in the project or that a tool returned. Never invent file URLs.\n- If a tool fails, read the error, fix the input and retry. A failed apply_commands batch applied NONE of its commands: resend all of them, corrected. If something can't be done, say why.\n- If the request is ambiguous in a way that matters, ask one short question instead of guessing.\n\nWhen you're done, reply in one to three short sentences: what you changed, in plain words (times in seconds, names over ids). Describe only edits your tools reported as applied; if a tool says something changed nothing or failed, fix it or say so. No markdown headings.";
 declare function createAssistant(options: AssistantOptions): Assistant;
 
+/** The Miraiclip plugin's skills, in their in-editor versions: pass to `createAssistant({ skills })`. */
+declare const MIRAICLIP_SKILLS: readonly AssistantSkill[];
+
 type ScriptStep = string | {
     text?: string;
     toolCalls?: (Omit<ToolCall, "id"> & {
@@ -404,4 +865,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 AssistantSkill, type AssistantTool, type AssistantTurn, BACKGROUND_TEMPLATE, type ChatHandlerOptions, type ChatImage, 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, MIRAICLIP_SKILLS, type ModelEntry, type OpenAIChatModelOptions, type ProviderApi, type RateLimitOptions, type RecordingProject, type RemoteChatModelOptions, type RemoteModelInfo, type RoutedChatModelOptions, type ScriptStep, type SkillsFromFilesOptions, 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, assetRefs, chatModelsFromEnv, commitFork, createAssistant, createChatHandler, createChatModel, defineChatModel, defineSkill, defineTool, describeCommands, describeForAssistant, describeSkills, editorTools, forkProject, geminiChatModel, markupProblem, openAIChatModel, parseFrontMatter, parseSkill, parseToolArguments, rateLimitedChatModel, remoteChatModel, retryDelayMs, routedChatModel, scriptedChatModel, skillTools, skillsFromFiles, splitModelRef, toAnthropicMessages, toGeminiContents, toOpenAIMessages, toolsFromDefinitions, unknownFields, userKeyHeaders, withExplicitIds };