@vetta-org/plugin-sdk 0.0.2 → 0.0.4

package/dist/scenario.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 对话场景 slug——决定一个工具 / 会话页插槽在哪些类型的会话里激活或可见。
+ *
+ * 本类型在 plugin-sdk 内本地定义（SDK 零依赖，不引入宿主包），与宿主
+ * `@vetta/coding-agent` 的 `ConversationScenario` 保持一一对应；任一侧增删场景时两边须同步，
+ * 否则宿主回传的 scenario 与此 union 不一致会触发编译错误（即为期望的漂移护栏）。
+ */
+export type ConversationScenario = "im-claw" | "conversation" | "project" | "batch" | "automation" | "kb-processing" | "cli";
+//# sourceMappingURL=scenario.d.ts.map

package/dist/scenario.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.d.ts","sourceRoot":"","sources":["../src/scenario.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC7B,SAAS,GACT,cAAc,GACd,SAAS,GACT,OAAO,GACP,YAAY,GACZ,eAAe,GACf,KAAK,CAAC","sourcesContent":["/**\n * 对话场景 slug——决定一个工具 / 会话页插槽在哪些类型的会话里激活或可见。\n *\n * 本类型在 plugin-sdk 内本地定义（SDK 零依赖，不引入宿主包），与宿主\n * `@vetta/coding-agent` 的 `ConversationScenario` 保持一一对应；任一侧增删场景时两边须同步，\n * 否则宿主回传的 scenario 与此 union 不一致会触发编译错误（即为期望的漂移护栏）。\n */\nexport type ConversationScenario =\n\t| \"im-claw\" // Claw IM 对话\n\t| \"conversation\" // 普通对话\n\t| \"project\" // 普通项目中对话\n\t| \"batch\" // 批量任务对话\n\t| \"automation\" // 自动化任务对话\n\t| \"kb-processing\" // 知识库加工对话\n\t| \"cli\"; // 裸 CLI / SDK 消费者\n"]}

package/dist/scenario.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scenario.js.map

package/dist/scenario.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.js","sourceRoot":"","sources":["../src/scenario.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * 对话场景 slug——决定一个工具 / 会话页插槽在哪些类型的会话里激活或可见。\n *\n * 本类型在 plugin-sdk 内本地定义（SDK 零依赖，不引入宿主包），与宿主\n * `@vetta/coding-agent` 的 `ConversationScenario` 保持一一对应；任一侧增删场景时两边须同步，\n * 否则宿主回传的 scenario 与此 union 不一致会触发编译错误（即为期望的漂移护栏）。\n */\nexport type ConversationScenario =\n\t| \"im-claw\" // Claw IM 对话\n\t| \"conversation\" // 普通对话\n\t| \"project\" // 普通项目中对话\n\t| \"batch\" // 批量任务对话\n\t| \"automation\" // 自动化任务对话\n\t| \"kb-processing\" // 知识库加工对话\n\t| \"cli\"; // 裸 CLI / SDK 消费者\n"]}

package/dist/settings.d.ts

@@ -0,0 +1,13 @@
+import type { Disposable } from "./disposable.js";
+/**
+ * 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;
+}
+//# sourceMappingURL=settings.d.ts.map

package/dist/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAC7C,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,UAAU,CAAC;CAC1E","sourcesContent":["import type { Disposable } from \"./disposable.js\";\n\n/**\n * Read-side access to this plugin's settings (the values configured against\n * the `contributes.settings` schema declared in plugin.json, namespaced by\n * plugin id). Writes go through the host's settings UI, not the plugin.\n */\nexport interface PluginSettingsApi {\n\tget<T = unknown>(key: string): T | undefined;\n\tgetAll(): Record<string, unknown>;\n\t/** Fired when any of this plugin's setting values change. */\n\tonChange(listener: (values: Record<string, unknown>) => void): Disposable;\n}\n"]}

package/dist/settings.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"","sourcesContent":["import type { Disposable } from \"./disposable.js\";\n\n/**\n * Read-side access to this plugin's settings (the values configured against\n * the `contributes.settings` schema declared in plugin.json, namespaced by\n * plugin id). Writes go through the host's settings UI, not the plugin.\n */\nexport interface PluginSettingsApi {\n\tget<T = unknown>(key: string): T | undefined;\n\tgetAll(): Record<string, unknown>;\n\t/** Fired when any of this plugin's setting values change. */\n\tonChange(listener: (values: Record<string, unknown>) => void): Disposable;\n}\n"]}

package/dist/ui.d.ts

@@ -0,0 +1,338 @@
+import type { ComponentType, ReactNode } from "react";
+import type { ConversationMessage } from "./conversation.js";
+import type { Disposable } from "./disposable.js";
+import type { PluginImageRef } from "./images.js";
+import type { ConversationScenario } from "./scenario.js";
+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";
+}
+/**
+ * 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[];
+}
+/**
+ * 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 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;
+}
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ComponentType, ReactNode } from \"react\";\nimport type { ConversationMessage } from \"./conversation.js\";\nimport type { Disposable } from \"./disposable.js\";\nimport type { PluginImageRef } from \"./images.js\";\nimport type { ConversationScenario } from \"./scenario.js\";\n\nexport interface PluginGlobalSlotContribution {\n\tid: string;\n\tcomponent: ComponentType;\n}\n\nexport interface PluginAudioMetadata {\n\t/** Embedded title; preview renderers should fall back to file.name. */\n\ttitle?: string;\n\tartist?: string;\n\t/** Embedded cover art as a Data URL when available. */\n\tcoverDataUrl?: string;\n}\n\nexport interface PluginPreviewUrlOptions {\n\t/** Optional media hint for ambiguous containers such as webm. */\n\tmediaKind?: \"audio\" | \"video\";\n}\n\n/**\n * The file handed to a file-preview plugin component. The host does NOT\n * pre-read or guess encoding — the plugin decides whether to read text or\n * bytes. `path` is also exposed for plugins that prefer native fetch.\n */\nexport interface PluginPreviewFile {\n\tpath: string | null;\n\tname: string;\n\textension: string;\n\tmime: string;\n\tsize: number;\n\t/** Read the file as a UTF-8 string. */\n\treadText(): Promise<string>;\n\t/** Read the raw file bytes. */\n\treadBytes(): Promise<ArrayBuffer>;\n\t/** A fetchable streaming URL for the file (Range-capable). */\n\tgetUrl(options?: PluginPreviewUrlOptions): string;\n\t/**\n\t * Subscribe to on-disk changes of this file. The listener fires (debounced\n\t * by the host) whenever the file's contents change, letting previews update\n\t * live. Returns a Disposable; call dispose() to stop watching. A no-op for\n\t * files without a real path (url-only sources).\n\t */\n\twatch(listener: () => void): Disposable;\n\t/**\n\t * Host-provided audio metadata for local media files. Returns null when the\n\t * host cannot provide metadata, e.g. url-only sources or unsupported files.\n\t */\n\tgetAudioMetadata?(): Promise<PluginAudioMetadata | null>;\n}\n\nexport interface PluginFilePreviewProps {\n\tfile: PluginPreviewFile;\n}\n\nexport interface PluginFilePreviewContribution {\n\t/** Lower-case extensions without the dot, e.g. [\"svg\"]. */\n\textensions: string[];\n\tcomponent: ComponentType<PluginFilePreviewProps>;\n}\n\n/**\n * An activity-panel tab contributed by a plugin. Registering only adds the\n * tab to the \"addable pool\" — it renders only after the user attaches it in\n * the activity panel (scoped by session cwd).\n */\nexport interface PluginActivityTabContribution {\n\tid: string;\n\tlabel: string;\n\t/** Tab icon as a React node (not an iconify class string). */\n\ticon?: ReactNode;\n\tcomponent: ComponentType;\n\t/**\n\t * 允许该标签卡出现的对话场景 slug 列表（镜像工具的 scope_use）。**fail-closed**：\n\t * 未声明/空数组 = 任何会话都不显示；声明后仅在列出的场景里出现（如\n\t * `[\"project\", \"conversation\"]`）。会话页插槽据此随对话类型显隐。\n\t */\n\tscope_use?: readonly ConversationScenario[];\n}\n\n/** Options for {@link PluginUiApi.openActivityTab}. */\nexport interface PluginOpenActivityTabOptions {\n\t/**\n\t * Desired panel width as it opens: a pixel number, or `\"max\"` for the widest\n\t * the current window allows. The host clamps to its min/max bounds. Omit to\n\t * keep the user's current width.\n\t */\n\twidth?: number | \"max\";\n}\n\n/**\n * Decoration a plugin contributes to the next outgoing prompt while its input\n * action is active. `metadata` is shallow-merged into the prompt request's\n * `metadata` bag, which the agent turn can read (e.g. `{ imageMode: true }`).\n */\nexport interface PluginPromptDecoration {\n\tmetadata?: Record<string, unknown>;\n}\n\n/**\n * An action button shown in a row beneath the AI input bar. Rendered as a\n * toggle: clicking activates, clicking again deactivates. While active, the\n * host calls `decoratePrompt()` before each send and merges the returned\n * metadata into the outgoing prompt request. The plugin owns any side state\n * (it is the same Module Federation instance as its other slots).\n */\nexport interface PluginInputActionContribution {\n\tid: string;\n\tlabel: string;\n\t/** Button icon as a React node (not an iconify class string). */\n\ticon?: ReactNode;\n\t/** Whether the action begins in the active state. Defaults to false. */\n\tdefaultActive?: boolean;\n\t/**\n\t * 该输入动作所依赖的 agent 工具名。设置后，仅当该工具在当前会话处于激活（按工具的\n\t * scope_use 解析）时才显示这个 badge——避免在工具被场景屏蔽（如批量任务）时仍显示一个\n\t * 点了也无效的开关。不设则始终显示。例如「图像生成」设为 \"generate_image\"。\n\t */\n\trequiresActiveTool?: string;\n\t/**\n\t * 允许该 toggle 出现的对话场景 slug 列表（镜像工具的 scope_use）。**fail-closed**：\n\t * 未声明/空数组 = 任何会话都不显示；声明后仅在列出的场景里出现。与 `requiresActiveTool`\n\t * 取「与」：两者都满足才显示。\n\t */\n\tscope_use?: readonly ConversationScenario[];\n\t/**\n\t * When true, this plugin's agent contributions (tools / skills / MCP /\n\t * systemPrompt) and Activity Tabs are hard-isolated: inactive until this\n\t * toggle is on (ADR-0041, knowledgeMode-style). Default false.\n\t */\n\thardIsolation?: boolean;\n\t/**\n\t * Fired when the user toggles the action; `active` is the new state. Return\n\t * `false` when `active` is true to VETO the activation (e.g. the plugin needs\n\t * configuration first) — the toggle stays off. Deactivation can't be vetoed.\n\t */\n\tonToggle?(active: boolean): boolean | void;\n\t/**\n\t * Called by the host before sending while the action is active. The\n\t * returned metadata is merged into the outgoing prompt request.\n\t */\n\tdecoratePrompt?(): PluginPromptDecoration | void;\n}\n\n/**\n * A declarative, serializable descriptor for one card rendered beneath a\n * message. `type` selects a registered card renderer; `key` drives cross-turn\n * dedup (same key across turns = one logical card, shown only under its latest\n * anchor); `payload` carries STABLE REFERENCES (e.g. image ids), not a content\n * snapshot — the renderer resolves live state from it. `title`/`icon` label the\n * card's tab (override the renderer's registration defaults). Rides a tool\n * result's out-of-band `details.cards`; crosses the agent→host boundary, so\n * `icon` is an icon-symbol string, not a node.\n */\nexport interface CardDescriptor {\n\ttype: string;\n\tkey?: string;\n\tpayload?: unknown;\n\ttitle?: string;\n\ticon?: string;\n}\n\n/** A pending (in-flight) tool call handed to a renderer's `pendingFor`. */\nexport interface PluginPendingToolCall {\n\ttoolName: string;\n\targs: Record<string, unknown>;\n}\n\n/**\n * Props for a card renderer. `descriptor` is the card's data; `pending` is true\n * while it was synthesized from an in-flight tool (render a skeleton); `message`\n * is the anchoring conversation message.\n */\nexport interface PluginCardProps {\n\tdescriptor: CardDescriptor;\n\tpending: boolean;\n\tmessage: ConversationMessage;\n}\n\n/**\n * A card renderer registered by a plugin, keyed by `type`. A descriptor whose\n * `type` matches is rendered by `component`. `title`/`icon` are the default tab\n * label/icon (a descriptor may override `title`). `pendingFor`, given an\n * in-flight tool call, returns a provisional descriptor so a skeleton card\n * appears (and claims a tab) before the tool's result lands — or null when this\n * renderer doesn't handle that tool. The `type` must be globally unique across\n * plugins (convention: prefix with the plugin id, e.g. \"image-gen:preview\").\n */\nexport interface PluginCardRendererContribution {\n\ttype: string;\n\tcomponent: ComponentType<PluginCardProps>;\n\ttitle?: string;\n\t/** Default tab icon as a React node (not an iconify class string). */\n\ticon?: ReactNode;\n\tpendingFor?: (toolCall: PluginPendingToolCall) => CardDescriptor | null;\n}\n\n/** A tool call handed to a tool-call slot renderer. */\nexport interface PluginToolCallSlotToolCall {\n\ttoolCallId: string;\n\ttoolName: string;\n\targs: Record<string, unknown>;\n\tstatus: \"pending\" | \"success\" | \"error\";\n\tresult?: string;\n\tisError?: boolean;\n}\n\nexport interface PluginToolCallSlotProps {\n\ttoolCall: PluginToolCallSlotToolCall;\n}\n\n/**\n * A component that **replaces the host's default inline transcript rendering**\n * for a specific tool (matched by `toolName`; first registered renderer wins).\n * This is how a plugin renders rich UI for its OWN agent tool's output — plugin\n * tools cannot emit `details.cards`, so the message card system (registerCardRenderer)\n * does not serve them; the tool-call slot does.\n */\nexport interface PluginToolCallSlotContribution {\n\tid: string;\n\ttoolName: string;\n\tcomponent: ComponentType<PluginToolCallSlotProps>;\n}\n\n/**\n * A card rendered at the bottom of the message list for the LATEST turn — NOT\n * bound to a tool call. The host mounts `component` in the footer slot and\n * re-mounts it each session/turn; the plugin owns visibility entirely (it reads\n * live state via SDK hooks — `useActiveConversation`, `useConversationMessages`,\n * `ctx.conversation.on(\"turn-end\")` — and returns `null` to render nothing,\n * e.g. git renders only inside a repo that has changes). `scope_use` gates which\n * conversation scenarios it may appear in (**fail-closed**, mirrors the other\n * slots). `id` must be unique within the plugin.\n */\nexport interface PluginTurnCardContribution {\n\tid: string;\n\tcomponent: ComponentType;\n\t/**\n\t * 允许该 turn 卡出现的对话场景 slug 列表（镜像其它插槽的 scope_use）。**fail-closed**：\n\t * 未声明/空数组 = 任何会话都不显示；声明后仅在列出的场景里出现（如 `[\"project\"]`）。\n\t */\n\tscope_use?: readonly ConversationScenario[];\n}\n\n/**\n * Options for {@link PluginUiApi.notify}. Surfaces a host toast so users can\n * see plugin failures without opening DevTools.\n */\nexport interface PluginNotifyOptions {\n\t/** Toast body. Required even when `error` is set (user-facing summary). */\n\tmessage: string;\n\t/** Defaults to plugin display name when omitted. */\n\ttitle?: string;\n\t/** Defaults to `\"info\"`; when `error` is set and variant omitted, host uses `\"error\"`. */\n\tvariant?: \"info\" | \"success\" | \"warning\" | \"error\";\n\t/**\n\t * Optional failure cause. Host formats message + stack and adds a\n\t * \"复制堆栈\" action so the user can paste it into bug reports / chat.\n\t */\n\terror?: unknown;\n\t/**\n\t * Auto-dismiss delay in ms. `0` keeps the toast until dismissed.\n\t * Defaults: sticky (`0`) when `error` is present, otherwise host default (~4s).\n\t */\n\tdurationMs?: number;\n}\n\nexport interface PluginUiApi {\n\tregisterGlobalSlot(contribution: PluginGlobalSlotContribution): Disposable;\n\t/**\n\t * Register a preview component keyed by file extension. The host dispatches\n\t * registered extensions before its built-in fallback renderers; first\n\t * registrant wins on conflict.\n\t */\n\tregisterFilePreview(contribution: PluginFilePreviewContribution): Disposable;\n\t/**\n\t * Register an activity-panel tab into the addable pool. The user attaches\n\t * it manually via the panel's \"+\" picker; attach records are keyed by the\n\t * session cwd.\n\t */\n\tregisterActivityTab(contribution: PluginActivityTabContribution): Disposable;\n\t/**\n\t * Register a toggle action shown beneath the AI input bar. While active,\n\t * its `decoratePrompt()` annotates the next outgoing prompt.\n\t */\n\tregisterInputAction(contribution: PluginInputActionContribution): Disposable;\n\t/**\n\t * Register a card renderer keyed by `type`. Cards rendered beneath a message\n\t * come from tool results' out-of-band `details.cards` (or `pendingFor` for\n\t * in-flight tools); the host resolves each card's `type` to a registered\n\t * renderer. Multiple cards under one message are shown as a tab-switcher\n\t * (\"收纳\") or a flat list.\n\t */\n\tregisterCardRenderer(contribution: PluginCardRendererContribution): Disposable;\n\t/**\n\t * Register a renderer that replaces the host's default inline transcript UI\n\t * for a tool call (matched by `toolName`). The complement to card renderers:\n\t * use it to render UI for a plugin's own agent tool output.\n\t */\n\tregisterToolCallSlot(contribution: PluginToolCallSlotContribution): Disposable;\n\t/**\n\t * Register a card rendered at the bottom of the message list for the latest\n\t * turn — NOT bound to a tool call. The host mounts the component in the\n\t * footer slot; the plugin owns visibility (return `null` to render nothing,\n\t * e.g. git renders only in a repo with changes). Gated by `scope_use`\n\t * (fail-closed). Needs the `ui.slot.turn-card` permission.\n\t */\n\tregisterTurnCard(contribution: PluginTurnCardContribution): Disposable;\n\t/**\n\t * Programmatically attach (if needed) and activate one of this plugin's\n\t * own activity tabs in the current conversation's activity panel. `tabId`\n\t * is the contribution id passed to registerActivityTab. Any payload (e.g.\n\t * which image to edit) is passed via the plugin's own in-memory state.\n\t *\n\t * Pass `options.width` to size the panel as it opens — a pixel number, or\n\t * `\"max\"` to expand it to the widest the current window allows (the host\n\t * still clamps to its min/max and auto-hides the sidebar when needed). Omit\n\t * to leave the user's current width untouched.\n\t */\n\topenActivityTab(tabId: string, options?: PluginOpenActivityTabOptions): void;\n\t/**\n\t * Bind (or clear, with `null`) an image as the \"edit target\" for the next\n\t * outgoing prompt. The host renders it as a thumbnail capsule in the AI input\n\t * bar's top capsule strip and, at send time, injects `metadata.editImageId`\n\t * (the ref's id) so this turn edits that image. One-shot: cleared after the\n\t * prompt is sent (or when the user closes the capsule). Only the image\n\t * reference (id/url) crosses over — bytes stay out-of-band.\n\t */\n\tsetEditImageAttachment(ref: PluginImageRef | null): void;\n\t/**\n\t * Open the host's global full-screen image previewer for the given image.\n\t * Only the image reference (id/url) crosses over — bytes stay out-of-band.\n\t *\n\t * Pass `group` (e.g. all images of the message) to open as an image group:\n\t * the previewer shows a thumbnail strip + arrows and starts at `ref`.\n\t */\n\tpreviewImage(ref: PluginImageRef, group?: PluginImageRef[]): void;\n\t/**\n\t * Open the app settings, scrolled to and highlighting THIS plugin's own\n\t * settings section (e.g. so the user can fill in a required API key/model).\n\t * The host owns the navigation; the plugin only asks to jump there.\n\t */\n\topenPluginSettings(): void;\n\t/**\n\t * Show a global toast in the host UI (bottom-right). No permission required.\n\t * Prefer this over swallowing errors into opaque UI copy: pass `error` so\n\t * the host attaches a one-click \"copy stack\" action for the user.\n\t *\n\t * Capture `ctx.ui.notify` in `activate` if React components need it\n\t * (components do not receive `ctx`).\n\t */\n\tnotify(options: PluginNotifyOptions): void;\n}\n"]}

package/dist/ui.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ui.js.map

package/dist/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"","sourcesContent":["import type { ComponentType, ReactNode } from \"react\";\nimport type { ConversationMessage } from \"./conversation.js\";\nimport type { Disposable } from \"./disposable.js\";\nimport type { PluginImageRef } from \"./images.js\";\nimport type { ConversationScenario } from \"./scenario.js\";\n\nexport interface PluginGlobalSlotContribution {\n\tid: string;\n\tcomponent: ComponentType;\n}\n\nexport interface PluginAudioMetadata {\n\t/** Embedded title; preview renderers should fall back to file.name. */\n\ttitle?: string;\n\tartist?: string;\n\t/** Embedded cover art as a Data URL when available. */\n\tcoverDataUrl?: string;\n}\n\nexport interface PluginPreviewUrlOptions {\n\t/** Optional media hint for ambiguous containers such as webm. */\n\tmediaKind?: \"audio\" | \"video\";\n}\n\n/**\n * The file handed to a file-preview plugin component. The host does NOT\n * pre-read or guess encoding — the plugin decides whether to read text or\n * bytes. `path` is also exposed for plugins that prefer native fetch.\n */\nexport interface PluginPreviewFile {\n\tpath: string | null;\n\tname: string;\n\textension: string;\n\tmime: string;\n\tsize: number;\n\t/** Read the file as a UTF-8 string. */\n\treadText(): Promise<string>;\n\t/** Read the raw file bytes. */\n\treadBytes(): Promise<ArrayBuffer>;\n\t/** A fetchable streaming URL for the file (Range-capable). */\n\tgetUrl(options?: PluginPreviewUrlOptions): string;\n\t/**\n\t * Subscribe to on-disk changes of this file. The listener fires (debounced\n\t * by the host) whenever the file's contents change, letting previews update\n\t * live. Returns a Disposable; call dispose() to stop watching. A no-op for\n\t * files without a real path (url-only sources).\n\t */\n\twatch(listener: () => void): Disposable;\n\t/**\n\t * Host-provided audio metadata for local media files. Returns null when the\n\t * host cannot provide metadata, e.g. url-only sources or unsupported files.\n\t */\n\tgetAudioMetadata?(): Promise<PluginAudioMetadata | null>;\n}\n\nexport interface PluginFilePreviewProps {\n\tfile: PluginPreviewFile;\n}\n\nexport interface PluginFilePreviewContribution {\n\t/** Lower-case extensions without the dot, e.g. [\"svg\"]. */\n\textensions: string[];\n\tcomponent: ComponentType<PluginFilePreviewProps>;\n}\n\n/**\n * An activity-panel tab contributed by a plugin. Registering only adds the\n * tab to the \"addable pool\" — it renders only after the user attaches it in\n * the activity panel (scoped by session cwd).\n */\nexport interface PluginActivityTabContribution {\n\tid: string;\n\tlabel: string;\n\t/** Tab icon as a React node (not an iconify class string). */\n\ticon?: ReactNode;\n\tcomponent: ComponentType;\n\t/**\n\t * 允许该标签卡出现的对话场景 slug 列表（镜像工具的 scope_use）。**fail-closed**：\n\t * 未声明/空数组 = 任何会话都不显示；声明后仅在列出的场景里出现（如\n\t * `[\"project\", \"conversation\"]`）。会话页插槽据此随对话类型显隐。\n\t */\n\tscope_use?: readonly ConversationScenario[];\n}\n\n/** Options for {@link PluginUiApi.openActivityTab}. */\nexport interface PluginOpenActivityTabOptions {\n\t/**\n\t * Desired panel width as it opens: a pixel number, or `\"max\"` for the widest\n\t * the current window allows. The host clamps to its min/max bounds. Omit to\n\t * keep the user's current width.\n\t */\n\twidth?: number | \"max\";\n}\n\n/**\n * Decoration a plugin contributes to the next outgoing prompt while its input\n * action is active. `metadata` is shallow-merged into the prompt request's\n * `metadata` bag, which the agent turn can read (e.g. `{ imageMode: true }`).\n */\nexport interface PluginPromptDecoration {\n\tmetadata?: Record<string, unknown>;\n}\n\n/**\n * An action button shown in a row beneath the AI input bar. Rendered as a\n * toggle: clicking activates, clicking again deactivates. While active, the\n * host calls `decoratePrompt()` before each send and merges the returned\n * metadata into the outgoing prompt request. The plugin owns any side state\n * (it is the same Module Federation instance as its other slots).\n */\nexport interface PluginInputActionContribution {\n\tid: string;\n\tlabel: string;\n\t/** Button icon as a React node (not an iconify class string). */\n\ticon?: ReactNode;\n\t/** Whether the action begins in the active state. Defaults to false. */\n\tdefaultActive?: boolean;\n\t/**\n\t * 该输入动作所依赖的 agent 工具名。设置后，仅当该工具在当前会话处于激活（按工具的\n\t * scope_use 解析）时才显示这个 badge——避免在工具被场景屏蔽（如批量任务）时仍显示一个\n\t * 点了也无效的开关。不设则始终显示。例如「图像生成」设为 \"generate_image\"。\n\t */\n\trequiresActiveTool?: string;\n\t/**\n\t * 允许该 toggle 出现的对话场景 slug 列表（镜像工具的 scope_use）。**fail-closed**：\n\t * 未声明/空数组 = 任何会话都不显示；声明后仅在列出的场景里出现。与 `requiresActiveTool`\n\t * 取「与」：两者都满足才显示。\n\t */\n\tscope_use?: readonly ConversationScenario[];\n\t/**\n\t * When true, this plugin's agent contributions (tools / skills / MCP /\n\t * systemPrompt) and Activity Tabs are hard-isolated: inactive until this\n\t * toggle is on (ADR-0041, knowledgeMode-style). Default false.\n\t */\n\thardIsolation?: boolean;\n\t/**\n\t * Fired when the user toggles the action; `active` is the new state. Return\n\t * `false` when `active` is true to VETO the activation (e.g. the plugin needs\n\t * configuration first) — the toggle stays off. Deactivation can't be vetoed.\n\t */\n\tonToggle?(active: boolean): boolean | void;\n\t/**\n\t * Called by the host before sending while the action is active. The\n\t * returned metadata is merged into the outgoing prompt request.\n\t */\n\tdecoratePrompt?(): PluginPromptDecoration | void;\n}\n\n/**\n * A declarative, serializable descriptor for one card rendered beneath a\n * message. `type` selects a registered card renderer; `key` drives cross-turn\n * dedup (same key across turns = one logical card, shown only under its latest\n * anchor); `payload` carries STABLE REFERENCES (e.g. image ids), not a content\n * snapshot — the renderer resolves live state from it. `title`/`icon` label the\n * card's tab (override the renderer's registration defaults). Rides a tool\n * result's out-of-band `details.cards`; crosses the agent→host boundary, so\n * `icon` is an icon-symbol string, not a node.\n */\nexport interface CardDescriptor {\n\ttype: string;\n\tkey?: string;\n\tpayload?: unknown;\n\ttitle?: string;\n\ticon?: string;\n}\n\n/** A pending (in-flight) tool call handed to a renderer's `pendingFor`. */\nexport interface PluginPendingToolCall {\n\ttoolName: string;\n\targs: Record<string, unknown>;\n}\n\n/**\n * Props for a card renderer. `descriptor` is the card's data; `pending` is true\n * while it was synthesized from an in-flight tool (render a skeleton); `message`\n * is the anchoring conversation message.\n */\nexport interface PluginCardProps {\n\tdescriptor: CardDescriptor;\n\tpending: boolean;\n\tmessage: ConversationMessage;\n}\n\n/**\n * A card renderer registered by a plugin, keyed by `type`. A descriptor whose\n * `type` matches is rendered by `component`. `title`/`icon` are the default tab\n * label/icon (a descriptor may override `title`). `pendingFor`, given an\n * in-flight tool call, returns a provisional descriptor so a skeleton card\n * appears (and claims a tab) before the tool's result lands — or null when this\n * renderer doesn't handle that tool. The `type` must be globally unique across\n * plugins (convention: prefix with the plugin id, e.g. \"image-gen:preview\").\n */\nexport interface PluginCardRendererContribution {\n\ttype: string;\n\tcomponent: ComponentType<PluginCardProps>;\n\ttitle?: string;\n\t/** Default tab icon as a React node (not an iconify class string). */\n\ticon?: ReactNode;\n\tpendingFor?: (toolCall: PluginPendingToolCall) => CardDescriptor | null;\n}\n\n/** A tool call handed to a tool-call slot renderer. */\nexport interface PluginToolCallSlotToolCall {\n\ttoolCallId: string;\n\ttoolName: string;\n\targs: Record<string, unknown>;\n\tstatus: \"pending\" | \"success\" | \"error\";\n\tresult?: string;\n\tisError?: boolean;\n}\n\nexport interface PluginToolCallSlotProps {\n\ttoolCall: PluginToolCallSlotToolCall;\n}\n\n/**\n * A component that **replaces the host's default inline transcript rendering**\n * for a specific tool (matched by `toolName`; first registered renderer wins).\n * This is how a plugin renders rich UI for its OWN agent tool's output — plugin\n * tools cannot emit `details.cards`, so the message card system (registerCardRenderer)\n * does not serve them; the tool-call slot does.\n */\nexport interface PluginToolCallSlotContribution {\n\tid: string;\n\ttoolName: string;\n\tcomponent: ComponentType<PluginToolCallSlotProps>;\n}\n\n/**\n * A card rendered at the bottom of the message list for the LATEST turn — NOT\n * bound to a tool call. The host mounts `component` in the footer slot and\n * re-mounts it each session/turn; the plugin owns visibility entirely (it reads\n * live state via SDK hooks — `useActiveConversation`, `useConversationMessages`,\n * `ctx.conversation.on(\"turn-end\")` — and returns `null` to render nothing,\n * e.g. git renders only inside a repo that has changes). `scope_use` gates which\n * conversation scenarios it may appear in (**fail-closed**, mirrors the other\n * slots). `id` must be unique within the plugin.\n */\nexport interface PluginTurnCardContribution {\n\tid: string;\n\tcomponent: ComponentType;\n\t/**\n\t * 允许该 turn 卡出现的对话场景 slug 列表（镜像其它插槽的 scope_use）。**fail-closed**：\n\t * 未声明/空数组 = 任何会话都不显示；声明后仅在列出的场景里出现（如 `[\"project\"]`）。\n\t */\n\tscope_use?: readonly ConversationScenario[];\n}\n\n/**\n * Options for {@link PluginUiApi.notify}. Surfaces a host toast so users can\n * see plugin failures without opening DevTools.\n */\nexport interface PluginNotifyOptions {\n\t/** Toast body. Required even when `error` is set (user-facing summary). */\n\tmessage: string;\n\t/** Defaults to plugin display name when omitted. */\n\ttitle?: string;\n\t/** Defaults to `\"info\"`; when `error` is set and variant omitted, host uses `\"error\"`. */\n\tvariant?: \"info\" | \"success\" | \"warning\" | \"error\";\n\t/**\n\t * Optional failure cause. Host formats message + stack and adds a\n\t * \"复制堆栈\" action so the user can paste it into bug reports / chat.\n\t */\n\terror?: unknown;\n\t/**\n\t * Auto-dismiss delay in ms. `0` keeps the toast until dismissed.\n\t * Defaults: sticky (`0`) when `error` is present, otherwise host default (~4s).\n\t */\n\tdurationMs?: number;\n}\n\nexport interface PluginUiApi {\n\tregisterGlobalSlot(contribution: PluginGlobalSlotContribution): Disposable;\n\t/**\n\t * Register a preview component keyed by file extension. The host dispatches\n\t * registered extensions before its built-in fallback renderers; first\n\t * registrant wins on conflict.\n\t */\n\tregisterFilePreview(contribution: PluginFilePreviewContribution): Disposable;\n\t/**\n\t * Register an activity-panel tab into the addable pool. The user attaches\n\t * it manually via the panel's \"+\" picker; attach records are keyed by the\n\t * session cwd.\n\t */\n\tregisterActivityTab(contribution: PluginActivityTabContribution): Disposable;\n\t/**\n\t * Register a toggle action shown beneath the AI input bar. While active,\n\t * its `decoratePrompt()` annotates the next outgoing prompt.\n\t */\n\tregisterInputAction(contribution: PluginInputActionContribution): Disposable;\n\t/**\n\t * Register a card renderer keyed by `type`. Cards rendered beneath a message\n\t * come from tool results' out-of-band `details.cards` (or `pendingFor` for\n\t * in-flight tools); the host resolves each card's `type` to a registered\n\t * renderer. Multiple cards under one message are shown as a tab-switcher\n\t * (\"收纳\") or a flat list.\n\t */\n\tregisterCardRenderer(contribution: PluginCardRendererContribution): Disposable;\n\t/**\n\t * Register a renderer that replaces the host's default inline transcript UI\n\t * for a tool call (matched by `toolName`). The complement to card renderers:\n\t * use it to render UI for a plugin's own agent tool output.\n\t */\n\tregisterToolCallSlot(contribution: PluginToolCallSlotContribution): Disposable;\n\t/**\n\t * Register a card rendered at the bottom of the message list for the latest\n\t * turn — NOT bound to a tool call. The host mounts the component in the\n\t * footer slot; the plugin owns visibility (return `null` to render nothing,\n\t * e.g. git renders only in a repo with changes). Gated by `scope_use`\n\t * (fail-closed). Needs the `ui.slot.turn-card` permission.\n\t */\n\tregisterTurnCard(contribution: PluginTurnCardContribution): Disposable;\n\t/**\n\t * Programmatically attach (if needed) and activate one of this plugin's\n\t * own activity tabs in the current conversation's activity panel. `tabId`\n\t * is the contribution id passed to registerActivityTab. Any payload (e.g.\n\t * which image to edit) is passed via the plugin's own in-memory state.\n\t *\n\t * Pass `options.width` to size the panel as it opens — a pixel number, or\n\t * `\"max\"` to expand it to the widest the current window allows (the host\n\t * still clamps to its min/max and auto-hides the sidebar when needed). Omit\n\t * to leave the user's current width untouched.\n\t */\n\topenActivityTab(tabId: string, options?: PluginOpenActivityTabOptions): void;\n\t/**\n\t * Bind (or clear, with `null`) an image as the \"edit target\" for the next\n\t * outgoing prompt. The host renders it as a thumbnail capsule in the AI input\n\t * bar's top capsule strip and, at send time, injects `metadata.editImageId`\n\t * (the ref's id) so this turn edits that image. One-shot: cleared after the\n\t * prompt is sent (or when the user closes the capsule). Only the image\n\t * reference (id/url) crosses over — bytes stay out-of-band.\n\t */\n\tsetEditImageAttachment(ref: PluginImageRef | null): void;\n\t/**\n\t * Open the host's global full-screen image previewer for the given image.\n\t * Only the image reference (id/url) crosses over — bytes stay out-of-band.\n\t *\n\t * Pass `group` (e.g. all images of the message) to open as an image group:\n\t * the previewer shows a thumbnail strip + arrows and starts at `ref`.\n\t */\n\tpreviewImage(ref: PluginImageRef, group?: PluginImageRef[]): void;\n\t/**\n\t * Open the app settings, scrolled to and highlighting THIS plugin's own\n\t * settings section (e.g. so the user can fill in a required API key/model).\n\t * The host owns the navigation; the plugin only asks to jump there.\n\t */\n\topenPluginSettings(): void;\n\t/**\n\t * Show a global toast in the host UI (bottom-right). No permission required.\n\t * Prefer this over swallowing errors into opaque UI copy: pass `error` so\n\t * the host attaches a one-click \"copy stack\" action for the user.\n\t *\n\t * Capture `ctx.ui.notify` in `activate` if React components need it\n\t * (components do not receive `ctx`).\n\t */\n\tnotify(options: PluginNotifyOptions): void;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vetta-org/plugin-sdk",
-	"version": "0.0.2",
+	"version": "0.0.4",
 	"type": "module",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",