@vetta-org/plugin-sdk 0.1.1 → 0.3.0

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IAClC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,OAAO,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACvD,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;CAC5D","sourcesContent":["export interface PluginStoredBlobRef {\n\tid: string;\n\turl: string;\n\tmimeType: string;\n}\n\nexport interface PluginStoredBlob {\n\tdata: string;\n\tmimeType: string;\n}\n\nexport interface PluginPutBlobInput {\n\tid?: string;\n\tdata: string;\n\tmimeType: string;\n}\n\n/**\n * Private persistent storage scoped to the current plugin.\n *\n * JSON keys and file paths are relative to the plugin namespace. Blob bytes are\n * base64 encoded at the bridge boundary and exposed through a host media URL.\n */\nexport interface PluginStorageApi {\n\treadJson<T>(key: string): Promise<T | null>;\n\twriteJson(key: string, value: unknown): Promise<void>;\n\tlist(prefix?: string): Promise<string[]>;\n\treadFile(path: string): Promise<string | null>;\n\twriteFile(path: string, data: string): Promise<void>;\n\tputBlob(input: PluginPutBlobInput): Promise<PluginStoredBlobRef>;\n\treadBlob(id: string): Promise<PluginStoredBlob | null>;\n\tgetBlobRef(id: string): Promise<PluginStoredBlobRef | null>;\n}\n"]}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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","sourcesContent":["export interface PluginStoredBlobRef {\n\tid: string;\n\turl: string;\n\tmimeType: string;\n}\n\nexport interface PluginStoredBlob {\n\tdata: string;\n\tmimeType: string;\n}\n\nexport interface PluginPutBlobInput {\n\tid?: string;\n\tdata: string;\n\tmimeType: string;\n}\n\nexport interface PluginPutBlobFromFileInput {\n\tid?: string;\n\tfile: File;\n\tmimeType: string;\n}\n\nexport type PluginStorageEncoding = \"utf8\" | \"base64\";\n\nexport interface PluginStorageWrite {\n\tpath: string;\n\tdata: string;\n\tencoding: PluginStorageEncoding;\n}\n\nexport type PluginStorageChange = ({ type: \"write\" } & PluginStorageWrite) | { type: \"remove\"; path: string };\n\nexport interface PluginStorageCommitOptions {\n\texpectedRevision?: string;\n}\n\nexport interface PluginStorageCommitResult {\n\trevision: string;\n\tchangedPaths: string[];\n}\n\nexport interface PluginStorageSnapshot {\n\trevision: string;\n\tfiles: Record<string, string | null>;\n}\n\n/**\n * Private persistent storage scoped to the current plugin.\n *\n * Paths are relative to the plugin namespace and are never given an implicit\n * extension. Text and bytes use an explicit encoding at the bridge boundary;\n * JSON is a plugin-level serialization choice. `commit()` publishes all file\n * changes as one revision, and `readSnapshot()` reads several paths from the\n * same revision. Blob bytes remain a separate media resource API.\n */\nexport interface PluginStorageApi {\n\tlist(prefix?: string): Promise<string[]>;\n\treadFile(path: string, encoding: PluginStorageEncoding): Promise<string | null>;\n\twriteFile(path: string, data: string, encoding: PluginStorageEncoding): Promise<PluginStorageCommitResult>;\n\t/** Atomically publish multiple private-file writes/removals as one plugin-scoped revision. */\n\tcommit(\n\t\tchanges: readonly PluginStorageChange[],\n\t\toptions?: PluginStorageCommitOptions,\n\t): Promise<PluginStorageCommitResult>;\n\t/** Read several private files from one committed revision. */\n\treadSnapshot(paths: readonly string[], encoding: PluginStorageEncoding): Promise<PluginStorageSnapshot>;\n\tputBlob(input: PluginPutBlobInput): Promise<PluginStoredBlobRef>;\n\t/** Copy a user-selected or dropped filesystem file without carrying its bytes through the renderer. */\n\tputBlobFromFile(input: PluginPutBlobFromFileInput): Promise<PluginStoredBlobRef>;\n\treadBlob(id: string): Promise<PluginStoredBlob | null>;\n\tgetBlobRef(id: string): Promise<PluginStoredBlobRef | null>;\n\t/** Permanently delete one blob owned by this plugin namespace. */\n\tdeleteBlob(id: string): Promise<void>;\n}\n\n/** Optional JSON convenience helpers. The storage contract itself remains file/bytes based. */\nexport async function readJsonFile<T>(storage: PluginStorageApi, path: string): Promise<T | null> {\n\tconst data = await storage.readFile(path, \"utf8\");\n\treturn data === null ? null : (JSON.parse(data) as T);\n}\n\nexport function writeJsonFile(storage: PluginStorageApi, path: string, value: unknown): Promise<PluginStorageCommitResult> {\n\treturn storage.writeFile(path, JSON.stringify(value, null, 2), \"utf8\");\n}\n"]}

package/dist/storage.js

@@ -1,2 +1,9 @@
-export {};
+/** Optional JSON convenience helpers. The storage contract itself remains file/bytes based. */
+export async function readJsonFile(storage, path) {
+    const data = await storage.readFile(path, "utf8");
+    return data === null ? null : JSON.parse(data);
+}
+export function writeJsonFile(storage, path, value) {
+    return storage.writeFile(path, JSON.stringify(value, null, 2), "utf8");
+}
 //# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"","sourcesContent":["export interface PluginStoredBlobRef {\n\tid: string;\n\turl: string;\n\tmimeType: string;\n}\n\nexport interface PluginStoredBlob {\n\tdata: string;\n\tmimeType: string;\n}\n\nexport interface PluginPutBlobInput {\n\tid?: string;\n\tdata: string;\n\tmimeType: string;\n}\n\n/**\n * Private persistent storage scoped to the current plugin.\n *\n * JSON keys and file paths are relative to the plugin namespace. Blob bytes are\n * base64 encoded at the bridge boundary and exposed through a host media URL.\n */\nexport interface PluginStorageApi {\n\treadJson<T>(key: string): Promise<T | null>;\n\twriteJson(key: string, value: unknown): Promise<void>;\n\tlist(prefix?: string): Promise<string[]>;\n\treadFile(path: string): Promise<string | null>;\n\twriteFile(path: string, data: string): Promise<void>;\n\tputBlob(input: PluginPutBlobInput): Promise<PluginStoredBlobRef>;\n\treadBlob(id: string): Promise<PluginStoredBlob | null>;\n\tgetBlobRef(id: string): Promise<PluginStoredBlobRef | null>;\n}\n"]}
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AA4EA,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,OAAyB,EAAE,IAAY,EAAqB;IACjG,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAClD,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAO,CAAC;AAAA,CACtD;AAED,MAAM,UAAU,aAAa,CAAC,OAAyB,EAAE,IAAY,EAAE,KAAc,EAAsC;IAC1H,OAAO,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAAA,CACvE","sourcesContent":["export interface PluginStoredBlobRef {\n\tid: string;\n\turl: string;\n\tmimeType: string;\n}\n\nexport interface PluginStoredBlob {\n\tdata: string;\n\tmimeType: string;\n}\n\nexport interface PluginPutBlobInput {\n\tid?: string;\n\tdata: string;\n\tmimeType: string;\n}\n\nexport interface PluginPutBlobFromFileInput {\n\tid?: string;\n\tfile: File;\n\tmimeType: string;\n}\n\nexport type PluginStorageEncoding = \"utf8\" | \"base64\";\n\nexport interface PluginStorageWrite {\n\tpath: string;\n\tdata: string;\n\tencoding: PluginStorageEncoding;\n}\n\nexport type PluginStorageChange = ({ type: \"write\" } & PluginStorageWrite) | { type: \"remove\"; path: string };\n\nexport interface PluginStorageCommitOptions {\n\texpectedRevision?: string;\n}\n\nexport interface PluginStorageCommitResult {\n\trevision: string;\n\tchangedPaths: string[];\n}\n\nexport interface PluginStorageSnapshot {\n\trevision: string;\n\tfiles: Record<string, string | null>;\n}\n\n/**\n * Private persistent storage scoped to the current plugin.\n *\n * Paths are relative to the plugin namespace and are never given an implicit\n * extension. Text and bytes use an explicit encoding at the bridge boundary;\n * JSON is a plugin-level serialization choice. `commit()` publishes all file\n * changes as one revision, and `readSnapshot()` reads several paths from the\n * same revision. Blob bytes remain a separate media resource API.\n */\nexport interface PluginStorageApi {\n\tlist(prefix?: string): Promise<string[]>;\n\treadFile(path: string, encoding: PluginStorageEncoding): Promise<string | null>;\n\twriteFile(path: string, data: string, encoding: PluginStorageEncoding): Promise<PluginStorageCommitResult>;\n\t/** Atomically publish multiple private-file writes/removals as one plugin-scoped revision. */\n\tcommit(\n\t\tchanges: readonly PluginStorageChange[],\n\t\toptions?: PluginStorageCommitOptions,\n\t): Promise<PluginStorageCommitResult>;\n\t/** Read several private files from one committed revision. */\n\treadSnapshot(paths: readonly string[], encoding: PluginStorageEncoding): Promise<PluginStorageSnapshot>;\n\tputBlob(input: PluginPutBlobInput): Promise<PluginStoredBlobRef>;\n\t/** Copy a user-selected or dropped filesystem file without carrying its bytes through the renderer. */\n\tputBlobFromFile(input: PluginPutBlobFromFileInput): Promise<PluginStoredBlobRef>;\n\treadBlob(id: string): Promise<PluginStoredBlob | null>;\n\tgetBlobRef(id: string): Promise<PluginStoredBlobRef | null>;\n\t/** Permanently delete one blob owned by this plugin namespace. */\n\tdeleteBlob(id: string): Promise<void>;\n}\n\n/** Optional JSON convenience helpers. The storage contract itself remains file/bytes based. */\nexport async function readJsonFile<T>(storage: PluginStorageApi, path: string): Promise<T | null> {\n\tconst data = await storage.readFile(path, \"utf8\");\n\treturn data === null ? null : (JSON.parse(data) as T);\n}\n\nexport function writeJsonFile(storage: PluginStorageApi, path: string, value: unknown): Promise<PluginStorageCommitResult> {\n\treturn storage.writeFile(path, JSON.stringify(value, null, 2), \"utf8\");\n}\n"]}

package/dist/ui.d.ts

@@ -9,6 +9,156 @@ export interface PluginGlobalSlotContribution {
     id: string;
     component: ComponentType;
 }
+export interface PluginAbilityDetailSlotProps {
+    abilityId: string;
+    installed: boolean;
+    enabled: boolean;
+}
+/** Inline setup/status surface rendered near the top of one ability detail page. */
+export interface PluginAbilityDetailSlotContribution {
+    id: string;
+    abilityId: string;
+    component: ComponentType<PluginAbilityDetailSlotProps>;
+}
+/**
+ * Props handed to a workspace-view component. A workspace view owns the whole
+ * content area, so unlike panel slots it is addressed by its own route and can
+ * be deep-linked; the host passes back its identity so one component can serve
+ * several registered views.
+ */
+export interface PluginWorkspaceViewProps {
+    /** The contribution id as registered (NOT namespaced). */
+    viewId: string;
+    /** The owning plugin id. */
+    pluginId: string;
+}
+/**
+ * Badge tone. The host maps it to its own theme colors — a plugin cannot pick a
+ * raw color, so badges stay consistent with the built-in navigation entries.
+ */
+export type PluginNavBadgeTone = "accent" | "danger" | "default" | "warning";
+/**
+ * A badge on the plugin's sidebar navigation entry.
+ *
+ * `beta` is the host's own preset — it renders exactly like the built-in
+ * 知识库 Beta 标识, wording included (and localized by the host), so plugins do
+ * not have to spell "Beta" themselves in every locale.
+ *
+ * `count` renders `99+` past 99 and disappears at 0 — an unread badge showing
+ * "0" is worse than no badge.
+ */
+export type PluginNavBadge = {
+    kind: "beta";
+} | {
+    kind: "text";
+    text: string;
+    tone?: PluginNavBadgeTone;
+} | {
+    kind: "count";
+    count: number;
+    tone?: PluginNavBadgeTone;
+} | {
+    kind: "dot";
+    tone?: PluginNavBadgeTone;
+};
+/**
+ * A **workspace view**（工作区视图）: a full-page surface a plugin contributes to
+ * the host's primary navigation. It is the plugin counterpart of a built-in page
+ * such as 自动化 / 知识库 — the host gives it its own route
+ * (`/workspace/<pluginId>/<viewId>`) and a sidebar entry, and the plugin owns the
+ * entire content area while it is open.
+ *
+ * Use it for standalone workbenches that are NOT bound to one conversation
+ * (dashboards, boards, consoles). Conversation-scoped UI belongs in an
+ * {@link PluginActivityTabContribution activity tab}; floating UI belongs in a
+ * {@link PluginGlobalSlotContribution global slot}.
+ */
+export interface PluginWorkspaceViewContribution {
+    /** Unique within the plugin; the host namespaces it as `${pluginId}:${id}`. */
+    id: string;
+    /** Sidebar entry label. Supports `%catalogKey%` i18n lookup. */
+    label: string;
+    /**
+     * Sidebar entry icon as an **iconify class string** (e.g.
+     * `"icon-[solar--widget-5-linear]"`) — NOT a React node, because the host
+     * renders it inside its own nav button and persists nav layout by key.
+     *
+     * Omit it to inherit the plugin's own `plugin.json` icon: a packaged image
+     * (svg / png / webp …) is masked with the theme's foreground color, so a plugin
+     * that ships artwork does not have to find a lookalike in an icon set. Set
+     * {@link PluginWorkspaceViewContribution.iconTint} to `false` to keep its colors.
+     */
+    icon?: string;
+    /**
+     * Whether an image icon is tinted with the theme's foreground color. Defaults to
+     * `true`, which keeps the entry consistent with the built-in navigation and legible
+     * in every theme.
+     *
+     * Pass `false` for a full-color logo. Weigh it first: the entry renders at 16px
+     * beside monochrome built-ins, and a fixed-color image cannot follow the active
+     * theme — a dark logo can disappear on a dark sidebar. Has no effect on Iconify
+     * class icons, which are always tinted.
+     */
+    iconTint?: boolean;
+    /** Optional one-line description; shown as the nav entry tooltip. */
+    description?: string;
+    /**
+     * Initial badge on the sidebar entry. `{ kind: "text" }` supports the same
+     * `%catalogKey%` i18n lookup as {@link label}. Update it at runtime with
+     * {@link PluginUiApi.setWorkspaceViewBadge}.
+     */
+    badge?: PluginNavBadge;
+    /** Zero-props aside from {@link PluginWorkspaceViewProps}. */
+    component: ComponentType<PluginWorkspaceViewProps>;
+    /** Sort hint among this plugin's own views (ascending). Defaults to 0. */
+    navOrder?: number;
+    /**
+     * Whether this view takes a sidebar entry. Defaults to `true`.
+     *
+     * Pass `false` for a surface users open occasionally — a setup page, a
+     * diagnostics console. It then lives only under Settings → More options,
+     * where the host lists every off-sidebar view and opens it inside the
+     * settings shell, so switching between such pages stays one click.
+     *
+     * The sidebar is a scarce, user-curated space: a plugin that always claims a
+     * slot pushes the entries someone actually uses into the overflow menu.
+     */
+    sidebar?: boolean;
+}
+/**
+ * What a workspace view puts into the **host page header** — the window's top
+ * bar that also carries the drag region, the macOS traffic-light gutter and the
+ * sidebar trigger.
+ *
+ * Without this the header still renders, showing the app name above the
+ * plugin's own toolbar — two stacked bars. Set `hideTitle` and move the view's
+ * toolbar in here and the surface gets a single, host-consistent header.
+ *
+ * `left` / `right` are ReactNodes rendered by the host inside that bar (left:
+ * right after the sidebar trigger; right: before the window controls). They are
+ * rendered in the plugin's i18n + CSS scope, so `useTranslation()` and the
+ * plugin's own classes work as usual. Pass fresh nodes whenever the view's
+ * state changes — this is a live setter, not a one-time registration.
+ */
+export interface PluginWorkspaceViewHeader {
+    /** Replaces the host title text. Supports `%catalogKey%` i18n lookup. */
+    title?: string;
+    /** Drop the host title entirely (use when {@link left} carries its own). */
+    hideTitle?: boolean;
+    /** Rendered in the header's left cluster, after the sidebar trigger. */
+    left?: ReactNode;
+    /** Rendered in the header's action cluster, before the window controls. */
+    right?: ReactNode;
+    /**
+     * Float the host header OVER the view instead of stacking above it. The view
+     * then owns the full content height, and its top `~44px` sit under the
+     * transparent header strip (window drag region / traffic lights / sidebar
+     * trigger all keep working on top). Use for immersive full-page surfaces
+     * whose own hero starts at the very top; leave unset for toolbar-style
+     * headers that need their own opaque row.
+     */
+    immersive?: boolean;
+}
 export interface PluginAudioMetadata {
     /** Embedded title; preview renderers should fall back to file.name. */
     title?: string;
@@ -63,10 +213,17 @@ export interface PluginFilePreviewContribution {
  * tab to the "addable pool" — it renders only after the user attaches it in
  * the activity panel (scoped by session cwd).
  */
+/** Host residency policy for an activity-panel tab. */
+export type PluginActivityTabRetention = "active-only" | "warm" | "pinned";
 export interface PluginActivityTabContribution {
     id: string;
     label: string;
-    /** Tab icon as a React node (not an iconify class string). */
+    /**
+     * Tab icon as a React node (not an iconify class string).
+     * Omit to inherit the host-resolved brand icon from `plugin.json#icon`
+     * (`ctx.plugin.iconUrl`). Prefer omitting for package brand icons so the
+     * plugin never loads assets via absolute `/…` paths or host protocols.
+     */
     icon?: ReactNode;
     component: ComponentType;
     /**
@@ -82,13 +239,36 @@ export interface PluginActivityTabContribution {
      * 工作台跟随输入栏 toggle）。无论哪种，用户仍可用减号手动隐藏。
      */
     initiallyVisible?: boolean;
+    /**
+     * Component residency while the tab is inactive. Defaults to `"warm"`:
+     * visited tabs stay mounted in the host's bounded LRU cache. Use
+     * `"active-only"` for cheap, stateless content and `"pinned"` for runtimes
+     * that must never be evicted while available.
+     */
+    retention?: PluginActivityTabRetention;
+    /**
+     * @deprecated Use {@link PluginActivityTabContribution.retention}. `true`
+     * maps to `"pinned"`; `false` maps to `"active-only"`.
+     */
+    keepAliveWhenAvailable?: boolean;
+}
+/** Explicit conversation scope for an activity-tab command. */
+export interface PluginActivityTabTargetOptions {
+    /**
+     * Absolute cwd whose activity-tab state should be changed. Omit to target
+     * the conversation currently displayed by the host. Tool handlers and
+     * background work should pass the triggering session's cwd so a foreground
+     * navigation change cannot redirect the command to another conversation.
+     */
+    cwd?: string;
 }
 /** Options for {@link PluginUiApi.openActivityTab}. */
-export interface PluginOpenActivityTabOptions {
+export interface PluginOpenActivityTabOptions extends PluginActivityTabTargetOptions {
     /**
-     * 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.
+     * Desired panel width as it opens: a pixel number, or `"max"` to track the
+     * widest the window allows — `"max"` keeps following window resizes until the
+     * user drags the divider. The host clamps to its min/max bounds. Omit to keep
+     * the user's current width.
      */
     width?: number | "max";
 }
@@ -206,7 +386,7 @@ export interface PluginToolCallSlotToolCall {
     toolCallId: string;
     toolName: string;
     args: Record<string, unknown>;
-    status: "pending" | "success" | "error";
+    status: "pending" | "success" | "error" | "cancelled";
     result?: string;
     isError?: boolean;
 }
@@ -266,8 +446,138 @@ export interface PluginNotifyOptions {
      */
     durationMs?: number;
 }
+/**
+ * 新会话上下文区的激活条件。**只能写本插件自己的东西**——填别人的 id 一律不生效。
+ *
+ * 这条限制是故意的：否则插件 A 可以声明「只要用户选了 B 的智能体我就上屏」，把别人的
+ * 使用场景劫持过来。
+ *
+ * 各字段取并集：任意一条命中即激活。至少要声明一条——全空等于「任何新会话都上屏」，宿主拒掉。
+ */
+export interface PluginNewSessionContextActivation {
+    /** 本插件在 manifest 里声明的智能体 id（不带 `plugin:` 前缀）。 */
+    agents?: readonly string[];
+    /** 本插件在 manifest 里声明的团队 id。省略则任意「含本插件成员的团队」都算命中。 */
+    teams?: readonly string[];
+    /** 本插件提供的 skill 名；用户在输入框里提到时命中。 */
+    skills?: readonly string[];
+    /** 本插件提供的 MCP server 名。 */
+    mcpServers?: readonly string[];
+}
+/** 用户在新会话页当前选中的对话目标。 */
+export interface PluginNewSessionTarget {
+    readonly kind: "agent" | "team";
+    /** Agent 档案 id 或团队 id。 */
+    readonly id: string;
+    /** 目标若由本插件贡献，这里给出 manifest 里的那个 id。 */
+    readonly contributedId?: string;
+}
+/**
+ * 渲染上下文。这是一个**会继续生长的对象**：后续新增字段不会破坏既有插件，所以按需
+ * 解构、不要假定它只有这些键。
+ */
+export interface PluginNewSessionContext {
+    readonly target: PluginNewSessionTarget | null;
+    /** 输入框里提到的、属于本插件的能力。 */
+    readonly mentionedAbilities: {
+        readonly skills: readonly string[];
+        readonly mcpServers: readonly string[];
+    };
+    /**
+     * 输入框中尚未发送的文本。需要 `conversation.draft.read` 权限，未授予时恒为空串。
+     *
+     * 只在本贡献处于激活状态时提供——插件拿不到「用户随便打点什么」的全程流水。
+     */
+    readonly draft: string;
+    /** 当前工作区目录；未选择项目时为 null。 */
+    readonly cwd: string | null;
+    /** 回写输入栏。刻意不提供「直接发送」：越过发送前这道关不属于本区职责。 */
+    readonly composer: {
+        /** 把资源挂成附件，随下一次发送带走。 */
+        attach(attachment: PluginPromptAttachment): void;
+        /**
+         * 往草稿里插一段文本。始终是插入而非替换，免得抹掉用户已经打的内容。
+         *
+         * `position` 缺省为 `"end"`（光标处）。`"start"` 插到最前面，适合「先定题、细节
+         * 由用户补」这类写法——用户点完多半光标并不在开头，位置只能由调用方定死。
+         */
+        insertText(text: string, options?: {
+            position?: "start" | "end";
+        }): void;
+    };
+}
+/**
+ * 新会话页输入框下方的一块内容（`ui.slot.new-session-context`）。
+ *
+ * 与 input-action 的分工：那是发送前的开关，这是发送前的**上下文**——把用户接下来多半
+ * 要用到的素材摆出来。激活与否由宿主按 {@link PluginNewSessionContextActivation} 裁决，
+ * 插件只负责在被激活后渲染，因此拿不到用户逐键输入的全程内容。
+ *
+ * 同时有多个贡献上屏时，宿主会在该区域顶部出 tabbar；只有一个时直接渲染内容。
+ */
+export interface PluginNewSessionContextContribution {
+    id: string;
+    /** tabbar 上的标题；只有一个贡献上屏时不展示。 */
+    label: string;
+    /** tab 图标；省略时用插件自己的图标。 */
+    icon?: ReactNode;
+    activateWhen: PluginNewSessionContextActivation;
+    /**
+     * 横向占位。`"input"`（默认）与输入框同宽，适合补充说明一类的窄内容；`"wide"` 铺满
+     * 页面可用宽度，留给画廊、素材墙这类「内容本身就是主角」的东西——把它们压在输入框
+     * 宽度里，每一项都会小到看不清。
+     */
+    width?: "input" | "wide";
+    render(context: PluginNewSessionContext): ReactNode;
+}
 export interface PluginUiApi {
     registerGlobalSlot(contribution: PluginGlobalSlotContribution): Disposable;
+    registerAbilityDetailSlot(contribution: PluginAbilityDetailSlotContribution): Disposable;
+    /** Render an opaque setup URL as a host-themed PNG data URL. */
+    createQrCode(text: string): Promise<string>;
+    /**
+     * Register a **workspace view**（工作区视图）— a full-page surface with its own
+     * route and sidebar entry, on par with the host's built-in pages. Needs the
+     * `ui.slot.workspace-view` permission (missing permission = **warn+noop**).
+     *
+     * The entry lands in the sidebar's「更多」收纳 by default; the user can pin it
+     * to the top region or reorder it, and that layout is remembered.
+     */
+    registerWorkspaceView(contribution: PluginWorkspaceViewContribution): Disposable;
+    /**
+     * Register a **new-session context block** — content shown beneath the input
+     * on the new-session page, surfaced only when the user's current selection or
+     * draft matches {@link PluginNewSessionContextActivation}. Needs the
+     * `ui.slot.new-session-context` permission (missing permission = **warn+noop**).
+     */
+    registerNewSessionContext(contribution: PluginNewSessionContextContribution): Disposable;
+    /**
+     * Navigate to one of this plugin's own workspace views. `viewId` is the
+     * contribution id passed to {@link PluginUiApi.registerWorkspaceView}. No-op
+     * when the view is not registered (e.g. permission missing).
+     */
+    openWorkspaceView(viewId: string): void;
+    /**
+     * Update (or clear, with `null`) the badge on one of this plugin's workspace
+     * view entries. Re-registering the view is NOT a way to do this — it would
+     * remount the whole surface — so live badges (unread counts, status dots)
+     * must come through here.
+     *
+     * No-op when the view is not registered (e.g. permission missing).
+     */
+    setWorkspaceViewBadge(viewId: string, badge: PluginNavBadge | null): void;
+    /**
+     * Fill (or clear, with `null`) the host page header while one of this
+     * plugin's workspace views is open. Call it from the view component (an
+     * effect that re-runs on state change) and clear it on unmount — the host
+     * keeps the entry keyed by view, and only applies it on that view's route.
+     *
+     * The header itself is never removed: it owns the window drag region and the
+     * macOS traffic-light gutter. This is how a view takes it over instead.
+     *
+     * No-op when the view is not registered (e.g. permission missing).
+     */
+    setWorkspaceViewHeader(viewId: string, header: PluginWorkspaceViewHeader | null): void;
     /**
      * Register a preview component keyed by file extension. The host dispatches
      * registered extensions before its built-in fallback renderers; first
@@ -317,7 +627,7 @@ export interface PluginUiApi {
     registerShortcutScope(contribution: PluginShortcutScopeContribution): Disposable;
     /**
      * Programmatically attach (if needed) and activate one of this plugin's
-     * own activity tabs in the current conversation's activity panel. `tabId`
+     * own activity tabs in a 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.
      *
@@ -325,22 +635,29 @@ export interface PluginUiApi {
      * `"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.
+     *
+     * Omit `options.cwd` for the conversation currently displayed by the host.
+     * Tool handlers and background work should pass their session cwd explicitly.
      */
     openActivityTab(tabId: string, options?: PluginOpenActivityTabOptions): void;
     /**
-     * 把本插件的某个活动面板标签卡在当前会话里上栏 / 下栏，**不激活也不展开
+     * 把本插件的某个活动面板标签卡在目标会话里上栏 / 下栏，**不激活也不展开
      * 面板**——`openActivityTab` 是「用户此刻要看它」，这个是「它现在该不该在
      * 栏里」。配合 `initiallyVisible: false` 使用，插件即可完全掌握自己标签卡的
      * 出现条件（如 git 只在仓库目录里上栏、工作台跟随输入栏 toggle）。
      *
      * 上栏记录按会话 cwd 持久化（ADR-0026），所以只需在条件变化时调用一次；
-     * 用户随后用减号手动隐藏的结果不会被重复调用覆盖。当前没有活动会话时为
-     * no-op（无处记录），插件应在会话就绪后重新判定。
+     * 用户随后用减号手动隐藏的结果不会被重复调用覆盖。缺省作用于宿主当前显示的
+     * 会话；工具 handler 与后台任务应通过 `options.cwd` 传入自己的会话 cwd。既没有
+     * 显式 cwd、也没有活动会话时为 no-op（无处记录）。
      */
-    setActivityTabVisible(tabId: string, visible: boolean): void;
+    setActivityTabVisible(tabId: string, visible: boolean, options?: PluginActivityTabTargetOptions): void;
     /**
-     * 直接设置活动面板宽度：像素值，或 `"max"` 表示当前窗口下的最大宽度（宿主仍
-     * 会夹到自己的 min/max 内，必要时自动收起侧边栏）。
+     * 直接设置活动面板宽度：像素值，或 `"max"` 表示「跟随窗口拉满」（宿主仍会夹到
+     * 自己的 min/max 内，必要时自动收起侧边栏）。
+     *
+     * `"max"` 是一种持续状态而非一次性求值：窗口尺寸变化时面板跟着变宽变窄，直到
+     * 用户拖动分隔条或有人写入具体像素为止。传数字则是一次性的固定宽度。
      *
      * 与 `openActivityTab(id, { width })` 的区别：那里的宽度只在标签卡首次 attach
      * 时生效（避免 activate 重放覆盖用户手拖的宽度）；这个是命令式的，每次调用都
@@ -348,9 +665,10 @@ export interface PluginUiApi {
      */
     setActivityPanelWidth(width: number | "max"): void;
     /**
-     * Bind or clear plugin-owned one-shot context for the next outgoing prompt.
-     * The host renders its label/icon, merges metadata and hidden instructions,
-     * then clears it after send or when the user closes the capsule.
+     * Bind or clear plugin-owned context for outgoing prompts. The host renders
+     * its label/icon and carries a structured `context` as a versioned snapshot.
+     * Attachments default to one-shot; `lifecycle: "sticky"` remains until the
+     * plugin or user clears the capsule.
      */
     setPromptAttachment(attachment: PluginPromptAttachment | null): void;
     /**
@@ -361,12 +679,6 @@ export interface PluginUiApi {
      * 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;
     /**
      * Capture a rectangle in the current Vetta window and open the host save
      * dialog. Coordinates use renderer DIP values such as getBoundingClientRect().
@@ -380,6 +692,13 @@ export interface PluginUiApi {
      * can only write what it already rendered.
      */
     copyImage(dataUrl: string): Promise<void>;
+    /**
+     * Hand a URL to the OS default browser (Electron `shell.openExternal`) —
+     * NOT the in-app browser panel. Only `http:`/`https:` are accepted; the host
+     * rejects every other protocol, so this cannot be used to launch arbitrary
+     * schemes. Needs `shell.openExternal`.
+     */
+    openExternal(url: string): Promise<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