@vetta-org/plugin-sdk 0.0.3 → 0.1.0

package/dist/index.d.ts

@@ -1,1481 +1,35 @@
-import type { ComponentType, ReactNode } from "react";
 /**
- * 对话场景 slug——决定一个工具 / 会话页插槽在哪些类型的会话里激活或可见。
+ * @vetta-org/plugin-sdk public surface.
  *
- * 本类型在 plugin-sdk 内本地定义（SDK 零依赖，不引入宿主包），与宿主
- * `@vetta/coding-agent` 的 `ConversationScenario` 保持一一对应；任一侧增删场景时两边须同步，
- * 否则宿主回传的 scenario 与此 union 不一致会触发编译错误（即为期望的漂移护栏）。
- */
-export type ConversationScenario = "im-claw" | "conversation" | "project" | "batch" | "automation" | "kb-processing" | "cli";
-export type PluginPermission = "ui.slot.global" | "ui.slot.file-preview" | "ui.slot.activity-tab" | "ui.slot.input-action" | "ui.slot.message" | "ui.slot.tool-call" | "ui.slot.turn-card" | "agent.session.read" | "agent.session.write" | "agent.command.run" | "agent.systemPrompt.read" | "agent.systemPrompt.write" | "agent.systemPrompt.fullControl" | "agent.skills.control" | "agent.mcp.control" | "agent.tools.control" | "agent.tools.register" | "agent.toolHandler.execute" | "agent.state.read" | "agent.state.write" | "agent.continuation.register" | "agent.runtime.configure" | "app.actions.register" | "app.actionHandler.execute" | "fs.read" | "fs.write" | "network.fetch" | "images.generate" | "settings.read" | "settings.write";
-/**
- * MCP server config declared inside a plugin (stdio or http). Relative paths in
- * stdio `command`/`args`/`cwd` are resolved against the plugin root at contribute time.
- */
-export type PluginMcpServerConfig = {
-    type?: "stdio";
-    command: string;
-    args?: string[];
-    env?: Record<string, string>;
-    cwd?: string;
-    disabled?: boolean;
-    autoApprove?: string[];
-    startupTimeout?: number;
-    debug?: boolean;
-    displayName?: string;
-    description?: string;
-    /** 该 server 的工具允许出现的工作模式 slug（agent_mode 轴，缺省/空 = 通用）。见 ADR-0046。 */
-    agent_mode?: string | string[];
-} | {
-    type: "http";
-    url: string;
-    headers?: Record<string, string>;
-    oauthClientId?: string;
-    oauthDeviceFlow?: boolean;
-    oauthScopes?: string;
-    disabled?: boolean;
-    autoApprove?: string[];
-    startupTimeout?: number;
-    debug?: boolean;
-    displayName?: string;
-    description?: string;
-    /** 该 server 的工具允许出现的工作模式 slug（agent_mode 轴，缺省/空 = 通用）。见 ADR-0046。 */
-    agent_mode?: string | string[];
-};
-export interface PluginAgentManifest {
-    systemPrompt?: {
-        /**
-         * Plugin-packaged prompt contribution file paths. Main-process aggregation
-         * resolves these relative to the installed plugin root.
-         */
-        promptPaths?: string[];
-    };
-    /** Plugin-packaged skill files or directories to add to the agent resource graph. */
-    skillPaths?: string[];
-    /**
-     * Plugin-scoped MCP servers. Either a relative path to `.mcp.json`
-     * (shape `{ mcpServers: { ... } }`) or an inline map of server configs.
-     * Requires permission `agent.mcp.control`. Never written into user mcp.json.
-     */
-    mcpServers?: string | Record<string, PluginMcpServerConfig>;
-    /** Declarative tool visibility policy. Names are tool ids after registration. */
-    toolPolicy?: {
-        allow?: string[];
-        deny?: string[];
-    };
-}
-export interface Disposable {
-    dispose(): void;
-}
-export interface PluginGlobalSlotContribution {
-    id: string;
-    component: ComponentType;
-}
-export interface PluginAudioMetadata {
-    /** Embedded title; preview renderers should fall back to file.name. */
-    title?: string;
-    artist?: string;
-    /** Embedded cover art as a Data URL when available. */
-    coverDataUrl?: string;
-}
-export interface PluginPreviewUrlOptions {
-    /** Optional media hint for ambiguous containers such as webm. */
-    mediaKind?: "audio" | "video";
-}
-/**
- * The file handed to a file-preview plugin component. The host does NOT
- * pre-read or guess encoding — the plugin decides whether to read text or
- * bytes. `path` is also exposed for plugins that prefer native fetch.
- */
-export interface PluginPreviewFile {
-    path: string | null;
-    name: string;
-    extension: string;
-    mime: string;
-    size: number;
-    /** Read the file as a UTF-8 string. */
-    readText(): Promise<string>;
-    /** Read the raw file bytes. */
-    readBytes(): Promise<ArrayBuffer>;
-    /** A fetchable streaming URL for the file (Range-capable). */
-    getUrl(options?: PluginPreviewUrlOptions): string;
-    /**
-     * Subscribe to on-disk changes of this file. The listener fires (debounced
-     * by the host) whenever the file's contents change, letting previews update
-     * live. Returns a Disposable; call dispose() to stop watching. A no-op for
-     * files without a real path (url-only sources).
-     */
-    watch(listener: () => void): Disposable;
-    /**
-     * Host-provided audio metadata for local media files. Returns null when the
-     * host cannot provide metadata, e.g. url-only sources or unsupported files.
-     */
-    getAudioMetadata?(): Promise<PluginAudioMetadata | null>;
-}
-export interface PluginFilePreviewProps {
-    file: PluginPreviewFile;
-}
-export interface PluginFilePreviewContribution {
-    /** Lower-case extensions without the dot, e.g. ["svg"]. */
-    extensions: string[];
-    component: ComponentType<PluginFilePreviewProps>;
-}
-/**
- * An activity-panel tab contributed by a plugin. Registering only adds the
- * tab to the "addable pool" — it renders only after the user attaches it in
- * the activity panel (scoped by session cwd).
- */
-export interface PluginActivityTabContribution {
-    id: string;
-    label: string;
-    /** Tab icon as a React node (not an iconify class string). */
-    icon?: ReactNode;
-    component: ComponentType;
-    /**
-     * 允许该标签卡出现的对话场景 slug 列表（镜像工具的 scope_use）。**fail-closed**：
-     * 未声明/空数组 = 任何会话都不显示；声明后仅在列出的场景里出现（如
-     * `["project", "conversation"]`）。会话页插槽据此随对话类型显隐。
-     */
-    scope_use?: readonly ConversationScenario[];
-}
-/** Options for {@link PluginUiApi.openActivityTab}. */
-export interface PluginOpenActivityTabOptions {
-    /**
-     * Desired panel width as it opens: a pixel number, or `"max"` for the widest
-     * the current window allows. The host clamps to its min/max bounds. Omit to
-     * keep the user's current width.
-     */
-    width?: number | "max";
-}
-/**
- * A reference to an image produced out-of-band by the host (e.g. an image
- * tool's result). The bytes are NOT carried inline — `url` is a host media
- * URL (Range-capable, usable directly as an `<img src>`).
- */
-export interface PluginImageRef {
-    id: string;
-    url: string;
-    mimeType?: string;
-    /**
-     * The edit-lineage root id this image belongs to (base image + all its edits
-     * share one rootId). Lets the host dedup per-message previews — only the
-     * latest message producing a given rootId renders the version swiper.
-     */
-    rootId?: string;
-}
-/**
- * Decoration a plugin contributes to the next outgoing prompt while its input
- * action is active. `metadata` is shallow-merged into the prompt request's
- * `metadata` bag, which the agent turn can read (e.g. `{ imageMode: true }`).
- */
-export interface PluginPromptDecoration {
-    metadata?: Record<string, unknown>;
-}
-/**
- * An action button shown in a row beneath the AI input bar. Rendered as a
- * toggle: clicking activates, clicking again deactivates. While active, the
- * host calls `decoratePrompt()` before each send and merges the returned
- * metadata into the outgoing prompt request. The plugin owns any side state
- * (it is the same Module Federation instance as its other slots).
- */
-export interface PluginInputActionContribution {
-    id: string;
-    label: string;
-    /** Button icon as a React node (not an iconify class string). */
-    icon?: ReactNode;
-    /** Whether the action begins in the active state. Defaults to false. */
-    defaultActive?: boolean;
-    /**
-     * 该输入动作所依赖的 agent 工具名。设置后，仅当该工具在当前会话处于激活（按工具的
-     * scope_use 解析）时才显示这个 badge——避免在工具被场景屏蔽（如批量任务）时仍显示一个
-     * 点了也无效的开关。不设则始终显示。例如「图像生成」设为 "generate_image"。
-     */
-    requiresActiveTool?: string;
-    /**
-     * 允许该 toggle 出现的对话场景 slug 列表（镜像工具的 scope_use）。**fail-closed**：
-     * 未声明/空数组 = 任何会话都不显示；声明后仅在列出的场景里出现。与 `requiresActiveTool`
-     * 取「与」：两者都满足才显示。
-     */
-    scope_use?: readonly ConversationScenario[];
-    /**
-     * When true, this plugin's agent contributions (tools / skills / MCP /
-     * systemPrompt) and Activity Tabs are hard-isolated: inactive until this
-     * toggle is on (ADR-0041, knowledgeMode-style). Default false.
-     */
-    hardIsolation?: boolean;
-    /**
-     * Fired when the user toggles the action; `active` is the new state. Return
-     * `false` when `active` is true to VETO the activation (e.g. the plugin needs
-     * configuration first) — the toggle stays off. Deactivation can't be vetoed.
-     */
-    onToggle?(active: boolean): boolean | void;
-    /**
-     * Called by the host before sending while the action is active. The
-     * returned metadata is merged into the outgoing prompt request.
-     */
-    decoratePrompt?(): PluginPromptDecoration | void;
-}
-/**
- * A declarative, serializable descriptor for one card rendered beneath a
- * message. `type` selects a registered card renderer; `key` drives cross-turn
- * dedup (same key across turns = one logical card, shown only under its latest
- * anchor); `payload` carries STABLE REFERENCES (e.g. image ids), not a content
- * snapshot — the renderer resolves live state from it. `title`/`icon` label the
- * card's tab (override the renderer's registration defaults). Rides a tool
- * result's out-of-band `details.cards`; crosses the agent→host boundary, so
- * `icon` is an icon-symbol string, not a node.
- */
-export interface CardDescriptor {
-    type: string;
-    key?: string;
-    payload?: unknown;
-    title?: string;
-    icon?: string;
-}
-/** A pending (in-flight) tool call handed to a renderer's `pendingFor`. */
-export interface PluginPendingToolCall {
-    toolName: string;
-    args: Record<string, unknown>;
-}
-/**
- * Props for a card renderer. `descriptor` is the card's data; `pending` is true
- * while it was synthesized from an in-flight tool (render a skeleton); `message`
- * is the anchoring conversation message.
- */
-export interface PluginCardProps {
-    descriptor: CardDescriptor;
-    pending: boolean;
-    message: ConversationMessage;
-}
-/**
- * A card renderer registered by a plugin, keyed by `type`. A descriptor whose
- * `type` matches is rendered by `component`. `title`/`icon` are the default tab
- * label/icon (a descriptor may override `title`). `pendingFor`, given an
- * in-flight tool call, returns a provisional descriptor so a skeleton card
- * appears (and claims a tab) before the tool's result lands — or null when this
- * renderer doesn't handle that tool. The `type` must be globally unique across
- * plugins (convention: prefix with the plugin id, e.g. "image-gen:preview").
- */
-export interface PluginCardRendererContribution {
-    type: string;
-    component: ComponentType<PluginCardProps>;
-    title?: string;
-    /** Default tab icon as a React node (not an iconify class string). */
-    icon?: ReactNode;
-    pendingFor?: (toolCall: PluginPendingToolCall) => CardDescriptor | null;
-}
-/** A tool call handed to a tool-call slot renderer. */
-export interface PluginToolCallSlotToolCall {
-    toolCallId: string;
-    toolName: string;
-    args: Record<string, unknown>;
-    status: "pending" | "success" | "error";
-    result?: string;
-    isError?: boolean;
-}
-export interface PluginToolCallSlotProps {
-    toolCall: PluginToolCallSlotToolCall;
-}
-/**
- * A component that **replaces the host's default inline transcript rendering**
- * for a specific tool (matched by `toolName`; first registered renderer wins).
- * This is how a plugin renders rich UI for its OWN agent tool's output — plugin
- * tools cannot emit `details.cards`, so the message card system (registerCardRenderer)
- * does not serve them; the tool-call slot does.
- */
-export interface PluginToolCallSlotContribution {
-    id: string;
-    toolName: string;
-    component: ComponentType<PluginToolCallSlotProps>;
-}
-/**
- * A card rendered at the bottom of the message list for the LATEST turn — NOT
- * bound to a tool call. The host mounts `component` in the footer slot and
- * re-mounts it each session/turn; the plugin owns visibility entirely (it reads
- * live state via SDK hooks — `useActiveConversation`, `useConversationMessages`,
- * `ctx.conversation.on("turn-end")` — and returns `null` to render nothing,
- * e.g. git renders only inside a repo that has changes). `scope_use` gates which
- * conversation scenarios it may appear in (**fail-closed**, mirrors the other
- * slots). `id` must be unique within the plugin.
- */
-export interface PluginTurnCardContribution {
-    id: string;
-    component: ComponentType;
-    /**
-     * 允许该 turn 卡出现的对话场景 slug 列表（镜像其它插槽的 scope_use）。**fail-closed**：
-     * 未声明/空数组 = 任何会话都不显示；声明后仅在列出的场景里出现（如 `["project"]`）。
-     */
-    scope_use?: readonly ConversationScenario[];
-}
-export interface PluginUiApi {
-    registerGlobalSlot(contribution: PluginGlobalSlotContribution): Disposable;
-    /**
-     * Register a preview component keyed by file extension. The host dispatches
-     * registered extensions before its built-in fallback renderers; first
-     * registrant wins on conflict.
-     */
-    registerFilePreview(contribution: PluginFilePreviewContribution): Disposable;
-    /**
-     * Register an activity-panel tab into the addable pool. The user attaches
-     * it manually via the panel's "+" picker; attach records are keyed by the
-     * session cwd.
-     */
-    registerActivityTab(contribution: PluginActivityTabContribution): Disposable;
-    /**
-     * Register a toggle action shown beneath the AI input bar. While active,
-     * its `decoratePrompt()` annotates the next outgoing prompt.
-     */
-    registerInputAction(contribution: PluginInputActionContribution): Disposable;
-    /**
-     * Register a card renderer keyed by `type`. Cards rendered beneath a message
-     * come from tool results' out-of-band `details.cards` (or `pendingFor` for
-     * in-flight tools); the host resolves each card's `type` to a registered
-     * renderer. Multiple cards under one message are shown as a tab-switcher
-     * ("收纳") or a flat list.
-     */
-    registerCardRenderer(contribution: PluginCardRendererContribution): Disposable;
-    /**
-     * Register a renderer that replaces the host's default inline transcript UI
-     * for a tool call (matched by `toolName`). The complement to card renderers:
-     * use it to render UI for a plugin's own agent tool output.
-     */
-    registerToolCallSlot(contribution: PluginToolCallSlotContribution): Disposable;
-    /**
-     * Register a card rendered at the bottom of the message list for the latest
-     * turn — NOT bound to a tool call. The host mounts the component in the
-     * footer slot; the plugin owns visibility (return `null` to render nothing,
-     * e.g. git renders only in a repo with changes). Gated by `scope_use`
-     * (fail-closed). Needs the `ui.slot.turn-card` permission.
-     */
-    registerTurnCard(contribution: PluginTurnCardContribution): Disposable;
-    /**
-     * Programmatically attach (if needed) and activate one of this plugin's
-     * own activity tabs in the current conversation's activity panel. `tabId`
-     * is the contribution id passed to registerActivityTab. Any payload (e.g.
-     * which image to edit) is passed via the plugin's own in-memory state.
-     *
-     * Pass `options.width` to size the panel as it opens — a pixel number, or
-     * `"max"` to expand it to the widest the current window allows (the host
-     * still clamps to its min/max and auto-hides the sidebar when needed). Omit
-     * to leave the user's current width untouched.
-     */
-    openActivityTab(tabId: string, options?: PluginOpenActivityTabOptions): void;
-    /**
-     * Bind (or clear, with `null`) an image as the "edit target" for the next
-     * outgoing prompt. The host renders it as a thumbnail capsule in the AI input
-     * bar's top capsule strip and, at send time, injects `metadata.editImageId`
-     * (the ref's id) so this turn edits that image. One-shot: cleared after the
-     * prompt is sent (or when the user closes the capsule). Only the image
-     * reference (id/url) crosses over — bytes stay out-of-band.
-     */
-    setEditImageAttachment(ref: PluginImageRef | null): void;
-    /**
-     * Open the host's global full-screen image previewer for the given image.
-     * Only the image reference (id/url) crosses over — bytes stay out-of-band.
-     *
-     * Pass `group` (e.g. all images of the message) to open as an image group:
-     * the previewer shows a thumbnail strip + arrows and starts at `ref`.
-     */
-    previewImage(ref: PluginImageRef, group?: PluginImageRef[]): void;
-    /**
-     * Open the app settings, scrolled to and highlighting THIS plugin's own
-     * settings section (e.g. so the user can fill in a required API key/model).
-     * The host owns the navigation; the plugin only asks to jump there.
-     */
-    openPluginSettings(): void;
-    /**
-     * Show a global toast in the host UI (bottom-right). No permission required.
-     * Prefer this over swallowing errors into opaque UI copy: pass `error` so
-     * the host attaches a one-click "copy stack" action for the user.
-     *
-     * Capture `ctx.ui.notify` in `activate` if React components need it
-     * (components do not receive `ctx`).
-     */
-    notify(options: PluginNotifyOptions): void;
-}
-/**
- * Options for {@link PluginUiApi.notify}. Surfaces a host toast so users can
- * see plugin failures without opening DevTools.
- */
-export interface PluginNotifyOptions {
-    /** Toast body. Required even when `error` is set (user-facing summary). */
-    message: string;
-    /** Defaults to plugin display name when omitted. */
-    title?: string;
-    /** Defaults to `"info"`; when `error` is set and variant omitted, host uses `"error"`. */
-    variant?: "info" | "success" | "warning" | "error";
-    /**
-     * Optional failure cause. Host formats message + stack and adds a
-     * "复制堆栈" action so the user can paste it into bug reports / chat.
-     */
-    error?: unknown;
-    /**
-     * Auto-dismiss delay in ms. `0` keeps the toast until dismissed.
-     * Defaults: sticky (`0`) when `error` is present, otherwise host default (~4s).
-     */
-    durationMs?: number;
-}
-export interface ConversationState {
-    /** Active session runtimeId, or null when no conversation is active. */
-    id: string | null;
-    cwd: string | null;
-    sessionPath: string | null;
-    model: string | null;
-    isStreaming: boolean;
-}
-export interface ConversationMessage {
-    id: string;
-    role: "user" | "assistant" | "compaction";
-    text: string;
-    timestamp?: number;
-}
-export type ConversationEvent = {
-    type: "turn-start";
-} | {
-    type: "turn-end";
-    stopReason: string;
-} | {
-    type: "message-added";
-    message: ConversationMessage;
-} | {
-    type: "message-updated";
-    delta: string;
-} | {
-    type: "tool-call-start";
-    toolCallId: string;
-    toolName: string;
-} | {
-    type: "tool-call-end";
-    toolCallId: string;
-    toolName: string;
-    isError: boolean;
-} | {
-    type: "conversation-changed";
-    conversation: ConversationState;
-};
-export interface PluginConversationApi {
-    /** Send a prompt into the active conversation (renders as a user turn). */
-    sendPrompt(text: string): Promise<void>;
-    /** Fill the input bar without sending; the user can edit and send. */
-    insertText(text: string): void;
-    /** Abort the active conversation's current turn. */
-    abort(): Promise<void>;
-    /** Subscribe to real-time conversation events. */
-    on(listener: (event: ConversationEvent) => void): Disposable;
-}
-export type PluginJsonSchema = object;
-export interface PluginAgentToolApi {
-    fs: PluginFsApi;
-    conversation: PluginConversationApi;
-}
-export interface PluginAgentToolRegistration<TInput = unknown> {
-    id: string;
-    name?: string;
-    label?: string;
-    description: string;
-    parameters: PluginJsonSchema;
-    timeoutMs?: number;
-    /**
-     * 允许该工具出现的对话场景 slug 列表。**fail-closed**：未声明/空数组 = 所有场景都不激活。
-     * 插件须显式声明。
-     */
-    scope_use?: readonly ConversationScenario[];
-    /** 需要的会话能力 slug（如 "knowledge"）；全满足才激活。一般插件无需设置。 */
-    requires?: string[];
-    /** 允许该工具出现的工作模式 slug（agent_mode 轴，如 "work"/"coding"）。缺省/空 = 通用。见 ADR-0046。 */
-    agent_mode?: readonly string[];
-    context?: {
-        conversation?: "summary" | "messages";
-    };
-    handler: PluginAgentToolHandler<TInput>;
-}
-export interface PluginSystemPromptBlock {
-    id: string;
-    content: string;
-    priority?: number;
-    enabled?: boolean;
-}
-export type PluginDynamicSystemPromptOperation = {
-    type: "addBlock";
-    block: PluginSystemPromptBlock;
-} | {
-    type: "replaceBlock";
-    blockId: string;
-    block: Omit<PluginSystemPromptBlock, "id">;
-} | {
-    type: "updateBlock";
-    blockId: string;
-    patch: Partial<Pick<PluginSystemPromptBlock, "content" | "priority" | "enabled">>;
-} | {
-    type: "removeBlock";
-    blockId: string;
-} | {
-    type: "setBlockEnabled";
-    blockId: string;
-    enabled: boolean;
-} | {
-    type: "setToolEnabled";
-    toolName: string;
-    enabled: boolean;
-} | {
-    type: "requestContinuation";
-    result: PluginContinuationResult;
-};
-export interface PluginSystemPromptMessage {
-    role: string;
-    text: string;
-    timestamp?: number;
-    toolName?: string;
-}
-export interface PluginSystemPromptProviderContext {
-    plugin: {
-        id: string;
-        providerId: string;
-        settings: Readonly<Record<string, unknown>>;
-    };
-    session: {
-        id: string;
-        cwd: string;
-        scenario: ConversationScenario;
-    };
-    model: {
-        provider: string;
-        id: string;
-        api: string;
-        input: readonly string[];
-        contextWindow?: number;
-        maxTokens?: number;
-    };
-    conversation: {
-        messages: readonly PluginSystemPromptMessage[];
-        messageCount: number;
-    };
-    runtime: {
-        activeToolNames: readonly string[];
-        availableToolNames: readonly string[];
-        runIndex: number;
-    };
-    trigger: {
-        kind: "agent-run";
-        timestamp: number;
-    };
-    systemPrompt?: {
-        base: {
-            blocks?: readonly PluginSystemPromptBlockView[];
-            rendered?: string;
-        };
-        current: {
-            blocks?: readonly PluginSystemPromptBlockView[];
-            rendered?: string;
-        };
-    };
-}
-export interface PluginSystemPromptBlockView extends PluginSystemPromptBlock {
-    type: string;
-    source: {
-        kind: "core" | "plugin";
-        pluginId?: string;
-    };
-    priority: number;
-    enabled: boolean;
-}
-export interface PluginAgentActions {
-    systemPrompt: {
-        addBlock(block: PluginSystemPromptBlock): void;
-        replaceBlock(blockId: string, block: Omit<PluginSystemPromptBlock, "id">): void;
-        updateBlock(blockId: string, patch: Partial<Pick<PluginSystemPromptBlock, "content" | "priority" | "enabled">>): void;
-        removeBlock(blockId: string): void;
-        setBlockEnabled(blockId: string, enabled: boolean): void;
-    };
-    tools: {
-        setEnabled(toolName: string, enabled: boolean): void;
-        enable(toolName: string): void;
-        disable(toolName: string): void;
-    };
-    continuation: {
-        request(result: PluginContinuationResult): void;
-    };
-}
-export interface PluginAgentHandlerContext<TTrigger> {
-    invocationId: string;
-    plugin: {
-        id: string;
-        contributionId: string;
-        settings: Readonly<Record<string, unknown>>;
-    };
-    session: PluginSystemPromptProviderContext["session"];
-    model: PluginSystemPromptProviderContext["model"];
-    conversation: PluginSystemPromptProviderContext["conversation"];
-    runtime: PluginSystemPromptProviderContext["runtime"];
-    trigger: TTrigger;
-    systemPrompt?: PluginSystemPromptProviderContext["systemPrompt"];
-    actions: PluginAgentActions;
-    host: PluginAgentToolApi;
-}
-export type PluginAgentToolHandler<TInput = unknown> = (context: PluginAgentHandlerContext<{
-    kind: "tool-call";
-    timestamp: number;
-    toolCallId: string;
-    toolId: string;
-    toolName: string;
-    input: TInput;
-}>) => unknown | Promise<unknown>;
-export type PluginSystemPromptProviderHandler = (context: PluginAgentHandlerContext<{
-    kind: "agent-run";
-    timestamp: number;
-}>) => void | PluginDynamicSystemPromptOperation[] | Promise<void | PluginDynamicSystemPromptOperation[]>;
-export interface PluginSystemPromptProviderRegistration {
-    id: string;
-    timeoutMs?: number;
-    /**
-     * Large context is opt-in. Omitted fields are not serialized across the
-     * host/renderer boundary.
-     */
-    context?: {
-        systemPrompt?: "none" | "blocks" | "rendered" | "full";
-        conversation?: "summary" | "messages";
-    };
-    handler: PluginSystemPromptProviderHandler;
-}
-export interface PluginAgentApi {
-    registerTool<TInput = unknown>(registration: PluginAgentToolRegistration<TInput>): Disposable;
-    /** Register a provider evaluated before every Agent run. */
-    registerSystemPromptProvider(registration: PluginSystemPromptProviderRegistration): Disposable;
-    /**
-     * Register a policy consulted when the agent reaches a natural stopping point.
-     * Return null to allow the agent to stop, or a message to continue with another turn.
-     */
-    registerContinuationProvider(registration: PluginContinuationRegistration): Disposable;
-}
-export interface PluginContinuationResult {
-    text: string;
-    /** Stable key used by the host to suppress duplicate continuations in a session. */
-    idempotencyKey?: string;
-}
-export type PluginContinuationHandler = (context: PluginAgentHandlerContext<{
-    kind: "continuation";
-    timestamp: number;
-}>) => PluginContinuationResult | null | Promise<PluginContinuationResult | null>;
-export interface PluginContinuationRegistration {
-    id: string;
-    timeoutMs?: number;
-    context?: {
-        conversation?: "summary" | "messages";
-    };
-    handler: PluginContinuationHandler;
-}
-export type PluginAppActionEffect = "read" | "write" | "execute";
-export interface PluginAppActionExample<TInput = unknown> {
-    description: string;
-    input: TInput;
-}
-export interface PluginAppActionHandlerContext<TInput = unknown> {
-    invocationId: string;
-    plugin: {
-        id: string;
-        actionId: string;
-        settings: Readonly<Record<string, unknown>>;
-    };
-    input: TInput;
-    signal: AbortSignal;
-}
-export type PluginAppActionHandler<TInput = unknown> = (context: PluginAppActionHandlerContext<TInput>) => unknown | Promise<unknown>;
-export type PluginAppActionReadyHandler<TInput = unknown> = (context: PluginAppActionHandlerContext<TInput>) => void | Promise<void>;
-/** 插件 Action 向宿主返回稳定错误码与可序列化详情。 */
-export declare class PluginAppActionError extends Error {
-    readonly code: string;
-    readonly details?: unknown;
-    constructor(code: string, message: string, details?: unknown);
-}
-export interface PluginAppActionApprovalPresentation {
-    id: string;
-    title: string;
-    description: string;
-}
-export interface PluginAppActionApproval {
-    /** 默认使用的宿主审批界面。 */
-    defaultPresentation: string;
-    /** 可用的宿主审批界面；仅官方插件可以声明。 */
-    presentations: PluginAppActionApprovalPresentation[];
-    /** 根据 input.operation 自动选择审批界面，不要求 Agent 传 approvalUi。 */
-    presentationByOperation?: Record<string, string>;
-    /** 某 operation 明确允许的附加审批界面；宿主仍会拒绝未列出的调用方选择。 */
-    alternativePresentationsByOperation?: Record<string, string[]>;
-}
-export interface PluginAppActionRegistration<TInput = unknown> {
-    /** 插件内局部 id；宿主公开为 `plugin.<pluginId>.<id>`。 */
-    id: string;
-    /** 可信官方插件可指定稳定公共 id；若 id 已被占用则后到者忽略（先注册为准）。 */
-    publicId?: string;
-    title: string;
-    summary: string;
-    description?: string;
-    keywords?: string[];
-    effect: PluginAppActionEffect;
-    /** 官方插件可引用宿主已有审批界面；不能关闭 effect 对应的审批。 */
-    approval?: PluginAppActionApproval;
-    inputSchema: PluginJsonSchema;
-    examples?: PluginAppActionExample<TInput>[];
-    timeoutMs?: number;
-    /** 审批前业务就绪校验；失败时不会向用户弹出审批。 */
-    assertReady?: PluginAppActionReadyHandler<TInput>;
-    handler: PluginAppActionHandler<TInput>;
-}
-export interface PluginAppActionsApi {
-    register<TInput = unknown>(registration: PluginAppActionRegistration<TInput>): Disposable;
-}
-export interface PluginOfficialGeneralSettings {
-    workspacePath: string;
-    defaultExecutionMode?: "sandbox" | "full-access";
-    notificationsEnabled: boolean;
-    debugMode: boolean;
-    sandbox: unknown;
-}
-export type PluginOfficialGeneralSettingsUpdate = {
-    operation: "set-notifications";
-    enabled: boolean;
-} | {
-    operation: "set-execution-mode";
-    mode: "sandbox" | "full-access";
-} | {
-    operation: "set-workspace";
-    path: string;
-};
-export interface PluginOfficialExperimentalSettings {
-    vettaCli: boolean;
-    promptPrediction: boolean;
-    agentSkills: boolean;
-}
-export interface PluginOfficialDownloadItem {
-    id: string;
-    url: string;
-    filename: string;
-    path: string;
-    totalBytes: number;
-    receivedBytes: number;
-    status: "queued" | "downloading" | "paused" | "completed" | "failed" | "canceled";
-    error?: string;
-    createdAt: number;
-    completedAt?: number;
-    speedBytesPerSec?: number;
-}
-export interface PluginOfficialUpdaterState {
-    phase: "idle" | "checking" | "available" | "downloading" | "ready" | "installing" | "error";
-    currentVersion: string;
-    latestVersion?: string;
-    releaseNote?: string;
-    progress?: number;
-    downloadedBytes?: number;
-    totalBytes?: number;
-    assetFileName?: string;
-    error?: string;
-    pendingInstall: boolean;
-}
-export type PluginOfficialWebhookKind = "feishu" | "dingtalk";
-export interface PluginOfficialWebhookEndpoint {
-    id: string;
-    kind: PluginOfficialWebhookKind;
-    name: string;
-    enabled: boolean;
-    createdAt: string;
-    updatedAt: string;
-    urlMask?: string;
-    hasSignSecret?: boolean;
-}
-export interface PluginOfficialWebhookProvider {
-    kind: PluginOfficialWebhookKind;
-    displayName: string;
-    iconClass?: string;
-}
-export interface PluginOfficialWebhookCreateInput {
-    kind: PluginOfficialWebhookKind;
-    name: string;
-    webhookUrl: string;
-    signSecret?: string;
-    enabled?: boolean;
-}
-export interface PluginOfficialWebhookUpdateInput {
-    name?: string;
-    enabled?: boolean;
-    webhookUrl?: string;
-    signSecret?: string;
-}
-export interface PluginOfficialWebhookMessage {
-    title?: string;
-    text: string;
-    level?: "info" | "warn" | "error" | "success";
-}
-export interface PluginOfficialWebhookSendResult {
-    ok: boolean;
-    error?: string;
-}
-export interface PluginOfficialSkillInfo {
-    name: string;
-    alias?: string;
-    description: string;
-    source: string;
-    type: "skill" | "scene";
-}
-export type PluginOfficialInstalledSkill = {
-    name: string;
-    version: string;
-    installedAt: string;
-    source: "market" | "custom";
-    enabled: boolean;
-    type?: "skill" | "scene";
-    alias?: string;
-    marketDescription?: string;
-    description?: string;
-};
-export interface PluginOfficialShortcutBinding {
-    id: string;
-    defaultShortcut: string;
-    shortcut: string;
-    isDefault: boolean;
-}
-export interface PluginOfficialQuickPanelSettings {
-    trigger: "none" | "mod" | "alt" | "shift";
-    postSendBehavior: "foreground" | "background";
-}
-export interface PluginOfficialImStatus {
-    enabled: boolean;
-    transport: string;
-    agentModel: {
-        provider: string;
-        model: string;
-        reasoningLevel?: string;
-    } | null;
-    wechatBound: boolean;
-    feishuAppId: string | null;
-    runtime: unknown;
-}
-export interface PluginOfficialImLog {
-    level: string;
-    msg: string;
-    time: string;
-    fields?: Record<string, unknown>;
-}
-export interface PluginOfficialMcpServerSummary {
-    name: string;
-    type: "http" | "stdio";
-    disabled: boolean;
-    command?: string;
-    url?: string;
-}
-export interface PluginOfficialMcpServerDetail {
-    name: string;
-    type?: "http" | "stdio";
-    command?: string;
-    args?: string[];
-    env?: Record<string, string>;
-    cwd?: string;
-    url?: string;
-    headers?: Record<string, string>;
-    disabled?: boolean;
-    autoApprove?: string[];
-    startupTimeout?: number;
-    debug?: boolean;
-}
-export type PluginOfficialMcpUpsertData = {
-    type?: "stdio";
-    command?: string;
-    args?: string[];
-    env?: Record<string, string>;
-    cwd?: string;
-    disabled?: boolean;
-    autoApprove?: string[];
-    startupTimeout?: number;
-    debug?: boolean;
-} | {
-    type: "http";
-    url?: string;
-    headers?: Record<string, string>;
-    disabled?: boolean;
-    autoApprove?: string[];
-    startupTimeout?: number;
-    debug?: boolean;
-};
-export type PluginOfficialExecutionMode = "inherit" | "sandbox" | "full-access";
-export interface PluginOfficialSelectedSkill {
-    name: string;
-    alias?: string;
-    type: "skill" | "scene";
-}
-export interface PluginOfficialBatchProjectCreateData {
-    name: string;
-    prompt: string;
-    modelKey?: string;
-    folders: string[];
-    concurrency: number;
-    executionMode?: PluginOfficialExecutionMode;
-    artifactPatterns?: string[];
-    notifyEnabled?: boolean;
-    timeoutMinutes?: number;
-    skill?: PluginOfficialSelectedSkill;
-}
-export interface PluginOfficialBatchProjectUpdateData {
-    name?: string;
-    prompt?: string;
-    modelKey?: string;
-    concurrency?: number;
-    executionMode?: PluginOfficialExecutionMode;
-    artifactPatterns?: string[];
-    notifyEnabled?: boolean;
-    timeoutMinutes?: number;
-    newFolders?: string[];
-    skill?: PluginOfficialSelectedSkill | null;
-}
-export interface PluginOfficialSchedulerTaskCreateData {
-    name: string;
-    prompt: string;
-    cron: string;
-    isOnce: boolean;
-    enabled?: boolean;
-    cwd: string;
-    modelKey?: string;
-    executionMode?: PluginOfficialExecutionMode;
-    skill?: PluginOfficialSelectedSkill;
-}
-export interface PluginOfficialSchedulerTaskUpdateData {
-    name?: string;
-    prompt?: string;
-    cron?: string;
-    isOnce?: boolean;
-    enabled?: boolean;
-    cwd?: string;
-    modelKey?: string | null;
-    executionMode?: PluginOfficialExecutionMode;
-    skill?: PluginOfficialSelectedSkill | null;
-}
-export interface PluginOfficialModelSummary {
-    id: string;
-    name?: string;
-    api?: string;
-    reasoning?: boolean;
-}
-export interface PluginOfficialProviderSummary {
-    id: string;
-    displayName: string;
-    baseUrl?: string;
-    api?: string;
-    hasApiKey: boolean;
-    modelCount: number;
-    models: PluginOfficialModelSummary[];
-}
-export interface PluginOfficialProviderDetail {
-    baseUrl?: string;
-    apiKey?: string;
-    api?: string;
-    displayName?: string;
-    authHeader?: boolean;
-    headers?: Record<string, string>;
-    models?: Array<{
-        id: string;
-        name?: string;
-        api?: string;
-        reasoning?: boolean;
-        contextWindow?: number;
-        maxTokens?: number;
-    }>;
-}
-export interface PluginOfficialProviderUpsertData {
-    baseUrl?: string;
-    apiKey?: string;
-    api?: string;
-    displayName?: string;
-    authHeader?: boolean;
-    headers?: Record<string, string>;
-    models?: Array<{
-        id: string;
-        name?: string;
-        api?: string;
-        reasoning?: boolean;
-        contextWindow?: number;
-        maxTokens?: number;
-    }>;
-}
-export interface PluginOfficialProjectEntry {
-    path: string;
-    name?: string;
-}
-export interface PluginOfficialPluginSummary {
-    id: string;
-    name: string;
-    version: string;
-    enabled: boolean;
-    required: boolean;
-    source: string;
-    permissions: string[];
-    description?: string;
-    devWatch?: unknown;
-}
-export interface PluginOfficialKnowledgeBase {
-    id: string;
-    name: string;
-    updatedAt: number;
-    isDefault: boolean;
-    nodes: unknown[];
-}
-export interface PluginOfficialKnowledgeProcessingSettings {
-    enabled?: boolean;
-    pollIntervalMinutes?: number;
-    processingModelKey?: string;
-    processingModelReasoningLevel?: string;
-    agentConcurrency?: number;
-    ocrConcurrency?: number;
-}
-/** 仅宿主验证为官方来源的插件可以调用；普通插件调用时由宿主拒绝。 */
-export interface PluginOfficialApi {
-    general: {
-        getSettings(): Promise<PluginOfficialGeneralSettings>;
-        setSettings(input: PluginOfficialGeneralSettingsUpdate): Promise<PluginOfficialGeneralSettingsUpdate>;
-    };
-    agent: {
-        getExperimental(): Promise<PluginOfficialExperimentalSettings>;
-        setExperimental(input: Partial<PluginOfficialExperimentalSettings>): Promise<PluginOfficialExperimentalSettings>;
-    };
-    downloads: {
-        list(): Promise<PluginOfficialDownloadItem[]>;
-        cancel(id: string): Promise<void>;
-    };
-    updater: {
-        getState(): Promise<PluginOfficialUpdaterState>;
-        getCurrentVersion(): Promise<string>;
-        check(): Promise<PluginOfficialUpdaterState>;
-        download(): Promise<PluginOfficialUpdaterState>;
-        install(): Promise<void>;
-        dismiss(): Promise<void>;
-        cancel(): Promise<void>;
-    };
-    webhook: {
-        list(): Promise<PluginOfficialWebhookEndpoint[]>;
-        listProviders(): Promise<PluginOfficialWebhookProvider[]>;
-        create(input: PluginOfficialWebhookCreateInput): Promise<PluginOfficialWebhookEndpoint>;
-        update(id: string, input: PluginOfficialWebhookUpdateInput): Promise<PluginOfficialWebhookEndpoint>;
-        setEnabled(id: string, enabled: boolean): Promise<PluginOfficialWebhookEndpoint>;
-        delete(id: string): Promise<void>;
-        test(id: string): Promise<PluginOfficialWebhookSendResult>;
-        send(id: string, message: PluginOfficialWebhookMessage): Promise<PluginOfficialWebhookSendResult>;
-    };
-    skills: {
-        list(cwd?: string): Promise<PluginOfficialSkillInfo[]>;
-        getManifest(): Promise<Record<string, PluginOfficialInstalledSkill>>;
-        setEnabled(name: string, enabled: boolean): Promise<{
-            name: string;
-            enabled: boolean;
-        }>;
-        uninstall(name: string, type?: "skill" | "scene"): Promise<void>;
-    };
-    shortcuts: {
-        listAvailableActions(): Array<{
-            id: string;
-            defaultShortcut: string;
-        }>;
-        get(): Promise<{
-            bindings: PluginOfficialShortcutBinding[];
-            quickPanel: PluginOfficialQuickPanelSettings;
-        }>;
-        setBinding(id: string, shortcut: string): Promise<{
-            bindings: PluginOfficialShortcutBinding[];
-        }>;
-        resetBinding(id: string): Promise<{
-            bindings: PluginOfficialShortcutBinding[];
-            shortcut: string;
-        }>;
-        resetAllBindings(): Promise<{
-            bindings: PluginOfficialShortcutBinding[];
-        }>;
-        setQuickPanelTrigger(trigger: PluginOfficialQuickPanelSettings["trigger"]): Promise<PluginOfficialQuickPanelSettings>;
-        setQuickPanelBehavior(behavior: PluginOfficialQuickPanelSettings["postSendBehavior"]): Promise<PluginOfficialQuickPanelSettings>;
-    };
-    im: {
-        getStatus(): Promise<PluginOfficialImStatus>;
-        getLogs(limit?: number): Promise<PluginOfficialImLog[]>;
-        setEnabled(enabled: boolean): Promise<{
-            status: unknown;
-        }>;
-        restart(): Promise<{
-            status: unknown;
-        }>;
-        setAgentModel(modelKey: string | null, reasoningLevel?: string): Promise<{
-            status: unknown;
-        }>;
-        assertModelKeyExists(modelKey: string): Promise<void>;
-    };
-    mcp: {
-        list(): Promise<PluginOfficialMcpServerSummary[]>;
-        get(name: string): Promise<PluginOfficialMcpServerDetail>;
-        listNames(): Promise<string[]>;
-        upsert(name: string, data: PluginOfficialMcpUpsertData): Promise<PluginOfficialMcpServerDetail>;
-        setEnabled(name: string, enabled: boolean): Promise<void>;
-        remove(name: string): Promise<void>;
-    };
-    models: {
-        list(): Promise<{
-            defaultModel: string | null;
-            providers: PluginOfficialProviderSummary[];
-        }>;
-        get(provider?: string): Promise<unknown>;
-        probe(provider: string, model: string): Promise<{
-            ok: boolean;
-            message?: string;
-            error?: string;
-        }>;
-        listProviderIds(): Promise<string[]>;
-        assertModelKeyExists(modelKey: string, operation?: string): Promise<void>;
-        setDefault(modelKey: string): Promise<{
-            defaultModel: string;
-        }>;
-        upsertProvider(provider: string, data: PluginOfficialProviderUpsertData): Promise<PluginOfficialProviderDetail>;
-        removeProvider(provider: string): Promise<void>;
-    };
-    projects: {
-        list(): Promise<{
-            workspacePath: string;
-            projects: PluginOfficialProjectEntry[];
-            archivedProjects: PluginOfficialProjectEntry[];
-        }>;
-        listSessions(cwd: string): Promise<unknown[]>;
-        listRuntimeProjects(): Promise<unknown[]>;
-        create(name: string, path?: string): Promise<PluginOfficialProjectEntry>;
-        open(path: string, name?: string): Promise<PluginOfficialProjectEntry>;
-        rename(path: string, name: string): Promise<PluginOfficialProjectEntry>;
-        archive(path: string): Promise<void>;
-        unarchive(path: string): Promise<void>;
-        remove(path: string): Promise<void>;
-    };
-    plugins: {
-        list(): Promise<PluginOfficialPluginSummary[]>;
-        get(id: string): Promise<PluginOfficialPluginSummary>;
-        setEnabled(id: string, enabled: boolean): Promise<PluginOfficialPluginSummary>;
-        installFromUrl(url: string): Promise<PluginOfficialPluginSummary>;
-        installFromPath(path: string, options?: {
-            grantedPermissions?: string[];
-            enable?: boolean;
-        }): Promise<PluginOfficialPluginSummary>;
-        uninstall(id: string): Promise<void>;
-        reload(id: string): Promise<PluginOfficialPluginSummary>;
-    };
-    knowledge: {
-        list(): Promise<PluginOfficialKnowledgeBase[]>;
-        fileStatuses(): Promise<Record<string, unknown>>;
-        isProcessing(): Promise<boolean>;
-        getProcessing(): Promise<PluginOfficialKnowledgeProcessingSettings>;
-        create(name: string): Promise<void>;
-        rename(name: string, newName: string): Promise<void>;
-        delete(name: string): Promise<void>;
-        addFiles(kbId: string, paths: string[], move?: boolean): Promise<void>;
-        deleteEntry(kbId: string, relPath: string): Promise<void>;
-        scanNow(): Promise<{
-            skipped: boolean;
-            reason?: string;
-        }>;
-        retryFailed(): Promise<{
-            skipped: boolean;
-            reason?: string;
-        }>;
-        setProcessing(data: Partial<{
-            enabled: boolean;
-            pollIntervalMinutes: 3 | 5 | 10 | 30;
-            processingModelKey: string | null;
-            processingModelReasoningLevel: string | null;
-            agentConcurrency: number;
-            ocrConcurrency: number;
-        }>): Promise<PluginOfficialKnowledgeProcessingSettings>;
-    };
-    batchTasks: {
-        listProjects(): Promise<unknown[]>;
-        getProject(projectId: string): Promise<unknown>;
-        listProjectIds(): Promise<string[]>;
-        createProject(data: PluginOfficialBatchProjectCreateData): Promise<unknown>;
-        updateProject(projectId: string, data: PluginOfficialBatchProjectUpdateData): Promise<unknown>;
-        deleteProject(projectId: string): Promise<unknown>;
-        runTask(projectId: string, taskId: string): Promise<unknown>;
-        retryTask(projectId: string, taskId: string): Promise<unknown>;
-        stopTask(projectId: string, taskId: string): Promise<unknown>;
-        deleteTask(projectId: string, taskId: string): Promise<unknown>;
-        resumeTask(projectId: string, taskId: string): Promise<unknown>;
-        resumeTaskWithText(projectId: string, taskId: string, text: string): Promise<unknown>;
-        deleteTaskSession(projectId: string, taskId: string): Promise<unknown>;
-        batchDelete(projectId: string): Promise<unknown>;
-        batchStart(projectId: string): Promise<unknown>;
-        batchStop(projectId: string): Promise<unknown>;
-        batchReset(projectId: string): Promise<unknown>;
-        batchResetFailed(projectId: string, taskIds: string[]): Promise<unknown>;
-    };
-    scheduler: {
-        listTasks(): Promise<unknown[]>;
-        getTask(taskId: string): Promise<unknown>;
-        listTaskIds(): Promise<string[]>;
-        getHistory(taskId: string): Promise<unknown[]>;
-        createTask(data: PluginOfficialSchedulerTaskCreateData): Promise<unknown>;
-        updateTask(taskId: string, data: PluginOfficialSchedulerTaskUpdateData): Promise<unknown>;
-        deleteTask(taskId: string): Promise<unknown>;
-        setEnabled(taskId: string, enabled: boolean): Promise<unknown>;
-        runNow(taskId: string): Promise<unknown>;
-        abort(taskId: string): Promise<unknown>;
-    };
-    appearance: {
-        help(): Promise<unknown>;
-        get(): Promise<unknown>;
-        set(input: {
-            mode?: "light" | "dark" | "auto";
-            themeId?: string;
-            cursorStyle?: "default" | "stoat";
-        }): Promise<unknown>;
-        setLanguage(language: "zh" | "en"): Promise<unknown>;
-        listThemeIds(): string[];
-    };
-    navigation: {
-        help(): unknown;
-        resolveOpen(input: {
-            target: string;
-            tab?: string;
-            section?: string;
-        }): {
-            hashPath: string;
-            resolved: unknown;
-        };
-        open(input: {
-            target: string;
-            tab?: string;
-            section?: string;
-        }): Promise<unknown>;
-    };
-}
-export interface PluginFsEntry {
-    name: string;
-    path: string;
-    isDirectory: boolean;
-    size: number;
-    modifiedAt: number;
-}
-export interface PluginFsFileRef {
-    name: string;
-    path: string;
-    relPath: string;
-}
-export interface PluginFsStatResult {
-    size: number;
-    modifiedAt: number;
-    createdAt: number;
-}
-export interface PluginFsReadResult {
-    content: string;
-    encoding: "utf8" | "base64";
-}
-export interface PluginFsApi {
-    readDir(dirPath: string): Promise<PluginFsEntry[]>;
-    readFile(filePath: string): Promise<PluginFsReadResult>;
-    /** Pass `encoding: "base64"` to write binary payloads (decoded from base64 text). */
-    writeFile(filePath: string, content: string, encoding?: "utf8" | "base64"): Promise<void>;
-    stat(filePath: string): Promise<PluginFsStatResult | null>;
-    rename(oldPath: string, newPath: string): Promise<void>;
-    delete(targetPath: string): Promise<void>;
-    move(sourcePath: string, destDir: string): Promise<void>;
-    createDirectory(dirPath: string): Promise<void>;
-    listFilesRecursive(rootPath: string): Promise<PluginFsFileRef[]>;
-}
-export interface PluginCommandRunOptions {
-    /** Working directory. Must resolve inside a host-allowed root (e.g. a project). */
-    cwd?: string;
-    /** Extra environment entries, merged over the host process env (PATH preserved). */
-    env?: Record<string, string>;
-    /** Hard timeout in ms; the host clamps to its own maximum. */
-    timeoutMs?: number;
-}
-export interface PluginCommandRunResult {
-    stdout: string;
-    stderr: string;
-    /** Process exit code; null when the process was killed by a signal/timeout. */
-    exitCode: number | null;
-}
-/**
- * Run an allowed host command (e.g. `git`). execFile semantics — NO shell, args
- * are passed as an array (no string splitting, no injection). The executable
- * must be declared in plugin.json's `commands` and currently enabled by the
- * user; otherwise the call is rejected (and the host notifies the user). Needs
- * the `agent.command.run` permission.
- */
-export interface PluginCommandApi {
-    run(file: string, args?: string[], options?: PluginCommandRunOptions): Promise<PluginCommandRunResult>;
-}
-export interface PluginPermissionApi {
-    has(permission: PluginPermission): boolean;
-    require(permission: PluginPermission): void;
-}
-export interface PluginGenerateImageInput {
-    prompt: string;
-    /** Output size (e.g. "1024x1024"), decided by the agent and forwarded to the model. */
-    size?: string;
-    /** Optional reference id for grouping (e.g. the conversation/session). */
-    sessionId?: string;
-}
-export interface PluginEditImageInput {
-    prompt: string;
-    /**
-     * Source image to edit. Either an existing host image id (continue a
-     * lineage) or raw base64 bytes (e.g. a user upload).
-     */
-    source: {
-        imageId: string;
-    } | {
-        data: string;
-        mimeType: string;
-    };
-    sessionId?: string;
-}
-/**
- * Image generation, routed to the host's main-process image service (single
- * implementation shared with the agent's built-in image tool). Bytes are
- * stored out-of-band; results are returned as host media references.
- */
-export interface PluginImagesApi {
-    /** Text-to-image. Resolves to the produced image reference(s). */
-    generate(input: PluginGenerateImageInput): Promise<PluginImageRef[]>;
-    /** Image-to-image edit, producing the next version in a lineage. */
-    edit(input: PluginEditImageInput): Promise<PluginImageRef[]>;
-    /** The edit lineage (base image + its edits, oldest first) for an image. */
-    lineage(imageId: string): Promise<PluginImageRef[]>;
-    /**
-     * Every edit lineage the given session touched (generated or edited a version
-     * in), newest lineage first; each lineage's versions oldest → newest. The
-     * sessionId is the agent session id — derive it from the active conversation's
-     * `sessionPath` (the UUID embedded in the session file name).
-     */
-    sessionLineages(sessionId: string): Promise<PluginImageRef[][]>;
-}
-/**
- * Read-side access to this plugin's settings (the values configured against
- * the `contributes.settings` schema declared in plugin.json, namespaced by
- * plugin id). Writes go through the host's settings UI, not the plugin.
- */
-export interface PluginSettingsApi {
-    get<T = unknown>(key: string): T | undefined;
-    getAll(): Record<string, unknown>;
-    /** Fired when any of this plugin's setting values change. */
-    onChange(listener: (values: Record<string, unknown>) => void): Disposable;
-}
-/** A flat catalog: translation key → localized string. */
-export type PluginLocaleCatalog = Record<string, string>;
-/** Every catalog a plugin ships, keyed by locale code (e.g. "zh", "en"). */
-export type PluginLocales = Record<string, PluginLocaleCatalog>;
-/** Replace `{{name}}` placeholders in a resolved string with `params`. */
-export declare function interpolatePluginText(text: string, params?: Record<string, string | number>): string;
-/**
- * Resolve a bare catalog key against a plugin's catalogs. Fallback chain:
- * current-locale catalog → the plugin's `defaultLocale` catalog → the bare key
- * itself (a dev signal for a missing translation). Then interpolate `{{params}}`.
- */
-export declare function resolveCatalogKey(key: string, locales: PluginLocales, currentLocale: string, defaultLocale: string, params?: Record<string, string | number>): string;
-/**
- * Resolve a host-rendered plugin string. A value of the exact form `%key%` is a
- * catalog key (resolved via {@link resolveCatalogKey}); any other string is a
- * literal and returned unchanged — backwards compatible with bare strings.
- */
-export declare function resolvePluginText(raw: string, locales: PluginLocales, currentLocale: string, defaultLocale: string, params?: Record<string, string | number>): string;
-export type PluginTranslate = (key: string, params?: Record<string, string | number>) => string;
-/**
- * This plugin's i18n surface on the context. `locale` always equals the host's
- * current language; `t` resolves a BARE catalog key (no `%...%` wrapper) against
- * this plugin's catalogs at the current locale. Imperative — for plugin React
- * components prefer the reactive {@link useTranslation} hook.
- */
-export interface PluginI18nApi {
-    /** The host's current locale code (e.g. "zh"). */
-    readonly locale: string;
-    /** Resolve a bare catalog key at the current locale, with optional `{{params}}`. */
-    t: PluginTranslate;
-    /** Fired when the host language changes. */
-    onChange(listener: (locale: string) => void): Disposable;
-}
-/** 工作模式（agent_mode 轴，见 ADR-0046）。宿主 Work/Coding，未来可能扩展。 */
-export type AgentMode = "work" | "coding";
-export interface PluginContext {
-    plugin: {
-        id: string;
-        version: string;
-    };
-    permissions: PluginPermissionApi;
-    ui: PluginUiApi;
-    conversation: PluginConversationApi;
-    agent: PluginAgentApi;
-    appActions: PluginAppActionsApi;
-    official: PluginOfficialApi;
-    fs: PluginFsApi;
-    command: PluginCommandApi;
-    images: PluginImagesApi;
-    settings: PluginSettingsApi;
-    i18n: PluginI18nApi;
-    /** 当前工作模式（agent_mode 轴）。开发者据此做模式定制。见 ADR-0046。 */
-    getAgentMode(): AgentMode;
-    /** 订阅工作模式变更（纯全局实时切换）。返回 Disposable 取消订阅。 */
-    onAgentModeChanged(listener: (mode: AgentMode) => void): Disposable;
-}
-export interface PluginDefinition {
-    activate(ctx: PluginContext): void | Promise<void>;
-    deactivate?(): void | Promise<void>;
-}
-export declare function definePlugin(plugin: PluginDefinition): PluginDefinition;
-export interface PluginHostBridge {
-    useActiveConversation(): ConversationState;
-    useConversationMessages(): ConversationMessage[];
-    useEditImageAttachment(): PluginImageRef | null;
-    /** Reactive: the host's current locale code (e.g. "zh"). */
-    useLocale(): string;
-    conversation: PluginConversationApi;
-}
-export declare function __setPluginHostBridge(bridge: PluginHostBridge): void;
-export interface ActivityTabContextValue {
-    /**
-     * The cwd scope of the activity panel this tab is rendered in — the same
-     * key the attach record uses. Do NOT substitute useActiveConversation().cwd:
-     * on the project detail page the panel cwd is the project's, while the
-     * active conversation may belong to another project (or be null).
-     */
-    cwd: string | null;
-}
-/**
- * Internal: the host wraps attached activity-tab components in this context's
- * Provider. Module Federation shares this single SDK instance, so the value
- * the host provides is visible to plugin components.
- */
-export declare const __ActivityTabContext: import("react").Context<ActivityTabContextValue>;
-/** The panel scope of the activity tab this component is rendered in. */
-export declare function useActivityTab(): ActivityTabContextValue;
-export interface PluginI18nContextValue {
-    /** This plugin's catalogs, keyed by locale code. */
-    locales: PluginLocales;
-    /** Fallback locale when a key is missing in the current locale. */
-    defaultLocale: string;
-}
-/**
- * Internal: the host wraps plugin-rendered components in this context's Provider,
- * carrying THIS plugin's catalogs. Module Federation shares this single SDK
- * instance, so the value the host provides is visible to {@link useTranslation}.
- */
-export declare const __PluginI18nContext: import("react").Context<PluginI18nContextValue>;
-export interface PluginTranslation {
-    /** The host's current locale code (e.g. "zh"). */
-    locale: string;
-    /** Resolve a bare catalog key at the current locale, with optional `{{params}}`. */
-    t: PluginTranslate;
-}
-/**
- * Reactive translation for plugin React components — re-renders when the host
- * language changes. `t` resolves a BARE catalog key (no `%...%` wrapper) against
- * THIS plugin's catalogs; the host provides them via __PluginI18nContext.
- */
-export declare function useTranslation(): PluginTranslation;
-/** Reactive: the currently-active conversation's state. */
-export declare function useActiveConversation(): ConversationState;
-/** Reactive: the active conversation's messages. */
-export declare function useConversationMessages(): ConversationMessage[];
-/**
- * Reactive: the image currently bound as the edit target via
- * `ui.setEditImageAttachment` (or null). Single source of truth for the
- * "selected for edit" highlight — clears automatically when the host drops the
- * attachment (send, capsule close, or session switch).
- */
-export declare function useEditImageAttachment(): PluginImageRef | null;
+ * Implementation is split by domain under `src/*.ts`; this barrel re-exports
+ * the stable package API. Prefer importing from `@vetta-org/plugin-sdk` rather
+ * than deep paths.
+ */
+export type { ConversationScenario } from "./scenario.js";
+export type { PluginPermission } from "./permissions.js";
+export type { Disposable } from "./disposable.js";
+export type { PluginMcpServerConfig, PluginAgentManifest } from "./manifest.js";
+export type { ConversationState, ConversationMessage, ConversationEvent, PluginConversationApi, } from "./conversation.js";
+export type { PluginGlobalSlotContribution, PluginAudioMetadata, PluginPreviewUrlOptions, PluginPreviewFile, PluginFilePreviewProps, PluginFilePreviewContribution, PluginActivityTabContribution, PluginCaptureRegion, PluginOpenActivityTabOptions, PluginPromptDecoration, PluginInputActionContribution, CardDescriptor, PluginPendingToolCall, PluginCardProps, PluginCardRendererContribution, PluginToolCallSlotToolCall, PluginToolCallSlotProps, PluginToolCallSlotContribution, PluginTurnCardContribution, PluginNotifyOptions, PluginUiApi, } from "./ui.js";
+export type { PluginJsonSchema, PluginAgentToolApi, PluginAgentToolRegistration, PluginSystemPromptBlock, PluginDynamicSystemPromptOperation, PluginSystemPromptMessage, PluginSystemPromptProviderContext, PluginSystemPromptBlockView, PluginAgentActions, PluginAgentHandlerContext, PluginAgentToolHandler, PluginSystemPromptProviderHandler, PluginSystemPromptProviderRegistration, PluginContinuationResult, PluginContinuationHandler, PluginContinuationRegistration, PluginAgentApi, } from "./agent.js";
+export type { PluginAppActionEffect, PluginAppActionExample, PluginAppActionHandlerContext, PluginAppActionHandler, PluginAppActionReadyHandler, PluginAppActionApprovalPresentation, PluginAppActionApproval, PluginAppActionRegistration, PluginAppActionsApi, } from "./app-actions.js";
+export { PluginAppActionError } from "./app-actions.js";
+export type { PluginOfficialGeneralSettings, PluginOfficialGeneralSettingsUpdate, PluginOfficialExperimentalSettings, PluginOfficialDownloadItem, PluginOfficialUpdaterState, PluginOfficialWebhookKind, PluginOfficialWebhookEndpoint, PluginOfficialWebhookProvider, PluginOfficialWebhookCreateInput, PluginOfficialWebhookUpdateInput, PluginOfficialWebhookMessage, PluginOfficialWebhookSendResult, PluginOfficialSkillInfo, PluginOfficialInstalledSkill, PluginOfficialShortcutBinding, PluginOfficialQuickPanelSettings, PluginOfficialImStatus, PluginOfficialImLog, PluginOfficialMcpServerSummary, PluginOfficialMcpServerDetail, PluginOfficialMcpUpsertData, PluginOfficialExecutionMode, PluginOfficialSelectedSkill, PluginOfficialBatchProjectCreateData, PluginOfficialBatchProjectUpdateData, PluginOfficialSchedulerTaskCreateData, PluginOfficialSchedulerTaskUpdateData, PluginOfficialModelSummary, PluginOfficialProviderSummary, PluginOfficialProviderDetail, PluginOfficialProviderUpsertData, PluginOfficialProjectEntry, PluginOfficialPluginSummary, PluginOfficialKnowledgeBase, PluginOfficialKnowledgeProcessingSettings, PluginOfficialApi, } from "./official.js";
+export type { PluginFsEntry, PluginFsFileRef, PluginFsBinaryReadResult, PluginFsStatResult, PluginFsReadResult, PluginFsApi, } from "./fs.js";
+export type { PluginCommandRunOptions, PluginCommandRunResult, PluginCommandApi, } from "./command.js";
+export type { PluginImageRef } from "./images.js";
+export type { PluginPromptAttachment } from "./prompt-attachment.js";
+export type { PluginNetworkApi, PluginNetworkBody, PluginNetworkRequest, PluginNetworkResponse, } from "./network.js";
+export type { PluginPutBlobInput, PluginStorageApi, PluginStoredBlob, PluginStoredBlobRef, } from "./storage.js";
+export type { PluginSettingsApi } from "./settings.js";
+export type { PluginLocaleCatalog, PluginLocales, PluginTranslate, PluginI18nApi, } from "./i18n.js";
+export { interpolatePluginText, resolveCatalogKey, resolvePluginText } from "./i18n.js";
+export type { PluginPermissionApi, AgentMode, PluginContext, PluginDefinition } from "./context.js";
+export { definePlugin } from "./context.js";
+export type { PluginHostBridge } from "./host-bridge.js";
+export { __setPluginHostBridge } from "./host-bridge.js";
+export type { ActivityTabContextValue } from "./activity-tab.js";
+export { __ActivityTabContext, useActivityTab } from "./activity-tab.js";
+export type { PluginI18nContextValue, PluginTranslation } from "./hooks.js";
+export { __PluginI18nContext, useTranslation, useActiveConversation, useConversationMessages, usePromptAttachment, } from "./hooks.js";
 //# sourceMappingURL=index.d.ts.map