@vetta-org/plugin-sdk 0.0.3 → 0.1.0

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 { PluginPromptAttachment } from \"./prompt-attachment.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\t/**\n\t * 注册后是否默认在标签栏里（缺省 `true`）。声明 `false` 表示「出现条件由我\n\t * 自己决定」——注册只是入池，之后由 {@link PluginUiApi.setActivityTabVisible}\n\t * 或 {@link PluginUiApi.openActivityTab} 决定何时上栏（如 git 只在仓库目录、\n\t * 工作台跟随输入栏 toggle）。无论哪种，用户仍可用减号手动隐藏。\n\t */\n\tinitiallyVisible?: boolean;\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\nexport interface PluginCaptureRegion {\n\tx: number;\n\ty: number;\n\twidth: number;\n\theight: number;\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 and\n * `instructions` are appended as hidden, model-visible guidance.\n */\nexport interface PluginPromptDecoration {\n\tmetadata?: Record<string, unknown>;\n\t/** Hidden plugin-owned instructions appended to the next agent turn. */\n\tinstructions?: string[];\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 * 把本插件的某个活动面板标签卡在当前会话里上栏 / 下栏，**不激活也不展开\n\t * 面板**——`openActivityTab` 是「用户此刻要看它」，这个是「它现在该不该在\n\t * 栏里」。配合 `initiallyVisible: false` 使用，插件即可完全掌握自己标签卡的\n\t * 出现条件（如 git 只在仓库目录里上栏、工作台跟随输入栏 toggle）。\n\t *\n\t * 上栏记录按会话 cwd 持久化（ADR-0026），所以只需在条件变化时调用一次；\n\t * 用户随后用减号手动隐藏的结果不会被重复调用覆盖。当前没有活动会话时为\n\t * no-op（无处记录），插件应在会话就绪后重新判定。\n\t */\n\tsetActivityTabVisible(tabId: string, visible: boolean): void;\n\t/**\n\t * Bind or clear plugin-owned one-shot context for the next outgoing prompt.\n\t * The host renders its label/icon, merges metadata and hidden instructions,\n\t * then clears it after send or when the user closes the capsule.\n\t */\n\tsetPromptAttachment(attachment: PluginPromptAttachment | 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 * Capture a rectangle in the current Vetta window and open the host save\n\t * dialog. Coordinates use renderer DIP values such as getBoundingClientRect().\n\t * Requires `ui.slot.activity-tab`.\n\t */\n\tcaptureRegion(rect: PluginCaptureRegion, defaultFileName: string): Promise<string | null>;\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.3",
+	"version": "0.1.0",
 	"type": "module",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",