@vetta-org/plugin-sdk 0.1.0 → 0.1.1

package/dist/command.d.ts

@@ -12,14 +12,57 @@ export interface PluginCommandRunResult {
     /** Process exit code; null when the process was killed by a signal/timeout. */
     exitCode: number | null;
 }
+import type { Disposable } from "./disposable.js";
+export interface PluginCommandSpawnOptions {
+    /** Working directory. Must resolve inside a host-allowed root (e.g. a project). */
+    cwd?: string;
+    /** Extra environment entries, merged over the host process env (PATH preserved). */
+    env?: Record<string, string>;
+    /**
+     * Ask the host to allocate a free localhost port. Every literal `{{PORT}}`
+     * in args/env values is substituted with it, and the handle exposes `port`.
+     */
+    allocatePort?: boolean;
+}
+export interface PluginCommandSpawnExit {
+    exitCode: number | null;
+    signal: string | null;
+}
+export interface PluginCommandSpawnStatus {
+    running: boolean;
+    pid: number;
+    port?: number;
+    exit?: PluginCommandSpawnExit;
+    /** Ring-buffered combined stdout+stderr tail (~64KB), for diagnostics. */
+    recentOutput: string;
+}
+/** Handle to a long-lived process started via {@link PluginCommandApi.spawn}. */
+export interface PluginCommandSpawnHandle {
+    spawnId: string;
+    pid: number;
+    /** Present when `allocatePort` was requested. */
+    port?: number;
+    /** SIGTERM the process tree; SIGKILL after a grace period. Idempotent. */
+    stop(): Promise<void>;
+    status(): Promise<PluginCommandSpawnStatus>;
+    /** Fires once when the process exits (any reason). */
+    onExit(listener: (exit: PluginCommandSpawnExit) => void): Disposable;
+}
 /**
  * Run an allowed host command (e.g. `git`). execFile semantics — NO shell, args
  * are passed as an array (no string splitting, no injection). The executable
  * must be declared in plugin.json's `commands` and currently enabled by the
  * user; otherwise the call is rejected (and the host notifies the user). Needs
  * the `agent.command.run` permission.
+ *
+ * `spawn` starts a long-lived process instead (ADR-0054, e.g. a local dev
+ * server): same manifest `commands` declaration and user toggle, but gated by
+ * the separate `agent.command.spawn` permission. The child runs in its own
+ * process group; the host kills the whole tree on stop, plugin unload/disable,
+ * and app quit.
  */
 export interface PluginCommandApi {
     run(file: string, args?: string[], options?: PluginCommandRunOptions): Promise<PluginCommandRunResult>;
+    spawn(file: string, args?: string[], options?: PluginCommandSpawnOptions): Promise<PluginCommandSpawnHandle>;
 }
 //# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,uBAAuB;IACvC,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACvG","sourcesContent":["export interface PluginCommandRunOptions {\n\t/** Working directory. Must resolve inside a host-allowed root (e.g. a project). */\n\tcwd?: string;\n\t/** Extra environment entries, merged over the host process env (PATH preserved). */\n\tenv?: Record<string, string>;\n\t/** Hard timeout in ms; the host clamps to its own maximum. */\n\ttimeoutMs?: number;\n}\n\nexport interface PluginCommandRunResult {\n\tstdout: string;\n\tstderr: string;\n\t/** Process exit code; null when the process was killed by a signal/timeout. */\n\texitCode: number | null;\n}\n\n/**\n * Run an allowed host command (e.g. `git`). execFile semantics — NO shell, args\n * are passed as an array (no string splitting, no injection). The executable\n * must be declared in plugin.json's `commands` and currently enabled by the\n * user; otherwise the call is rejected (and the host notifies the user). Needs\n * the `agent.command.run` permission.\n */\nexport interface PluginCommandApi {\n\trun(file: string, args?: string[], options?: PluginCommandRunOptions): Promise<PluginCommandRunResult>;\n}\n"]}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,uBAAuB;IACvC,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,WAAW,yBAAyB;IACzC,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,iFAAiF;AACjF,MAAM,WAAW,wBAAwB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,MAAM,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAC5C,sDAAsD;IACtD,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,sBAAsB,KAAK,IAAI,GAAG,UAAU,CAAC;CACrE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAChC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACvG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC7G","sourcesContent":["export interface PluginCommandRunOptions {\n\t/** Working directory. Must resolve inside a host-allowed root (e.g. a project). */\n\tcwd?: string;\n\t/** Extra environment entries, merged over the host process env (PATH preserved). */\n\tenv?: Record<string, string>;\n\t/** Hard timeout in ms; the host clamps to its own maximum. */\n\ttimeoutMs?: number;\n}\n\nexport interface PluginCommandRunResult {\n\tstdout: string;\n\tstderr: string;\n\t/** Process exit code; null when the process was killed by a signal/timeout. */\n\texitCode: number | null;\n}\n\nimport type { Disposable } from \"./disposable.js\";\n\nexport interface PluginCommandSpawnOptions {\n\t/** Working directory. Must resolve inside a host-allowed root (e.g. a project). */\n\tcwd?: string;\n\t/** Extra environment entries, merged over the host process env (PATH preserved). */\n\tenv?: Record<string, string>;\n\t/**\n\t * Ask the host to allocate a free localhost port. Every literal `{{PORT}}`\n\t * in args/env values is substituted with it, and the handle exposes `port`.\n\t */\n\tallocatePort?: boolean;\n}\n\nexport interface PluginCommandSpawnExit {\n\texitCode: number | null;\n\tsignal: string | null;\n}\n\nexport interface PluginCommandSpawnStatus {\n\trunning: boolean;\n\tpid: number;\n\tport?: number;\n\texit?: PluginCommandSpawnExit;\n\t/** Ring-buffered combined stdout+stderr tail (~64KB), for diagnostics. */\n\trecentOutput: string;\n}\n\n/** Handle to a long-lived process started via {@link PluginCommandApi.spawn}. */\nexport interface PluginCommandSpawnHandle {\n\tspawnId: string;\n\tpid: number;\n\t/** Present when `allocatePort` was requested. */\n\tport?: number;\n\t/** SIGTERM the process tree; SIGKILL after a grace period. Idempotent. */\n\tstop(): Promise<void>;\n\tstatus(): Promise<PluginCommandSpawnStatus>;\n\t/** Fires once when the process exits (any reason). */\n\tonExit(listener: (exit: PluginCommandSpawnExit) => void): Disposable;\n}\n\n/**\n * Run an allowed host command (e.g. `git`). execFile semantics — NO shell, args\n * are passed as an array (no string splitting, no injection). The executable\n * must be declared in plugin.json's `commands` and currently enabled by the\n * user; otherwise the call is rejected (and the host notifies the user). Needs\n * the `agent.command.run` permission.\n *\n * `spawn` starts a long-lived process instead (ADR-0054, e.g. a local dev\n * server): same manifest `commands` declaration and user toggle, but gated by\n * the separate `agent.command.spawn` permission. The child runs in its own\n * process group; the host kills the whole tree on stop, plugin unload/disable,\n * and app quit.\n */\nexport interface PluginCommandApi {\n\trun(file: string, args?: string[], options?: PluginCommandRunOptions): Promise<PluginCommandRunResult>;\n\tspawn(file: string, args?: string[], options?: PluginCommandSpawnOptions): Promise<PluginCommandSpawnHandle>;\n}\n"]}

package/dist/command.js.map

@@ -1 +1 @@
-{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"","sourcesContent":["export interface PluginCommandRunOptions {\n\t/** Working directory. Must resolve inside a host-allowed root (e.g. a project). */\n\tcwd?: string;\n\t/** Extra environment entries, merged over the host process env (PATH preserved). */\n\tenv?: Record<string, string>;\n\t/** Hard timeout in ms; the host clamps to its own maximum. */\n\ttimeoutMs?: number;\n}\n\nexport interface PluginCommandRunResult {\n\tstdout: string;\n\tstderr: string;\n\t/** Process exit code; null when the process was killed by a signal/timeout. */\n\texitCode: number | null;\n}\n\n/**\n * Run an allowed host command (e.g. `git`). execFile semantics — NO shell, args\n * are passed as an array (no string splitting, no injection). The executable\n * must be declared in plugin.json's `commands` and currently enabled by the\n * user; otherwise the call is rejected (and the host notifies the user). Needs\n * the `agent.command.run` permission.\n */\nexport interface PluginCommandApi {\n\trun(file: string, args?: string[], options?: PluginCommandRunOptions): Promise<PluginCommandRunResult>;\n}\n"]}
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"","sourcesContent":["export interface PluginCommandRunOptions {\n\t/** Working directory. Must resolve inside a host-allowed root (e.g. a project). */\n\tcwd?: string;\n\t/** Extra environment entries, merged over the host process env (PATH preserved). */\n\tenv?: Record<string, string>;\n\t/** Hard timeout in ms; the host clamps to its own maximum. */\n\ttimeoutMs?: number;\n}\n\nexport interface PluginCommandRunResult {\n\tstdout: string;\n\tstderr: string;\n\t/** Process exit code; null when the process was killed by a signal/timeout. */\n\texitCode: number | null;\n}\n\nimport type { Disposable } from \"./disposable.js\";\n\nexport interface PluginCommandSpawnOptions {\n\t/** Working directory. Must resolve inside a host-allowed root (e.g. a project). */\n\tcwd?: string;\n\t/** Extra environment entries, merged over the host process env (PATH preserved). */\n\tenv?: Record<string, string>;\n\t/**\n\t * Ask the host to allocate a free localhost port. Every literal `{{PORT}}`\n\t * in args/env values is substituted with it, and the handle exposes `port`.\n\t */\n\tallocatePort?: boolean;\n}\n\nexport interface PluginCommandSpawnExit {\n\texitCode: number | null;\n\tsignal: string | null;\n}\n\nexport interface PluginCommandSpawnStatus {\n\trunning: boolean;\n\tpid: number;\n\tport?: number;\n\texit?: PluginCommandSpawnExit;\n\t/** Ring-buffered combined stdout+stderr tail (~64KB), for diagnostics. */\n\trecentOutput: string;\n}\n\n/** Handle to a long-lived process started via {@link PluginCommandApi.spawn}. */\nexport interface PluginCommandSpawnHandle {\n\tspawnId: string;\n\tpid: number;\n\t/** Present when `allocatePort` was requested. */\n\tport?: number;\n\t/** SIGTERM the process tree; SIGKILL after a grace period. Idempotent. */\n\tstop(): Promise<void>;\n\tstatus(): Promise<PluginCommandSpawnStatus>;\n\t/** Fires once when the process exits (any reason). */\n\tonExit(listener: (exit: PluginCommandSpawnExit) => void): Disposable;\n}\n\n/**\n * Run an allowed host command (e.g. `git`). execFile semantics — NO shell, args\n * are passed as an array (no string splitting, no injection). The executable\n * must be declared in plugin.json's `commands` and currently enabled by the\n * user; otherwise the call is rejected (and the host notifies the user). Needs\n * the `agent.command.run` permission.\n *\n * `spawn` starts a long-lived process instead (ADR-0054, e.g. a local dev\n * server): same manifest `commands` declaration and user toggle, but gated by\n * the separate `agent.command.spawn` permission. The child runs in its own\n * process group; the host kills the whole tree on stop, plugin unload/disable,\n * and app quit.\n */\nexport interface PluginCommandApi {\n\trun(file: string, args?: string[], options?: PluginCommandRunOptions): Promise<PluginCommandRunResult>;\n\tspawn(file: string, args?: string[], options?: PluginCommandSpawnOptions): Promise<PluginCommandSpawnHandle>;\n}\n"]}

package/dist/context.d.ts

@@ -3,6 +3,7 @@ import type { PluginAppActionsApi } from "./app-actions.js";
 import type { PluginCommandApi } from "./command.js";
 import type { PluginConversationApi } from "./conversation.js";
 import type { Disposable } from "./disposable.js";
+import type { PluginFileExplorerApi } from "./file-explorer.js";
 import type { PluginFsApi } from "./fs.js";
 import type { PluginI18nApi } from "./i18n.js";
 import type { PluginNetworkApi } from "./network.js";
@@ -24,6 +25,7 @@ export interface PluginContext {
     };
     permissions: PluginPermissionApi;
     ui: PluginUiApi;
+    fileExplorer: PluginFileExplorerApi;
     conversation: PluginConversationApi;
     agent: PluginAgentApi;
     appActions: PluginAppActionsApi;

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,WAAW,mBAAmB;IACnC,GAAG,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAC3C,OAAO,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC5C;AAED,mGAA2D;AAC3D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC7B,MAAM,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,EAAE,mBAAmB,CAAC;IACjC,EAAE,EAAE,WAAW,CAAC;IAChB,YAAY,EAAE,qBAAqB,CAAC;IACpC,KAAK,EAAE,cAAc,CAAC;IACtB,UAAU,EAAE,mBAAmB,CAAC;IAChC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,EAAE,EAAE,WAAW,CAAC;IAChB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,gGAAkD;IAClD,YAAY,IAAI,SAAS,CAAC;IAC1B,8FAA4C;IAC5C,kBAAkB,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,GAAG,UAAU,CAAC;CACpE;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,UAAU,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAEvE","sourcesContent":["import type { PluginAgentApi } from \"./agent.js\";\nimport type { PluginAppActionsApi } from \"./app-actions.js\";\nimport type { PluginCommandApi } from \"./command.js\";\nimport type { PluginConversationApi } from \"./conversation.js\";\nimport type { Disposable } from \"./disposable.js\";\nimport type { PluginFsApi } from \"./fs.js\";\nimport type { PluginI18nApi } from \"./i18n.js\";\nimport type { PluginNetworkApi } from \"./network.js\";\nimport type { PluginOfficialApi } from \"./official.js\";\nimport type { PluginPermission } from \"./permissions.js\";\nimport type { PluginSettingsApi } from \"./settings.js\";\nimport type { PluginStorageApi } from \"./storage.js\";\nimport type { PluginUiApi } from \"./ui.js\";\n\nexport interface PluginPermissionApi {\n\thas(permission: PluginPermission): boolean;\n\trequire(permission: PluginPermission): void;\n}\n\n/** 工作模式（agent_mode 轴，见 ADR-0046）。宿主 Work/Coding，未来可能扩展。 */\nexport type AgentMode = \"work\" | \"coding\";\n\nexport interface PluginContext {\n\tplugin: {\n\t\tid: string;\n\t\tversion: string;\n\t};\n\tpermissions: PluginPermissionApi;\n\tui: PluginUiApi;\n\tconversation: PluginConversationApi;\n\tagent: PluginAgentApi;\n\tappActions: PluginAppActionsApi;\n\tofficial: PluginOfficialApi;\n\tfs: PluginFsApi;\n\tcommand: PluginCommandApi;\n\tnetwork: PluginNetworkApi;\n\tstorage: PluginStorageApi;\n\tsettings: PluginSettingsApi;\n\ti18n: PluginI18nApi;\n\t/** 当前工作模式（agent_mode 轴）。开发者据此做模式定制。见 ADR-0046。 */\n\tgetAgentMode(): AgentMode;\n\t/** 订阅工作模式变更（纯全局实时切换）。返回 Disposable 取消订阅。 */\n\tonAgentModeChanged(listener: (mode: AgentMode) => void): Disposable;\n}\n\nexport interface PluginDefinition {\n\tactivate(ctx: PluginContext): void | Promise<void>;\n\tdeactivate?(): void | Promise<void>;\n}\n\nexport function definePlugin(plugin: PluginDefinition): PluginDefinition {\n\treturn plugin;\n}\n"]}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,WAAW,mBAAmB;IACnC,GAAG,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAC3C,OAAO,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC5C;AAED,mGAA2D;AAC3D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC7B,MAAM,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,EAAE,mBAAmB,CAAC;IACjC,EAAE,EAAE,WAAW,CAAC;IAChB,YAAY,EAAE,qBAAqB,CAAC;IACpC,YAAY,EAAE,qBAAqB,CAAC;IACpC,KAAK,EAAE,cAAc,CAAC;IACtB,UAAU,EAAE,mBAAmB,CAAC;IAChC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,EAAE,EAAE,WAAW,CAAC;IAChB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,gGAAkD;IAClD,YAAY,IAAI,SAAS,CAAC;IAC1B,8FAA4C;IAC5C,kBAAkB,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,GAAG,UAAU,CAAC;CACpE;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,UAAU,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAEvE","sourcesContent":["import type { PluginAgentApi } from \"./agent.js\";\nimport type { PluginAppActionsApi } from \"./app-actions.js\";\nimport type { PluginCommandApi } from \"./command.js\";\nimport type { PluginConversationApi } from \"./conversation.js\";\nimport type { Disposable } from \"./disposable.js\";\nimport type { PluginFileExplorerApi } from \"./file-explorer.js\";\nimport type { PluginFsApi } from \"./fs.js\";\nimport type { PluginI18nApi } from \"./i18n.js\";\nimport type { PluginNetworkApi } from \"./network.js\";\nimport type { PluginOfficialApi } from \"./official.js\";\nimport type { PluginPermission } from \"./permissions.js\";\nimport type { PluginSettingsApi } from \"./settings.js\";\nimport type { PluginStorageApi } from \"./storage.js\";\nimport type { PluginUiApi } from \"./ui.js\";\n\nexport interface PluginPermissionApi {\n\thas(permission: PluginPermission): boolean;\n\trequire(permission: PluginPermission): void;\n}\n\n/** 工作模式（agent_mode 轴，见 ADR-0046）。宿主 Work/Coding，未来可能扩展。 */\nexport type AgentMode = \"work\" | \"coding\";\n\nexport interface PluginContext {\n\tplugin: {\n\t\tid: string;\n\t\tversion: string;\n\t};\n\tpermissions: PluginPermissionApi;\n\tui: PluginUiApi;\n\tfileExplorer: PluginFileExplorerApi;\n\tconversation: PluginConversationApi;\n\tagent: PluginAgentApi;\n\tappActions: PluginAppActionsApi;\n\tofficial: PluginOfficialApi;\n\tfs: PluginFsApi;\n\tcommand: PluginCommandApi;\n\tnetwork: PluginNetworkApi;\n\tstorage: PluginStorageApi;\n\tsettings: PluginSettingsApi;\n\ti18n: PluginI18nApi;\n\t/** 当前工作模式（agent_mode 轴）。开发者据此做模式定制。见 ADR-0046。 */\n\tgetAgentMode(): AgentMode;\n\t/** 订阅工作模式变更（纯全局实时切换）。返回 Disposable 取消订阅。 */\n\tonAgentModeChanged(listener: (mode: AgentMode) => void): Disposable;\n}\n\nexport interface PluginDefinition {\n\tactivate(ctx: PluginContext): void | Promise<void>;\n\tdeactivate?(): void | Promise<void>;\n}\n\nexport function definePlugin(plugin: PluginDefinition): PluginDefinition {\n\treturn plugin;\n}\n"]}

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAkDA,MAAM,UAAU,YAAY,CAAC,MAAwB,EAAoB;IACxE,OAAO,MAAM,CAAC;AAAA,CACd","sourcesContent":["import type { PluginAgentApi } from \"./agent.js\";\nimport type { PluginAppActionsApi } from \"./app-actions.js\";\nimport type { PluginCommandApi } from \"./command.js\";\nimport type { PluginConversationApi } from \"./conversation.js\";\nimport type { Disposable } from \"./disposable.js\";\nimport type { PluginFsApi } from \"./fs.js\";\nimport type { PluginI18nApi } from \"./i18n.js\";\nimport type { PluginNetworkApi } from \"./network.js\";\nimport type { PluginOfficialApi } from \"./official.js\";\nimport type { PluginPermission } from \"./permissions.js\";\nimport type { PluginSettingsApi } from \"./settings.js\";\nimport type { PluginStorageApi } from \"./storage.js\";\nimport type { PluginUiApi } from \"./ui.js\";\n\nexport interface PluginPermissionApi {\n\thas(permission: PluginPermission): boolean;\n\trequire(permission: PluginPermission): void;\n}\n\n/** 工作模式（agent_mode 轴，见 ADR-0046）。宿主 Work/Coding，未来可能扩展。 */\nexport type AgentMode = \"work\" | \"coding\";\n\nexport interface PluginContext {\n\tplugin: {\n\t\tid: string;\n\t\tversion: string;\n\t};\n\tpermissions: PluginPermissionApi;\n\tui: PluginUiApi;\n\tconversation: PluginConversationApi;\n\tagent: PluginAgentApi;\n\tappActions: PluginAppActionsApi;\n\tofficial: PluginOfficialApi;\n\tfs: PluginFsApi;\n\tcommand: PluginCommandApi;\n\tnetwork: PluginNetworkApi;\n\tstorage: PluginStorageApi;\n\tsettings: PluginSettingsApi;\n\ti18n: PluginI18nApi;\n\t/** 当前工作模式（agent_mode 轴）。开发者据此做模式定制。见 ADR-0046。 */\n\tgetAgentMode(): AgentMode;\n\t/** 订阅工作模式变更（纯全局实时切换）。返回 Disposable 取消订阅。 */\n\tonAgentModeChanged(listener: (mode: AgentMode) => void): Disposable;\n}\n\nexport interface PluginDefinition {\n\tactivate(ctx: PluginContext): void | Promise<void>;\n\tdeactivate?(): void | Promise<void>;\n}\n\nexport function definePlugin(plugin: PluginDefinition): PluginDefinition {\n\treturn plugin;\n}\n"]}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAoDA,MAAM,UAAU,YAAY,CAAC,MAAwB,EAAoB;IACxE,OAAO,MAAM,CAAC;AAAA,CACd","sourcesContent":["import type { PluginAgentApi } from \"./agent.js\";\nimport type { PluginAppActionsApi } from \"./app-actions.js\";\nimport type { PluginCommandApi } from \"./command.js\";\nimport type { PluginConversationApi } from \"./conversation.js\";\nimport type { Disposable } from \"./disposable.js\";\nimport type { PluginFileExplorerApi } from \"./file-explorer.js\";\nimport type { PluginFsApi } from \"./fs.js\";\nimport type { PluginI18nApi } from \"./i18n.js\";\nimport type { PluginNetworkApi } from \"./network.js\";\nimport type { PluginOfficialApi } from \"./official.js\";\nimport type { PluginPermission } from \"./permissions.js\";\nimport type { PluginSettingsApi } from \"./settings.js\";\nimport type { PluginStorageApi } from \"./storage.js\";\nimport type { PluginUiApi } from \"./ui.js\";\n\nexport interface PluginPermissionApi {\n\thas(permission: PluginPermission): boolean;\n\trequire(permission: PluginPermission): void;\n}\n\n/** 工作模式（agent_mode 轴，见 ADR-0046）。宿主 Work/Coding，未来可能扩展。 */\nexport type AgentMode = \"work\" | \"coding\";\n\nexport interface PluginContext {\n\tplugin: {\n\t\tid: string;\n\t\tversion: string;\n\t};\n\tpermissions: PluginPermissionApi;\n\tui: PluginUiApi;\n\tfileExplorer: PluginFileExplorerApi;\n\tconversation: PluginConversationApi;\n\tagent: PluginAgentApi;\n\tappActions: PluginAppActionsApi;\n\tofficial: PluginOfficialApi;\n\tfs: PluginFsApi;\n\tcommand: PluginCommandApi;\n\tnetwork: PluginNetworkApi;\n\tstorage: PluginStorageApi;\n\tsettings: PluginSettingsApi;\n\ti18n: PluginI18nApi;\n\t/** 当前工作模式（agent_mode 轴）。开发者据此做模式定制。见 ADR-0046。 */\n\tgetAgentMode(): AgentMode;\n\t/** 订阅工作模式变更（纯全局实时切换）。返回 Disposable 取消订阅。 */\n\tonAgentModeChanged(listener: (mode: AgentMode) => void): Disposable;\n}\n\nexport interface PluginDefinition {\n\tactivate(ctx: PluginContext): void | Promise<void>;\n\tdeactivate?(): void | Promise<void>;\n}\n\nexport function definePlugin(plugin: PluginDefinition): PluginDefinition {\n\treturn plugin;\n}\n"]}

package/dist/conversation.d.ts

@@ -28,6 +28,7 @@ export type ConversationEvent = {
     type: "tool-call-start";
     toolCallId: string;
     toolName: string;
+    args?: Record<string, unknown>;
 } | {
     type: "tool-call-end";
     toolCallId: string;

package/dist/conversation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,WAAW,iBAAiB;IACjC,wEAAwE;IACxE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,YAAY,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,iBAAiB,GAC1B;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,YAAY,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAErE,MAAM,WAAW,qBAAqB;IACrC,2EAA2E;IAC3E,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,sEAAsE;IACtE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oDAAoD;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;;;OAMG;IACH,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,UAAU,CAAC;CAC7D","sourcesContent":["import type { Disposable } from \"./disposable.js\";\n\nexport interface ConversationState {\n\t/** Active session runtimeId, or null when no conversation is active. */\n\tid: string | null;\n\tcwd: string | null;\n\tsessionPath: string | null;\n\tmodel: string | null;\n\tisStreaming: boolean;\n}\n\nexport interface ConversationMessage {\n\tid: string;\n\trole: \"user\" | \"assistant\" | \"compaction\";\n\ttext: string;\n\ttimestamp?: number;\n}\n\nexport type ConversationEvent =\n\t| { type: \"turn-start\" }\n\t| { type: \"turn-end\"; stopReason: string }\n\t| { type: \"message-added\"; message: ConversationMessage }\n\t| { type: \"message-updated\"; delta: string }\n\t| { type: \"tool-call-start\"; toolCallId: string; toolName: string }\n\t| { type: \"tool-call-end\"; toolCallId: string; toolName: string; isError: boolean }\n\t| { type: \"conversation-changed\"; conversation: ConversationState };\n\nexport interface PluginConversationApi {\n\t/** Send a prompt into the active conversation (renders as a user turn). */\n\tsendPrompt(text: string): Promise<void>;\n\t/** Fill the input bar without sending; the user can edit and send. */\n\tinsertText(text: string): void;\n\t/** Abort the active conversation's current turn. */\n\tabort(): Promise<void>;\n\t/**\n\t * Subscribe to real-time conversation events. The listener is replayed one\n\t * `conversation-changed` with the current state right after subscribing (in a\n\t * microtask), so logic keyed off the active conversation — e.g. deciding\n\t * whether an activity tab belongs in the tab bar for this cwd — runs without\n\t * waiting for the next session switch.\n\t */\n\ton(listener: (event: ConversationEvent) => void): Disposable;\n}\n"]}
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,WAAW,iBAAiB;IACjC,wEAAwE;IACxE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,YAAY,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,iBAAiB,GAC1B;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACjG;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,YAAY,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAErE,MAAM,WAAW,qBAAqB;IACrC,2EAA2E;IAC3E,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,sEAAsE;IACtE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oDAAoD;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;;;OAMG;IACH,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,UAAU,CAAC;CAC7D","sourcesContent":["import type { Disposable } from \"./disposable.js\";\n\nexport interface ConversationState {\n\t/** Active session runtimeId, or null when no conversation is active. */\n\tid: string | null;\n\tcwd: string | null;\n\tsessionPath: string | null;\n\tmodel: string | null;\n\tisStreaming: boolean;\n}\n\nexport interface ConversationMessage {\n\tid: string;\n\trole: \"user\" | \"assistant\" | \"compaction\";\n\ttext: string;\n\ttimestamp?: number;\n}\n\nexport type ConversationEvent =\n\t| { type: \"turn-start\" }\n\t| { type: \"turn-end\"; stopReason: string }\n\t| { type: \"message-added\"; message: ConversationMessage }\n\t| { type: \"message-updated\"; delta: string }\n\t| { type: \"tool-call-start\"; toolCallId: string; toolName: string; args?: Record<string, unknown> }\n\t| { type: \"tool-call-end\"; toolCallId: string; toolName: string; isError: boolean }\n\t| { type: \"conversation-changed\"; conversation: ConversationState };\n\nexport interface PluginConversationApi {\n\t/** Send a prompt into the active conversation (renders as a user turn). */\n\tsendPrompt(text: string): Promise<void>;\n\t/** Fill the input bar without sending; the user can edit and send. */\n\tinsertText(text: string): void;\n\t/** Abort the active conversation's current turn. */\n\tabort(): Promise<void>;\n\t/**\n\t * Subscribe to real-time conversation events. The listener is replayed one\n\t * `conversation-changed` with the current state right after subscribing (in a\n\t * microtask), so logic keyed off the active conversation — e.g. deciding\n\t * whether an activity tab belongs in the tab bar for this cwd — runs without\n\t * waiting for the next session switch.\n\t */\n\ton(listener: (event: ConversationEvent) => void): Disposable;\n}\n"]}

package/dist/conversation.js.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"","sourcesContent":["import type { Disposable } from \"./disposable.js\";\n\nexport interface ConversationState {\n\t/** Active session runtimeId, or null when no conversation is active. */\n\tid: string | null;\n\tcwd: string | null;\n\tsessionPath: string | null;\n\tmodel: string | null;\n\tisStreaming: boolean;\n}\n\nexport interface ConversationMessage {\n\tid: string;\n\trole: \"user\" | \"assistant\" | \"compaction\";\n\ttext: string;\n\ttimestamp?: number;\n}\n\nexport type ConversationEvent =\n\t| { type: \"turn-start\" }\n\t| { type: \"turn-end\"; stopReason: string }\n\t| { type: \"message-added\"; message: ConversationMessage }\n\t| { type: \"message-updated\"; delta: string }\n\t| { type: \"tool-call-start\"; toolCallId: string; toolName: string }\n\t| { type: \"tool-call-end\"; toolCallId: string; toolName: string; isError: boolean }\n\t| { type: \"conversation-changed\"; conversation: ConversationState };\n\nexport interface PluginConversationApi {\n\t/** Send a prompt into the active conversation (renders as a user turn). */\n\tsendPrompt(text: string): Promise<void>;\n\t/** Fill the input bar without sending; the user can edit and send. */\n\tinsertText(text: string): void;\n\t/** Abort the active conversation's current turn. */\n\tabort(): Promise<void>;\n\t/**\n\t * Subscribe to real-time conversation events. The listener is replayed one\n\t * `conversation-changed` with the current state right after subscribing (in a\n\t * microtask), so logic keyed off the active conversation — e.g. deciding\n\t * whether an activity tab belongs in the tab bar for this cwd — runs without\n\t * waiting for the next session switch.\n\t */\n\ton(listener: (event: ConversationEvent) => void): Disposable;\n}\n"]}
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"","sourcesContent":["import type { Disposable } from \"./disposable.js\";\n\nexport interface ConversationState {\n\t/** Active session runtimeId, or null when no conversation is active. */\n\tid: string | null;\n\tcwd: string | null;\n\tsessionPath: string | null;\n\tmodel: string | null;\n\tisStreaming: boolean;\n}\n\nexport interface ConversationMessage {\n\tid: string;\n\trole: \"user\" | \"assistant\" | \"compaction\";\n\ttext: string;\n\ttimestamp?: number;\n}\n\nexport type ConversationEvent =\n\t| { type: \"turn-start\" }\n\t| { type: \"turn-end\"; stopReason: string }\n\t| { type: \"message-added\"; message: ConversationMessage }\n\t| { type: \"message-updated\"; delta: string }\n\t| { type: \"tool-call-start\"; toolCallId: string; toolName: string; args?: Record<string, unknown> }\n\t| { type: \"tool-call-end\"; toolCallId: string; toolName: string; isError: boolean }\n\t| { type: \"conversation-changed\"; conversation: ConversationState };\n\nexport interface PluginConversationApi {\n\t/** Send a prompt into the active conversation (renders as a user turn). */\n\tsendPrompt(text: string): Promise<void>;\n\t/** Fill the input bar without sending; the user can edit and send. */\n\tinsertText(text: string): void;\n\t/** Abort the active conversation's current turn. */\n\tabort(): Promise<void>;\n\t/**\n\t * Subscribe to real-time conversation events. The listener is replayed one\n\t * `conversation-changed` with the current state right after subscribing (in a\n\t * microtask), so logic keyed off the active conversation — e.g. deciding\n\t * whether an activity tab belongs in the tab bar for this cwd — runs without\n\t * waiting for the next session switch.\n\t */\n\ton(listener: (event: ConversationEvent) => void): Disposable;\n}\n"]}

package/dist/file-explorer.d.ts

@@ -0,0 +1,87 @@
+import type { ReactNode } from "react";
+import type { Disposable } from "./disposable.js";
+/** Metadata exposed by the host file explorer. Reading contents still requires `fs.read`. */
+export interface PluginFileExplorerEntry {
+    name: string;
+    path: string;
+    isDirectory: boolean;
+    size: number;
+    modifiedAt: number;
+}
+export interface PluginWorkspaceRoot {
+    name: string;
+    path: string;
+}
+/** Declarative matcher shared by menu actions and decorations. */
+export interface PluginFileExplorerWhen {
+    resourceType?: "file" | "directory";
+    /** Lower-case extensions without a leading dot. Matching is case-insensitive. */
+    extensions?: readonly string[];
+    /** Exact basenames. Matching is case-insensitive. */
+    fileNames?: readonly string[];
+}
+export interface PluginFileExplorerActionContext {
+    entry: PluginFileExplorerEntry;
+    workspaceRoot: PluginWorkspaceRoot | null;
+}
+export interface PluginFileExplorerContextMenuContribution {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    when?: PluginFileExplorerWhen;
+    /** Lower values render first. Defaults to 100. */
+    order?: number;
+    run(context: PluginFileExplorerActionContext): void | Promise<void>;
+}
+export interface PluginFileExplorerToolbarContext {
+    workspaceRoot: PluginWorkspaceRoot;
+    selection: readonly PluginFileExplorerEntry[];
+}
+export interface PluginFileExplorerToolbarContribution {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    /** Lower values render first. Defaults to 100. */
+    order?: number;
+    run(context: PluginFileExplorerToolbarContext): void | Promise<void>;
+}
+export interface PluginFileExplorerDecoration {
+    /** Replaces the host's default file/folder icon. */
+    icon?: ReactNode;
+    /** Compact status text rendered after the filename. Keep to one or two characters. */
+    badge?: string;
+    tooltip?: string;
+}
+export interface PluginFileExplorerDecorationProvider {
+    id: string;
+    when?: PluginFileExplorerWhen;
+    /** Higher values win when multiple providers return a decoration. Defaults to 0. */
+    priority?: number;
+    provideDecoration(entry: PluginFileExplorerEntry): PluginFileExplorerDecoration | null;
+}
+export type PluginFileExplorerChange = {
+    type: "changed" | "created" | "deleted";
+    path: string;
+} | {
+    type: "moved";
+    path: string;
+    oldPath: string;
+};
+export interface PluginFileExplorerRevealOptions {
+    /** Select the revealed entry. Defaults to true. */
+    select?: boolean;
+    /** Move DOM focus to the row after revealing it. Defaults to false. */
+    focus?: boolean;
+}
+export interface PluginFileExplorerApi {
+    getWorkspaceRoots(): readonly PluginWorkspaceRoot[];
+    getSelection(): readonly PluginFileExplorerEntry[];
+    reveal(path: string, options?: PluginFileExplorerRevealOptions): Promise<void>;
+    refresh(path?: string): Promise<void>;
+    onDidChangeSelection(listener: (selection: readonly PluginFileExplorerEntry[]) => void): Disposable;
+    onDidChangeFiles(listener: (changes: readonly PluginFileExplorerChange[]) => void): Disposable;
+    registerContextMenuAction(contribution: PluginFileExplorerContextMenuContribution): Disposable;
+    registerToolbarAction(contribution: PluginFileExplorerToolbarContribution): Disposable;
+    registerDecorationProvider(contribution: PluginFileExplorerDecorationProvider): Disposable;
+}
+//# sourceMappingURL=file-explorer.d.ts.map

package/dist/file-explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-explorer.d.ts","sourceRoot":"","sources":["../src/file-explorer.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ReactNode } from \"react\";\nimport type { Disposable } from \"./disposable.js\";\n\n/** Metadata exposed by the host file explorer. Reading contents still requires `fs.read`. */\nexport interface PluginFileExplorerEntry {\n\tname: string;\n\tpath: string;\n\tisDirectory: boolean;\n\tsize: number;\n\tmodifiedAt: number;\n}\n\nexport interface PluginWorkspaceRoot {\n\tname: string;\n\tpath: string;\n}\n\n/** Declarative matcher shared by menu actions and decorations. */\nexport interface PluginFileExplorerWhen {\n\tresourceType?: \"file\" | \"directory\";\n\t/** Lower-case extensions without a leading dot. Matching is case-insensitive. */\n\textensions?: readonly string[];\n\t/** Exact basenames. Matching is case-insensitive. */\n\tfileNames?: readonly string[];\n}\n\nexport interface PluginFileExplorerActionContext {\n\tentry: PluginFileExplorerEntry;\n\tworkspaceRoot: PluginWorkspaceRoot | null;\n}\n\nexport interface PluginFileExplorerContextMenuContribution {\n\tid: string;\n\tlabel: string;\n\ticon?: ReactNode;\n\twhen?: PluginFileExplorerWhen;\n\t/** Lower values render first. Defaults to 100. */\n\torder?: number;\n\trun(context: PluginFileExplorerActionContext): void | Promise<void>;\n}\n\nexport interface PluginFileExplorerToolbarContext {\n\tworkspaceRoot: PluginWorkspaceRoot;\n\tselection: readonly PluginFileExplorerEntry[];\n}\n\nexport interface PluginFileExplorerToolbarContribution {\n\tid: string;\n\tlabel: string;\n\ticon?: ReactNode;\n\t/** Lower values render first. Defaults to 100. */\n\torder?: number;\n\trun(context: PluginFileExplorerToolbarContext): void | Promise<void>;\n}\n\nexport interface PluginFileExplorerDecoration {\n\t/** Replaces the host's default file/folder icon. */\n\ticon?: ReactNode;\n\t/** Compact status text rendered after the filename. Keep to one or two characters. */\n\tbadge?: string;\n\ttooltip?: string;\n}\n\nexport interface PluginFileExplorerDecorationProvider {\n\tid: string;\n\twhen?: PluginFileExplorerWhen;\n\t/** Higher values win when multiple providers return a decoration. Defaults to 0. */\n\tpriority?: number;\n\tprovideDecoration(\n\t\tentry: PluginFileExplorerEntry,\n\t): PluginFileExplorerDecoration | null;\n}\n\nexport type PluginFileExplorerChange =\n\t| { type: \"changed\" | \"created\" | \"deleted\"; path: string }\n\t| { type: \"moved\"; path: string; oldPath: string };\n\nexport interface PluginFileExplorerRevealOptions {\n\t/** Select the revealed entry. Defaults to true. */\n\tselect?: boolean;\n\t/** Move DOM focus to the row after revealing it. Defaults to false. */\n\tfocus?: boolean;\n}\n\nexport interface PluginFileExplorerApi {\n\tgetWorkspaceRoots(): readonly PluginWorkspaceRoot[];\n\tgetSelection(): readonly PluginFileExplorerEntry[];\n\treveal(path: string, options?: PluginFileExplorerRevealOptions): Promise<void>;\n\trefresh(path?: string): Promise<void>;\n\tonDidChangeSelection(listener: (selection: readonly PluginFileExplorerEntry[]) => void): Disposable;\n\tonDidChangeFiles(listener: (changes: readonly PluginFileExplorerChange[]) => void): Disposable;\n\tregisterContextMenuAction(contribution: PluginFileExplorerContextMenuContribution): Disposable;\n\tregisterToolbarAction(contribution: PluginFileExplorerToolbarContribution): Disposable;\n\tregisterDecorationProvider(contribution: PluginFileExplorerDecorationProvider): Disposable;\n}\n"]}

package/dist/file-explorer.js

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

package/dist/file-explorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-explorer.js","sourceRoot":"","sources":["../src/file-explorer.ts"],"names":[],"mappings":"","sourcesContent":["import type { ReactNode } from \"react\";\nimport type { Disposable } from \"./disposable.js\";\n\n/** Metadata exposed by the host file explorer. Reading contents still requires `fs.read`. */\nexport interface PluginFileExplorerEntry {\n\tname: string;\n\tpath: string;\n\tisDirectory: boolean;\n\tsize: number;\n\tmodifiedAt: number;\n}\n\nexport interface PluginWorkspaceRoot {\n\tname: string;\n\tpath: string;\n}\n\n/** Declarative matcher shared by menu actions and decorations. */\nexport interface PluginFileExplorerWhen {\n\tresourceType?: \"file\" | \"directory\";\n\t/** Lower-case extensions without a leading dot. Matching is case-insensitive. */\n\textensions?: readonly string[];\n\t/** Exact basenames. Matching is case-insensitive. */\n\tfileNames?: readonly string[];\n}\n\nexport interface PluginFileExplorerActionContext {\n\tentry: PluginFileExplorerEntry;\n\tworkspaceRoot: PluginWorkspaceRoot | null;\n}\n\nexport interface PluginFileExplorerContextMenuContribution {\n\tid: string;\n\tlabel: string;\n\ticon?: ReactNode;\n\twhen?: PluginFileExplorerWhen;\n\t/** Lower values render first. Defaults to 100. */\n\torder?: number;\n\trun(context: PluginFileExplorerActionContext): void | Promise<void>;\n}\n\nexport interface PluginFileExplorerToolbarContext {\n\tworkspaceRoot: PluginWorkspaceRoot;\n\tselection: readonly PluginFileExplorerEntry[];\n}\n\nexport interface PluginFileExplorerToolbarContribution {\n\tid: string;\n\tlabel: string;\n\ticon?: ReactNode;\n\t/** Lower values render first. Defaults to 100. */\n\torder?: number;\n\trun(context: PluginFileExplorerToolbarContext): void | Promise<void>;\n}\n\nexport interface PluginFileExplorerDecoration {\n\t/** Replaces the host's default file/folder icon. */\n\ticon?: ReactNode;\n\t/** Compact status text rendered after the filename. Keep to one or two characters. */\n\tbadge?: string;\n\ttooltip?: string;\n}\n\nexport interface PluginFileExplorerDecorationProvider {\n\tid: string;\n\twhen?: PluginFileExplorerWhen;\n\t/** Higher values win when multiple providers return a decoration. Defaults to 0. */\n\tpriority?: number;\n\tprovideDecoration(\n\t\tentry: PluginFileExplorerEntry,\n\t): PluginFileExplorerDecoration | null;\n}\n\nexport type PluginFileExplorerChange =\n\t| { type: \"changed\" | \"created\" | \"deleted\"; path: string }\n\t| { type: \"moved\"; path: string; oldPath: string };\n\nexport interface PluginFileExplorerRevealOptions {\n\t/** Select the revealed entry. Defaults to true. */\n\tselect?: boolean;\n\t/** Move DOM focus to the row after revealing it. Defaults to false. */\n\tfocus?: boolean;\n}\n\nexport interface PluginFileExplorerApi {\n\tgetWorkspaceRoots(): readonly PluginWorkspaceRoot[];\n\tgetSelection(): readonly PluginFileExplorerEntry[];\n\treveal(path: string, options?: PluginFileExplorerRevealOptions): Promise<void>;\n\trefresh(path?: string): Promise<void>;\n\tonDidChangeSelection(listener: (selection: readonly PluginFileExplorerEntry[]) => void): Disposable;\n\tonDidChangeFiles(listener: (changes: readonly PluginFileExplorerChange[]) => void): Disposable;\n\tregisterContextMenuAction(contribution: PluginFileExplorerContextMenuContribution): Disposable;\n\tregisterToolbarAction(contribution: PluginFileExplorerToolbarContribution): Disposable;\n\tregisterDecorationProvider(contribution: PluginFileExplorerDecorationProvider): Disposable;\n}\n"]}

package/dist/fs.d.ts

@@ -24,6 +24,14 @@ export interface PluginFsBinaryReadResult {
     mimeType: string;
     size: number;
 }
+export interface PluginFsSaveAsOptions {
+    title?: string;
+    /** Defaults to a single filter derived from the default file name's extension. */
+    filters?: Array<{
+        name: string;
+        extensions: string[];
+    }>;
+}
 export interface PluginFsApi {
     readDir(dirPath: string): Promise<PluginFsEntry[]>;
     readFile(filePath: string): Promise<PluginFsReadResult>;
@@ -36,6 +44,14 @@ export interface PluginFsApi {
     move(sourcePath: string, destDir: string): Promise<void>;
     createDirectory(dirPath: string): Promise<void>;
     listFilesRecursive(rootPath: string): Promise<PluginFsFileRef[]>;
+    /**
+     * Write bytes to a path the user picks in the host's native save dialog.
+     * Unlike {@link writeFile} the destination is not restricted to project
+     * roots — the user chooses it, so nothing lands on disk without an explicit
+     * confirmation. Resolves to the saved path, or `null` if the user cancels.
+     * Requires `fs.write`.
+     */
+    saveAs(defaultFileName: string, content: string, encoding?: "utf8" | "base64", options?: PluginFsSaveAsOptions): Promise<string | null>;
     /** Watch one directory for host-debounced changes. Requires `fs.read`. */
     watchDirectory(dirPath: string, listener: (changedPath: string) => void): Disposable;
 }

package/dist/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC3B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACxD,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACpE,qFAAqF;IACrF,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAC3D,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IACjE,0EAA0E;IAC1E,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,GAAG,UAAU,CAAC;CACrF;AACD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC","sourcesContent":["export interface PluginFsEntry {\n\tname: string;\n\tpath: string;\n\tisDirectory: boolean;\n\tsize: number;\n\tmodifiedAt: number;\n}\n\nexport interface PluginFsFileRef {\n\tname: string;\n\tpath: string;\n\trelPath: string;\n}\n\nexport interface PluginFsStatResult {\n\tsize: number;\n\tmodifiedAt: number;\n\tcreatedAt: number;\n}\n\nexport interface PluginFsReadResult {\n\tcontent: string;\n\tencoding: \"utf8\" | \"base64\";\n}\n\nexport interface PluginFsBinaryReadResult {\n\tdata: string;\n\tmimeType: string;\n\tsize: number;\n}\n\nexport interface PluginFsApi {\n\treadDir(dirPath: string): Promise<PluginFsEntry[]>;\n\treadFile(filePath: string): Promise<PluginFsReadResult>;\n\treadBinaryFile(filePath: string): Promise<PluginFsBinaryReadResult>;\n\t/** Pass `encoding: \"base64\"` to write binary payloads (decoded from base64 text). */\n\twriteFile(filePath: string, content: string, encoding?: \"utf8\" | \"base64\"): Promise<void>;\n\tstat(filePath: string): Promise<PluginFsStatResult | null>;\n\trename(oldPath: string, newPath: string): Promise<void>;\n\tdelete(targetPath: string): Promise<void>;\n\tmove(sourcePath: string, destDir: string): Promise<void>;\n\tcreateDirectory(dirPath: string): Promise<void>;\n\tlistFilesRecursive(rootPath: string): Promise<PluginFsFileRef[]>;\n\t/** Watch one directory for host-debounced changes. Requires `fs.read`. */\n\twatchDirectory(dirPath: string, listener: (changedPath: string) => void): Disposable;\n}\nimport type { Disposable } from \"./disposable.js\";\n"]}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,qBAAqB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,WAAW;IAC3B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACxD,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACpE,qFAAqF;IACrF,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAC3D,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IACjE;;;;;;OAMG;IACH,MAAM,CACL,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,EAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1B,0EAA0E;IAC1E,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,GAAG,UAAU,CAAC;CACrF;AACD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC","sourcesContent":["export interface PluginFsEntry {\n\tname: string;\n\tpath: string;\n\tisDirectory: boolean;\n\tsize: number;\n\tmodifiedAt: number;\n}\n\nexport interface PluginFsFileRef {\n\tname: string;\n\tpath: string;\n\trelPath: string;\n}\n\nexport interface PluginFsStatResult {\n\tsize: number;\n\tmodifiedAt: number;\n\tcreatedAt: number;\n}\n\nexport interface PluginFsReadResult {\n\tcontent: string;\n\tencoding: \"utf8\" | \"base64\";\n}\n\nexport interface PluginFsBinaryReadResult {\n\tdata: string;\n\tmimeType: string;\n\tsize: number;\n}\n\nexport interface PluginFsSaveAsOptions {\n\ttitle?: string;\n\t/** Defaults to a single filter derived from the default file name's extension. */\n\tfilters?: Array<{ name: string; extensions: string[] }>;\n}\n\nexport interface PluginFsApi {\n\treadDir(dirPath: string): Promise<PluginFsEntry[]>;\n\treadFile(filePath: string): Promise<PluginFsReadResult>;\n\treadBinaryFile(filePath: string): Promise<PluginFsBinaryReadResult>;\n\t/** Pass `encoding: \"base64\"` to write binary payloads (decoded from base64 text). */\n\twriteFile(filePath: string, content: string, encoding?: \"utf8\" | \"base64\"): Promise<void>;\n\tstat(filePath: string): Promise<PluginFsStatResult | null>;\n\trename(oldPath: string, newPath: string): Promise<void>;\n\tdelete(targetPath: string): Promise<void>;\n\tmove(sourcePath: string, destDir: string): Promise<void>;\n\tcreateDirectory(dirPath: string): Promise<void>;\n\tlistFilesRecursive(rootPath: string): Promise<PluginFsFileRef[]>;\n\t/**\n\t * Write bytes to a path the user picks in the host's native save dialog.\n\t * Unlike {@link writeFile} the destination is not restricted to project\n\t * roots — the user chooses it, so nothing lands on disk without an explicit\n\t * confirmation. Resolves to the saved path, or `null` if the user cancels.\n\t * Requires `fs.write`.\n\t */\n\tsaveAs(\n\t\tdefaultFileName: string,\n\t\tcontent: string,\n\t\tencoding?: \"utf8\" | \"base64\",\n\t\toptions?: PluginFsSaveAsOptions,\n\t): Promise<string | null>;\n\t/** Watch one directory for host-debounced changes. Requires `fs.read`. */\n\twatchDirectory(dirPath: string, listener: (changedPath: string) => void): Disposable;\n}\nimport type { Disposable } from \"./disposable.js\";\n"]}

package/dist/fs.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"","sourcesContent":["export interface PluginFsEntry {\n\tname: string;\n\tpath: string;\n\tisDirectory: boolean;\n\tsize: number;\n\tmodifiedAt: number;\n}\n\nexport interface PluginFsFileRef {\n\tname: string;\n\tpath: string;\n\trelPath: string;\n}\n\nexport interface PluginFsStatResult {\n\tsize: number;\n\tmodifiedAt: number;\n\tcreatedAt: number;\n}\n\nexport interface PluginFsReadResult {\n\tcontent: string;\n\tencoding: \"utf8\" | \"base64\";\n}\n\nexport interface PluginFsBinaryReadResult {\n\tdata: string;\n\tmimeType: string;\n\tsize: number;\n}\n\nexport interface PluginFsApi {\n\treadDir(dirPath: string): Promise<PluginFsEntry[]>;\n\treadFile(filePath: string): Promise<PluginFsReadResult>;\n\treadBinaryFile(filePath: string): Promise<PluginFsBinaryReadResult>;\n\t/** Pass `encoding: \"base64\"` to write binary payloads (decoded from base64 text). */\n\twriteFile(filePath: string, content: string, encoding?: \"utf8\" | \"base64\"): Promise<void>;\n\tstat(filePath: string): Promise<PluginFsStatResult | null>;\n\trename(oldPath: string, newPath: string): Promise<void>;\n\tdelete(targetPath: string): Promise<void>;\n\tmove(sourcePath: string, destDir: string): Promise<void>;\n\tcreateDirectory(dirPath: string): Promise<void>;\n\tlistFilesRecursive(rootPath: string): Promise<PluginFsFileRef[]>;\n\t/** Watch one directory for host-debounced changes. Requires `fs.read`. */\n\twatchDirectory(dirPath: string, listener: (changedPath: string) => void): Disposable;\n}\nimport type { Disposable } from \"./disposable.js\";\n"]}
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"","sourcesContent":["export interface PluginFsEntry {\n\tname: string;\n\tpath: string;\n\tisDirectory: boolean;\n\tsize: number;\n\tmodifiedAt: number;\n}\n\nexport interface PluginFsFileRef {\n\tname: string;\n\tpath: string;\n\trelPath: string;\n}\n\nexport interface PluginFsStatResult {\n\tsize: number;\n\tmodifiedAt: number;\n\tcreatedAt: number;\n}\n\nexport interface PluginFsReadResult {\n\tcontent: string;\n\tencoding: \"utf8\" | \"base64\";\n}\n\nexport interface PluginFsBinaryReadResult {\n\tdata: string;\n\tmimeType: string;\n\tsize: number;\n}\n\nexport interface PluginFsSaveAsOptions {\n\ttitle?: string;\n\t/** Defaults to a single filter derived from the default file name's extension. */\n\tfilters?: Array<{ name: string; extensions: string[] }>;\n}\n\nexport interface PluginFsApi {\n\treadDir(dirPath: string): Promise<PluginFsEntry[]>;\n\treadFile(filePath: string): Promise<PluginFsReadResult>;\n\treadBinaryFile(filePath: string): Promise<PluginFsBinaryReadResult>;\n\t/** Pass `encoding: \"base64\"` to write binary payloads (decoded from base64 text). */\n\twriteFile(filePath: string, content: string, encoding?: \"utf8\" | \"base64\"): Promise<void>;\n\tstat(filePath: string): Promise<PluginFsStatResult | null>;\n\trename(oldPath: string, newPath: string): Promise<void>;\n\tdelete(targetPath: string): Promise<void>;\n\tmove(sourcePath: string, destDir: string): Promise<void>;\n\tcreateDirectory(dirPath: string): Promise<void>;\n\tlistFilesRecursive(rootPath: string): Promise<PluginFsFileRef[]>;\n\t/**\n\t * Write bytes to a path the user picks in the host's native save dialog.\n\t * Unlike {@link writeFile} the destination is not restricted to project\n\t * roots — the user chooses it, so nothing lands on disk without an explicit\n\t * confirmation. Resolves to the saved path, or `null` if the user cancels.\n\t * Requires `fs.write`.\n\t */\n\tsaveAs(\n\t\tdefaultFileName: string,\n\t\tcontent: string,\n\t\tencoding?: \"utf8\" | \"base64\",\n\t\toptions?: PluginFsSaveAsOptions,\n\t): Promise<string | null>;\n\t/** Watch one directory for host-debounced changes. Requires `fs.read`. */\n\twatchDirectory(dirPath: string, listener: (changedPath: string) => void): Disposable;\n}\nimport type { Disposable } from \"./disposable.js\";\n"]}

package/dist/index.d.ts

@@ -9,14 +9,17 @@ export type { ConversationScenario } from "./scenario.js";
 export type { PluginPermission } from "./permissions.js";
 export type { Disposable } from "./disposable.js";
 export type { PluginMcpServerConfig, PluginAgentManifest } from "./manifest.js";
+export type { PluginFileExplorerEntry, PluginWorkspaceRoot, PluginFileExplorerWhen, PluginFileExplorerActionContext, PluginFileExplorerContextMenuContribution, PluginFileExplorerToolbarContext, PluginFileExplorerToolbarContribution, PluginFileExplorerDecoration, PluginFileExplorerDecorationProvider, PluginFileExplorerChange, PluginFileExplorerRevealOptions, PluginFileExplorerApi, } from "./file-explorer.js";
 export type { ConversationState, ConversationMessage, ConversationEvent, PluginConversationApi, } from "./conversation.js";
 export type { PluginGlobalSlotContribution, PluginAudioMetadata, PluginPreviewUrlOptions, PluginPreviewFile, PluginFilePreviewProps, PluginFilePreviewContribution, PluginActivityTabContribution, PluginCaptureRegion, PluginOpenActivityTabOptions, PluginPromptDecoration, PluginInputActionContribution, CardDescriptor, PluginPendingToolCall, PluginCardProps, PluginCardRendererContribution, PluginToolCallSlotToolCall, PluginToolCallSlotProps, PluginToolCallSlotContribution, PluginTurnCardContribution, PluginNotifyOptions, PluginUiApi, } from "./ui.js";
+export type { PluginShortcutScopeKind, PluginShortcutWhen, PluginShortcutBinding, PluginShortcutScopeContribution, PluginRegisterShortcutScope, UsePluginShortcutScopeOptions, } from "./shortcuts.js";
+export { usePluginShortcutScope } from "./shortcuts.js";
 export type { PluginJsonSchema, PluginAgentToolApi, PluginAgentToolRegistration, PluginSystemPromptBlock, PluginDynamicSystemPromptOperation, PluginSystemPromptMessage, PluginSystemPromptProviderContext, PluginSystemPromptBlockView, PluginAgentActions, PluginAgentHandlerContext, PluginAgentToolHandler, PluginSystemPromptProviderHandler, PluginSystemPromptProviderRegistration, PluginContinuationResult, PluginContinuationHandler, PluginContinuationRegistration, PluginAgentApi, } from "./agent.js";
 export type { PluginAppActionEffect, PluginAppActionExample, PluginAppActionHandlerContext, PluginAppActionHandler, PluginAppActionReadyHandler, PluginAppActionApprovalPresentation, PluginAppActionApproval, PluginAppActionRegistration, PluginAppActionsApi, } from "./app-actions.js";
 export { PluginAppActionError } from "./app-actions.js";
 export type { PluginOfficialGeneralSettings, PluginOfficialGeneralSettingsUpdate, PluginOfficialExperimentalSettings, PluginOfficialDownloadItem, PluginOfficialUpdaterState, PluginOfficialWebhookKind, PluginOfficialWebhookEndpoint, PluginOfficialWebhookProvider, PluginOfficialWebhookCreateInput, PluginOfficialWebhookUpdateInput, PluginOfficialWebhookMessage, PluginOfficialWebhookSendResult, PluginOfficialSkillInfo, PluginOfficialInstalledSkill, PluginOfficialShortcutBinding, PluginOfficialQuickPanelSettings, PluginOfficialImStatus, PluginOfficialImLog, PluginOfficialMcpServerSummary, PluginOfficialMcpServerDetail, PluginOfficialMcpUpsertData, PluginOfficialExecutionMode, PluginOfficialSelectedSkill, PluginOfficialBatchProjectCreateData, PluginOfficialBatchProjectUpdateData, PluginOfficialSchedulerTaskCreateData, PluginOfficialSchedulerTaskUpdateData, PluginOfficialModelSummary, PluginOfficialProviderSummary, PluginOfficialProviderDetail, PluginOfficialProviderUpsertData, PluginOfficialProjectEntry, PluginOfficialPluginSummary, PluginOfficialKnowledgeBase, PluginOfficialKnowledgeProcessingSettings, PluginOfficialApi, } from "./official.js";
 export type { PluginFsEntry, PluginFsFileRef, PluginFsBinaryReadResult, PluginFsStatResult, PluginFsReadResult, PluginFsApi, } from "./fs.js";
-export type { PluginCommandRunOptions, PluginCommandRunResult, PluginCommandApi, } from "./command.js";
+export type { PluginCommandRunOptions, PluginCommandRunResult, PluginCommandSpawnOptions, PluginCommandSpawnExit, PluginCommandSpawnStatus, PluginCommandSpawnHandle, PluginCommandApi, } from "./command.js";
 export type { PluginImageRef } from "./images.js";
 export type { PluginPromptAttachment } from "./prompt-attachment.js";
 export type { PluginNetworkApi, PluginNetworkBody, PluginNetworkRequest, PluginNetworkResponse, } from "./network.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @vetta-org/plugin-sdk public surface.\n *\n * Implementation is split by domain under `src/*.ts`; this barrel re-exports\n * the stable package API. Prefer importing from `@vetta-org/plugin-sdk` rather\n * than deep paths.\n */\n\n// Core primitives\nexport type { ConversationScenario } from \"./scenario.js\";\nexport type { PluginPermission } from \"./permissions.js\";\nexport type { Disposable } from \"./disposable.js\";\nexport type { PluginMcpServerConfig, PluginAgentManifest } from \"./manifest.js\";\n\n// Conversation\nexport type {\n\tConversationState,\n\tConversationMessage,\n\tConversationEvent,\n\tPluginConversationApi,\n} from \"./conversation.js\";\n\n// UI slots\nexport type {\n\tPluginGlobalSlotContribution,\n\tPluginAudioMetadata,\n\tPluginPreviewUrlOptions,\n\tPluginPreviewFile,\n\tPluginFilePreviewProps,\n\tPluginFilePreviewContribution,\n\tPluginActivityTabContribution,\n\tPluginCaptureRegion,\n\tPluginOpenActivityTabOptions,\n\tPluginPromptDecoration,\n\tPluginInputActionContribution,\n\tCardDescriptor,\n\tPluginPendingToolCall,\n\tPluginCardProps,\n\tPluginCardRendererContribution,\n\tPluginToolCallSlotToolCall,\n\tPluginToolCallSlotProps,\n\tPluginToolCallSlotContribution,\n\tPluginTurnCardContribution,\n\tPluginNotifyOptions,\n\tPluginUiApi,\n} from \"./ui.js\";\n\n// Agent runtime\nexport type {\n\tPluginJsonSchema,\n\tPluginAgentToolApi,\n\tPluginAgentToolRegistration,\n\tPluginSystemPromptBlock,\n\tPluginDynamicSystemPromptOperation,\n\tPluginSystemPromptMessage,\n\tPluginSystemPromptProviderContext,\n\tPluginSystemPromptBlockView,\n\tPluginAgentActions,\n\tPluginAgentHandlerContext,\n\tPluginAgentToolHandler,\n\tPluginSystemPromptProviderHandler,\n\tPluginSystemPromptProviderRegistration,\n\tPluginContinuationResult,\n\tPluginContinuationHandler,\n\tPluginContinuationRegistration,\n\tPluginAgentApi,\n} from \"./agent.js\";\n\n// App actions\nexport type {\n\tPluginAppActionEffect,\n\tPluginAppActionExample,\n\tPluginAppActionHandlerContext,\n\tPluginAppActionHandler,\n\tPluginAppActionReadyHandler,\n\tPluginAppActionApprovalPresentation,\n\tPluginAppActionApproval,\n\tPluginAppActionRegistration,\n\tPluginAppActionsApi,\n} from \"./app-actions.js\";\nexport { PluginAppActionError } from \"./app-actions.js\";\n\n// Official host capabilities\nexport type {\n\tPluginOfficialGeneralSettings,\n\tPluginOfficialGeneralSettingsUpdate,\n\tPluginOfficialExperimentalSettings,\n\tPluginOfficialDownloadItem,\n\tPluginOfficialUpdaterState,\n\tPluginOfficialWebhookKind,\n\tPluginOfficialWebhookEndpoint,\n\tPluginOfficialWebhookProvider,\n\tPluginOfficialWebhookCreateInput,\n\tPluginOfficialWebhookUpdateInput,\n\tPluginOfficialWebhookMessage,\n\tPluginOfficialWebhookSendResult,\n\tPluginOfficialSkillInfo,\n\tPluginOfficialInstalledSkill,\n\tPluginOfficialShortcutBinding,\n\tPluginOfficialQuickPanelSettings,\n\tPluginOfficialImStatus,\n\tPluginOfficialImLog,\n\tPluginOfficialMcpServerSummary,\n\tPluginOfficialMcpServerDetail,\n\tPluginOfficialMcpUpsertData,\n\tPluginOfficialExecutionMode,\n\tPluginOfficialSelectedSkill,\n\tPluginOfficialBatchProjectCreateData,\n\tPluginOfficialBatchProjectUpdateData,\n\tPluginOfficialSchedulerTaskCreateData,\n\tPluginOfficialSchedulerTaskUpdateData,\n\tPluginOfficialModelSummary,\n\tPluginOfficialProviderSummary,\n\tPluginOfficialProviderDetail,\n\tPluginOfficialProviderUpsertData,\n\tPluginOfficialProjectEntry,\n\tPluginOfficialPluginSummary,\n\tPluginOfficialKnowledgeBase,\n\tPluginOfficialKnowledgeProcessingSettings,\n\tPluginOfficialApi,\n} from \"./official.js\";\n\n// Files / command / images / settings\nexport type {\n\tPluginFsEntry,\n\tPluginFsFileRef,\n\tPluginFsBinaryReadResult,\n\tPluginFsStatResult,\n\tPluginFsReadResult,\n\tPluginFsApi,\n} from \"./fs.js\";\nexport type {\n\tPluginCommandRunOptions,\n\tPluginCommandRunResult,\n\tPluginCommandApi,\n} from \"./command.js\";\nexport type { PluginImageRef } from \"./images.js\";\nexport type { PluginPromptAttachment } from \"./prompt-attachment.js\";\nexport type {\n\tPluginNetworkApi,\n\tPluginNetworkBody,\n\tPluginNetworkRequest,\n\tPluginNetworkResponse,\n} from \"./network.js\";\nexport type {\n\tPluginPutBlobInput,\n\tPluginStorageApi,\n\tPluginStoredBlob,\n\tPluginStoredBlobRef,\n} from \"./storage.js\";\nexport type { PluginSettingsApi } from \"./settings.js\";\n\n// i18n\nexport type {\n\tPluginLocaleCatalog,\n\tPluginLocales,\n\tPluginTranslate,\n\tPluginI18nApi,\n} from \"./i18n.js\";\nexport { interpolatePluginText, resolveCatalogKey, resolvePluginText } from \"./i18n.js\";\n\n// Context & lifecycle\nexport type { PluginPermissionApi, AgentMode, PluginContext, PluginDefinition } from \"./context.js\";\nexport { definePlugin } from \"./context.js\";\n\n// Host bridge (host-injected; plugins use hooks)\nexport type { PluginHostBridge } from \"./host-bridge.js\";\nexport { __setPluginHostBridge } from \"./host-bridge.js\";\n\n// Activity tab context\nexport type { ActivityTabContextValue } from \"./activity-tab.js\";\nexport { __ActivityTabContext, useActivityTab } from \"./activity-tab.js\";\n\n// React hooks\nexport type { PluginI18nContextValue, PluginTranslation } from \"./hooks.js\";\nexport {\n\t__PluginI18nContext,\n\tuseTranslation,\n\tuseActiveConversation,\n\tuseConversationMessages,\n\tusePromptAttachment,\n} from \"./hooks.js\";\n"]}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @vetta-org/plugin-sdk public surface.\n *\n * Implementation is split by domain under `src/*.ts`; this barrel re-exports\n * the stable package API. Prefer importing from `@vetta-org/plugin-sdk` rather\n * than deep paths.\n */\n\n// Core primitives\nexport type { ConversationScenario } from \"./scenario.js\";\nexport type { PluginPermission } from \"./permissions.js\";\nexport type { Disposable } from \"./disposable.js\";\nexport type { PluginMcpServerConfig, PluginAgentManifest } from \"./manifest.js\";\n\n// File explorer\nexport type {\n\tPluginFileExplorerEntry,\n\tPluginWorkspaceRoot,\n\tPluginFileExplorerWhen,\n\tPluginFileExplorerActionContext,\n\tPluginFileExplorerContextMenuContribution,\n\tPluginFileExplorerToolbarContext,\n\tPluginFileExplorerToolbarContribution,\n\tPluginFileExplorerDecoration,\n\tPluginFileExplorerDecorationProvider,\n\tPluginFileExplorerChange,\n\tPluginFileExplorerRevealOptions,\n\tPluginFileExplorerApi,\n} from \"./file-explorer.js\";\n\n// Conversation\nexport type {\n\tConversationState,\n\tConversationMessage,\n\tConversationEvent,\n\tPluginConversationApi,\n} from \"./conversation.js\";\n\n// UI slots\nexport type {\n\tPluginGlobalSlotContribution,\n\tPluginAudioMetadata,\n\tPluginPreviewUrlOptions,\n\tPluginPreviewFile,\n\tPluginFilePreviewProps,\n\tPluginFilePreviewContribution,\n\tPluginActivityTabContribution,\n\tPluginCaptureRegion,\n\tPluginOpenActivityTabOptions,\n\tPluginPromptDecoration,\n\tPluginInputActionContribution,\n\tCardDescriptor,\n\tPluginPendingToolCall,\n\tPluginCardProps,\n\tPluginCardRendererContribution,\n\tPluginToolCallSlotToolCall,\n\tPluginToolCallSlotProps,\n\tPluginToolCallSlotContribution,\n\tPluginTurnCardContribution,\n\tPluginNotifyOptions,\n\tPluginUiApi,\n} from \"./ui.js\";\n\n// Keyboard shortcuts (host ShortcutScopeStack)\nexport type {\n\tPluginShortcutScopeKind,\n\tPluginShortcutWhen,\n\tPluginShortcutBinding,\n\tPluginShortcutScopeContribution,\n\tPluginRegisterShortcutScope,\n\tUsePluginShortcutScopeOptions,\n} from \"./shortcuts.js\";\nexport { usePluginShortcutScope } from \"./shortcuts.js\";\n\n// Agent runtime\nexport type {\n\tPluginJsonSchema,\n\tPluginAgentToolApi,\n\tPluginAgentToolRegistration,\n\tPluginSystemPromptBlock,\n\tPluginDynamicSystemPromptOperation,\n\tPluginSystemPromptMessage,\n\tPluginSystemPromptProviderContext,\n\tPluginSystemPromptBlockView,\n\tPluginAgentActions,\n\tPluginAgentHandlerContext,\n\tPluginAgentToolHandler,\n\tPluginSystemPromptProviderHandler,\n\tPluginSystemPromptProviderRegistration,\n\tPluginContinuationResult,\n\tPluginContinuationHandler,\n\tPluginContinuationRegistration,\n\tPluginAgentApi,\n} from \"./agent.js\";\n\n// App actions\nexport type {\n\tPluginAppActionEffect,\n\tPluginAppActionExample,\n\tPluginAppActionHandlerContext,\n\tPluginAppActionHandler,\n\tPluginAppActionReadyHandler,\n\tPluginAppActionApprovalPresentation,\n\tPluginAppActionApproval,\n\tPluginAppActionRegistration,\n\tPluginAppActionsApi,\n} from \"./app-actions.js\";\nexport { PluginAppActionError } from \"./app-actions.js\";\n\n// Official host capabilities\nexport type {\n\tPluginOfficialGeneralSettings,\n\tPluginOfficialGeneralSettingsUpdate,\n\tPluginOfficialExperimentalSettings,\n\tPluginOfficialDownloadItem,\n\tPluginOfficialUpdaterState,\n\tPluginOfficialWebhookKind,\n\tPluginOfficialWebhookEndpoint,\n\tPluginOfficialWebhookProvider,\n\tPluginOfficialWebhookCreateInput,\n\tPluginOfficialWebhookUpdateInput,\n\tPluginOfficialWebhookMessage,\n\tPluginOfficialWebhookSendResult,\n\tPluginOfficialSkillInfo,\n\tPluginOfficialInstalledSkill,\n\tPluginOfficialShortcutBinding,\n\tPluginOfficialQuickPanelSettings,\n\tPluginOfficialImStatus,\n\tPluginOfficialImLog,\n\tPluginOfficialMcpServerSummary,\n\tPluginOfficialMcpServerDetail,\n\tPluginOfficialMcpUpsertData,\n\tPluginOfficialExecutionMode,\n\tPluginOfficialSelectedSkill,\n\tPluginOfficialBatchProjectCreateData,\n\tPluginOfficialBatchProjectUpdateData,\n\tPluginOfficialSchedulerTaskCreateData,\n\tPluginOfficialSchedulerTaskUpdateData,\n\tPluginOfficialModelSummary,\n\tPluginOfficialProviderSummary,\n\tPluginOfficialProviderDetail,\n\tPluginOfficialProviderUpsertData,\n\tPluginOfficialProjectEntry,\n\tPluginOfficialPluginSummary,\n\tPluginOfficialKnowledgeBase,\n\tPluginOfficialKnowledgeProcessingSettings,\n\tPluginOfficialApi,\n} from \"./official.js\";\n\n// Files / command / images / settings\nexport type {\n\tPluginFsEntry,\n\tPluginFsFileRef,\n\tPluginFsBinaryReadResult,\n\tPluginFsStatResult,\n\tPluginFsReadResult,\n\tPluginFsApi,\n} from \"./fs.js\";\nexport type {\n\tPluginCommandRunOptions,\n\tPluginCommandRunResult,\n\tPluginCommandSpawnOptions,\n\tPluginCommandSpawnExit,\n\tPluginCommandSpawnStatus,\n\tPluginCommandSpawnHandle,\n\tPluginCommandApi,\n} from \"./command.js\";\nexport type { PluginImageRef } from \"./images.js\";\nexport type { PluginPromptAttachment } from \"./prompt-attachment.js\";\nexport type {\n\tPluginNetworkApi,\n\tPluginNetworkBody,\n\tPluginNetworkRequest,\n\tPluginNetworkResponse,\n} from \"./network.js\";\nexport type {\n\tPluginPutBlobInput,\n\tPluginStorageApi,\n\tPluginStoredBlob,\n\tPluginStoredBlobRef,\n} from \"./storage.js\";\nexport type { PluginSettingsApi } from \"./settings.js\";\n\n// i18n\nexport type {\n\tPluginLocaleCatalog,\n\tPluginLocales,\n\tPluginTranslate,\n\tPluginI18nApi,\n} from \"./i18n.js\";\nexport { interpolatePluginText, resolveCatalogKey, resolvePluginText } from \"./i18n.js\";\n\n// Context & lifecycle\nexport type { PluginPermissionApi, AgentMode, PluginContext, PluginDefinition } from \"./context.js\";\nexport { definePlugin } from \"./context.js\";\n\n// Host bridge (host-injected; plugins use hooks)\nexport type { PluginHostBridge } from \"./host-bridge.js\";\nexport { __setPluginHostBridge } from \"./host-bridge.js\";\n\n// Activity tab context\nexport type { ActivityTabContextValue } from \"./activity-tab.js\";\nexport { __ActivityTabContext, useActivityTab } from \"./activity-tab.js\";\n\n// React hooks\nexport type { PluginI18nContextValue, PluginTranslation } from \"./hooks.js\";\nexport {\n\t__PluginI18nContext,\n\tuseTranslation,\n\tuseActiveConversation,\n\tuseConversationMessages,\n\tusePromptAttachment,\n} from \"./hooks.js\";\n"]}

package/dist/index.js

@@ -5,6 +5,7 @@
  * the stable package API. Prefer importing from `@vetta-org/plugin-sdk` rather
  * than deep paths.
  */
+export { usePluginShortcutScope } from "./shortcuts.js";
 export { PluginAppActionError } from "./app-actions.js";
 export { interpolatePluginText, resolveCatalogKey, resolvePluginText } from "./i18n.js";
 export { definePlugin } from "./context.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA0EH,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AA+ExD,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAIxF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAI5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAIzD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIzE,OAAO,EACN,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,GACnB,MAAM,YAAY,CAAC","sourcesContent":["/**\n * @vetta-org/plugin-sdk public surface.\n *\n * Implementation is split by domain under `src/*.ts`; this barrel re-exports\n * the stable package API. Prefer importing from `@vetta-org/plugin-sdk` rather\n * than deep paths.\n */\n\n// Core primitives\nexport type { ConversationScenario } from \"./scenario.js\";\nexport type { PluginPermission } from \"./permissions.js\";\nexport type { Disposable } from \"./disposable.js\";\nexport type { PluginMcpServerConfig, PluginAgentManifest } from \"./manifest.js\";\n\n// Conversation\nexport type {\n\tConversationState,\n\tConversationMessage,\n\tConversationEvent,\n\tPluginConversationApi,\n} from \"./conversation.js\";\n\n// UI slots\nexport type {\n\tPluginGlobalSlotContribution,\n\tPluginAudioMetadata,\n\tPluginPreviewUrlOptions,\n\tPluginPreviewFile,\n\tPluginFilePreviewProps,\n\tPluginFilePreviewContribution,\n\tPluginActivityTabContribution,\n\tPluginCaptureRegion,\n\tPluginOpenActivityTabOptions,\n\tPluginPromptDecoration,\n\tPluginInputActionContribution,\n\tCardDescriptor,\n\tPluginPendingToolCall,\n\tPluginCardProps,\n\tPluginCardRendererContribution,\n\tPluginToolCallSlotToolCall,\n\tPluginToolCallSlotProps,\n\tPluginToolCallSlotContribution,\n\tPluginTurnCardContribution,\n\tPluginNotifyOptions,\n\tPluginUiApi,\n} from \"./ui.js\";\n\n// Agent runtime\nexport type {\n\tPluginJsonSchema,\n\tPluginAgentToolApi,\n\tPluginAgentToolRegistration,\n\tPluginSystemPromptBlock,\n\tPluginDynamicSystemPromptOperation,\n\tPluginSystemPromptMessage,\n\tPluginSystemPromptProviderContext,\n\tPluginSystemPromptBlockView,\n\tPluginAgentActions,\n\tPluginAgentHandlerContext,\n\tPluginAgentToolHandler,\n\tPluginSystemPromptProviderHandler,\n\tPluginSystemPromptProviderRegistration,\n\tPluginContinuationResult,\n\tPluginContinuationHandler,\n\tPluginContinuationRegistration,\n\tPluginAgentApi,\n} from \"./agent.js\";\n\n// App actions\nexport type {\n\tPluginAppActionEffect,\n\tPluginAppActionExample,\n\tPluginAppActionHandlerContext,\n\tPluginAppActionHandler,\n\tPluginAppActionReadyHandler,\n\tPluginAppActionApprovalPresentation,\n\tPluginAppActionApproval,\n\tPluginAppActionRegistration,\n\tPluginAppActionsApi,\n} from \"./app-actions.js\";\nexport { PluginAppActionError } from \"./app-actions.js\";\n\n// Official host capabilities\nexport type {\n\tPluginOfficialGeneralSettings,\n\tPluginOfficialGeneralSettingsUpdate,\n\tPluginOfficialExperimentalSettings,\n\tPluginOfficialDownloadItem,\n\tPluginOfficialUpdaterState,\n\tPluginOfficialWebhookKind,\n\tPluginOfficialWebhookEndpoint,\n\tPluginOfficialWebhookProvider,\n\tPluginOfficialWebhookCreateInput,\n\tPluginOfficialWebhookUpdateInput,\n\tPluginOfficialWebhookMessage,\n\tPluginOfficialWebhookSendResult,\n\tPluginOfficialSkillInfo,\n\tPluginOfficialInstalledSkill,\n\tPluginOfficialShortcutBinding,\n\tPluginOfficialQuickPanelSettings,\n\tPluginOfficialImStatus,\n\tPluginOfficialImLog,\n\tPluginOfficialMcpServerSummary,\n\tPluginOfficialMcpServerDetail,\n\tPluginOfficialMcpUpsertData,\n\tPluginOfficialExecutionMode,\n\tPluginOfficialSelectedSkill,\n\tPluginOfficialBatchProjectCreateData,\n\tPluginOfficialBatchProjectUpdateData,\n\tPluginOfficialSchedulerTaskCreateData,\n\tPluginOfficialSchedulerTaskUpdateData,\n\tPluginOfficialModelSummary,\n\tPluginOfficialProviderSummary,\n\tPluginOfficialProviderDetail,\n\tPluginOfficialProviderUpsertData,\n\tPluginOfficialProjectEntry,\n\tPluginOfficialPluginSummary,\n\tPluginOfficialKnowledgeBase,\n\tPluginOfficialKnowledgeProcessingSettings,\n\tPluginOfficialApi,\n} from \"./official.js\";\n\n// Files / command / images / settings\nexport type {\n\tPluginFsEntry,\n\tPluginFsFileRef,\n\tPluginFsBinaryReadResult,\n\tPluginFsStatResult,\n\tPluginFsReadResult,\n\tPluginFsApi,\n} from \"./fs.js\";\nexport type {\n\tPluginCommandRunOptions,\n\tPluginCommandRunResult,\n\tPluginCommandApi,\n} from \"./command.js\";\nexport type { PluginImageRef } from \"./images.js\";\nexport type { PluginPromptAttachment } from \"./prompt-attachment.js\";\nexport type {\n\tPluginNetworkApi,\n\tPluginNetworkBody,\n\tPluginNetworkRequest,\n\tPluginNetworkResponse,\n} from \"./network.js\";\nexport type {\n\tPluginPutBlobInput,\n\tPluginStorageApi,\n\tPluginStoredBlob,\n\tPluginStoredBlobRef,\n} from \"./storage.js\";\nexport type { PluginSettingsApi } from \"./settings.js\";\n\n// i18n\nexport type {\n\tPluginLocaleCatalog,\n\tPluginLocales,\n\tPluginTranslate,\n\tPluginI18nApi,\n} from \"./i18n.js\";\nexport { interpolatePluginText, resolveCatalogKey, resolvePluginText } from \"./i18n.js\";\n\n// Context & lifecycle\nexport type { PluginPermissionApi, AgentMode, PluginContext, PluginDefinition } from \"./context.js\";\nexport { definePlugin } from \"./context.js\";\n\n// Host bridge (host-injected; plugins use hooks)\nexport type { PluginHostBridge } from \"./host-bridge.js\";\nexport { __setPluginHostBridge } from \"./host-bridge.js\";\n\n// Activity tab context\nexport type { ActivityTabContextValue } from \"./activity-tab.js\";\nexport { __ActivityTabContext, useActivityTab } from \"./activity-tab.js\";\n\n// React hooks\nexport type { PluginI18nContextValue, PluginTranslation } from \"./hooks.js\";\nexport {\n\t__PluginI18nContext,\n\tuseTranslation,\n\tuseActiveConversation,\n\tuseConversationMessages,\n\tusePromptAttachment,\n} from \"./hooks.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAmCxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAmFxD,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAIxF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAI5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAIzD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIzE,OAAO,EACN,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,GACnB,MAAM,YAAY,CAAC","sourcesContent":["/**\n * @vetta-org/plugin-sdk public surface.\n *\n * Implementation is split by domain under `src/*.ts`; this barrel re-exports\n * the stable package API. Prefer importing from `@vetta-org/plugin-sdk` rather\n * than deep paths.\n */\n\n// Core primitives\nexport type { ConversationScenario } from \"./scenario.js\";\nexport type { PluginPermission } from \"./permissions.js\";\nexport type { Disposable } from \"./disposable.js\";\nexport type { PluginMcpServerConfig, PluginAgentManifest } from \"./manifest.js\";\n\n// File explorer\nexport type {\n\tPluginFileExplorerEntry,\n\tPluginWorkspaceRoot,\n\tPluginFileExplorerWhen,\n\tPluginFileExplorerActionContext,\n\tPluginFileExplorerContextMenuContribution,\n\tPluginFileExplorerToolbarContext,\n\tPluginFileExplorerToolbarContribution,\n\tPluginFileExplorerDecoration,\n\tPluginFileExplorerDecorationProvider,\n\tPluginFileExplorerChange,\n\tPluginFileExplorerRevealOptions,\n\tPluginFileExplorerApi,\n} from \"./file-explorer.js\";\n\n// Conversation\nexport type {\n\tConversationState,\n\tConversationMessage,\n\tConversationEvent,\n\tPluginConversationApi,\n} from \"./conversation.js\";\n\n// UI slots\nexport type {\n\tPluginGlobalSlotContribution,\n\tPluginAudioMetadata,\n\tPluginPreviewUrlOptions,\n\tPluginPreviewFile,\n\tPluginFilePreviewProps,\n\tPluginFilePreviewContribution,\n\tPluginActivityTabContribution,\n\tPluginCaptureRegion,\n\tPluginOpenActivityTabOptions,\n\tPluginPromptDecoration,\n\tPluginInputActionContribution,\n\tCardDescriptor,\n\tPluginPendingToolCall,\n\tPluginCardProps,\n\tPluginCardRendererContribution,\n\tPluginToolCallSlotToolCall,\n\tPluginToolCallSlotProps,\n\tPluginToolCallSlotContribution,\n\tPluginTurnCardContribution,\n\tPluginNotifyOptions,\n\tPluginUiApi,\n} from \"./ui.js\";\n\n// Keyboard shortcuts (host ShortcutScopeStack)\nexport type {\n\tPluginShortcutScopeKind,\n\tPluginShortcutWhen,\n\tPluginShortcutBinding,\n\tPluginShortcutScopeContribution,\n\tPluginRegisterShortcutScope,\n\tUsePluginShortcutScopeOptions,\n} from \"./shortcuts.js\";\nexport { usePluginShortcutScope } from \"./shortcuts.js\";\n\n// Agent runtime\nexport type {\n\tPluginJsonSchema,\n\tPluginAgentToolApi,\n\tPluginAgentToolRegistration,\n\tPluginSystemPromptBlock,\n\tPluginDynamicSystemPromptOperation,\n\tPluginSystemPromptMessage,\n\tPluginSystemPromptProviderContext,\n\tPluginSystemPromptBlockView,\n\tPluginAgentActions,\n\tPluginAgentHandlerContext,\n\tPluginAgentToolHandler,\n\tPluginSystemPromptProviderHandler,\n\tPluginSystemPromptProviderRegistration,\n\tPluginContinuationResult,\n\tPluginContinuationHandler,\n\tPluginContinuationRegistration,\n\tPluginAgentApi,\n} from \"./agent.js\";\n\n// App actions\nexport type {\n\tPluginAppActionEffect,\n\tPluginAppActionExample,\n\tPluginAppActionHandlerContext,\n\tPluginAppActionHandler,\n\tPluginAppActionReadyHandler,\n\tPluginAppActionApprovalPresentation,\n\tPluginAppActionApproval,\n\tPluginAppActionRegistration,\n\tPluginAppActionsApi,\n} from \"./app-actions.js\";\nexport { PluginAppActionError } from \"./app-actions.js\";\n\n// Official host capabilities\nexport type {\n\tPluginOfficialGeneralSettings,\n\tPluginOfficialGeneralSettingsUpdate,\n\tPluginOfficialExperimentalSettings,\n\tPluginOfficialDownloadItem,\n\tPluginOfficialUpdaterState,\n\tPluginOfficialWebhookKind,\n\tPluginOfficialWebhookEndpoint,\n\tPluginOfficialWebhookProvider,\n\tPluginOfficialWebhookCreateInput,\n\tPluginOfficialWebhookUpdateInput,\n\tPluginOfficialWebhookMessage,\n\tPluginOfficialWebhookSendResult,\n\tPluginOfficialSkillInfo,\n\tPluginOfficialInstalledSkill,\n\tPluginOfficialShortcutBinding,\n\tPluginOfficialQuickPanelSettings,\n\tPluginOfficialImStatus,\n\tPluginOfficialImLog,\n\tPluginOfficialMcpServerSummary,\n\tPluginOfficialMcpServerDetail,\n\tPluginOfficialMcpUpsertData,\n\tPluginOfficialExecutionMode,\n\tPluginOfficialSelectedSkill,\n\tPluginOfficialBatchProjectCreateData,\n\tPluginOfficialBatchProjectUpdateData,\n\tPluginOfficialSchedulerTaskCreateData,\n\tPluginOfficialSchedulerTaskUpdateData,\n\tPluginOfficialModelSummary,\n\tPluginOfficialProviderSummary,\n\tPluginOfficialProviderDetail,\n\tPluginOfficialProviderUpsertData,\n\tPluginOfficialProjectEntry,\n\tPluginOfficialPluginSummary,\n\tPluginOfficialKnowledgeBase,\n\tPluginOfficialKnowledgeProcessingSettings,\n\tPluginOfficialApi,\n} from \"./official.js\";\n\n// Files / command / images / settings\nexport type {\n\tPluginFsEntry,\n\tPluginFsFileRef,\n\tPluginFsBinaryReadResult,\n\tPluginFsStatResult,\n\tPluginFsReadResult,\n\tPluginFsApi,\n} from \"./fs.js\";\nexport type {\n\tPluginCommandRunOptions,\n\tPluginCommandRunResult,\n\tPluginCommandSpawnOptions,\n\tPluginCommandSpawnExit,\n\tPluginCommandSpawnStatus,\n\tPluginCommandSpawnHandle,\n\tPluginCommandApi,\n} from \"./command.js\";\nexport type { PluginImageRef } from \"./images.js\";\nexport type { PluginPromptAttachment } from \"./prompt-attachment.js\";\nexport type {\n\tPluginNetworkApi,\n\tPluginNetworkBody,\n\tPluginNetworkRequest,\n\tPluginNetworkResponse,\n} from \"./network.js\";\nexport type {\n\tPluginPutBlobInput,\n\tPluginStorageApi,\n\tPluginStoredBlob,\n\tPluginStoredBlobRef,\n} from \"./storage.js\";\nexport type { PluginSettingsApi } from \"./settings.js\";\n\n// i18n\nexport type {\n\tPluginLocaleCatalog,\n\tPluginLocales,\n\tPluginTranslate,\n\tPluginI18nApi,\n} from \"./i18n.js\";\nexport { interpolatePluginText, resolveCatalogKey, resolvePluginText } from \"./i18n.js\";\n\n// Context & lifecycle\nexport type { PluginPermissionApi, AgentMode, PluginContext, PluginDefinition } from \"./context.js\";\nexport { definePlugin } from \"./context.js\";\n\n// Host bridge (host-injected; plugins use hooks)\nexport type { PluginHostBridge } from \"./host-bridge.js\";\nexport { __setPluginHostBridge } from \"./host-bridge.js\";\n\n// Activity tab context\nexport type { ActivityTabContextValue } from \"./activity-tab.js\";\nexport { __ActivityTabContext, useActivityTab } from \"./activity-tab.js\";\n\n// React hooks\nexport type { PluginI18nContextValue, PluginTranslation } from \"./hooks.js\";\nexport {\n\t__PluginI18nContext,\n\tuseTranslation,\n\tuseActiveConversation,\n\tuseConversationMessages,\n\tusePromptAttachment,\n} from \"./hooks.js\";\n"]}

package/dist/permissions.d.ts

@@ -1,2 +1,2 @@
-export type PluginPermission = "ui.slot.global" | "ui.slot.file-preview" | "ui.slot.activity-tab" | "ui.slot.input-action" | "ui.slot.message" | "ui.slot.tool-call" | "ui.slot.turn-card" | "agent.session.read" | "agent.session.write" | "agent.command.run" | "agent.systemPrompt.read" | "agent.systemPrompt.write" | "agent.systemPrompt.fullControl" | "agent.skills.control" | "agent.mcp.control" | "agent.tools.control" | "agent.tools.register" | "agent.toolHandler.execute" | "agent.state.read" | "agent.state.write" | "agent.continuation.register" | "agent.runtime.configure" | "app.actions.register" | "app.actionHandler.execute" | "fs.read" | "fs.write" | "network.fetch" | "storage.read" | "storage.write" | "settings.read" | "settings.write";
+export type PluginPermission = "ui.slot.global" | "ui.slot.file-preview" | "ui.slot.activity-tab" | "ui.slot.input-action" | "ui.slot.message" | "ui.slot.tool-call" | "ui.slot.turn-card" | "ui.shortcuts.register" | "ui.file-explorer.decorations" | "ui.file-explorer.context-menu" | "ui.file-explorer.toolbar" | "workspace.read" | "agent.session.read" | "agent.session.write" | "agent.command.run" | "agent.command.spawn" | "agent.systemPrompt.read" | "agent.systemPrompt.write" | "agent.systemPrompt.fullControl" | "agent.skills.control" | "agent.mcp.control" | "agent.tools.control" | "agent.tools.register" | "agent.toolHandler.execute" | "agent.state.read" | "agent.state.write" | "agent.continuation.register" | "agent.runtime.configure" | "app.actions.register" | "app.actionHandler.execute" | "fs.read" | "fs.write" | "network.fetch" | "storage.read" | "storage.write" | "settings.read" | "settings.write";
 //# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACzB,gBAAgB,GAChB,sBAAsB,GACtB,sBAAsB,GACtB,sBAAsB,GACtB,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,GACnB,oBAAoB,GACpB,qBAAqB,GACrB,mBAAmB,GACnB,yBAAyB,GACzB,0BAA0B,GAC1B,gCAAgC,GAChC,sBAAsB,GACtB,mBAAmB,GACnB,qBAAqB,GACrB,sBAAsB,GACtB,2BAA2B,GAC3B,kBAAkB,GAClB,mBAAmB,GACnB,6BAA6B,GAC7B,yBAAyB,GACzB,sBAAsB,GACtB,2BAA2B,GAC3B,SAAS,GACT,UAAU,GACV,eAAe,GACf,cAAc,GACd,eAAe,GACf,eAAe,GACf,gBAAgB,CAAC","sourcesContent":["export type PluginPermission =\n\t| \"ui.slot.global\"\n\t| \"ui.slot.file-preview\"\n\t| \"ui.slot.activity-tab\"\n\t| \"ui.slot.input-action\"\n\t| \"ui.slot.message\"\n\t| \"ui.slot.tool-call\"\n\t| \"ui.slot.turn-card\"\n\t| \"agent.session.read\"\n\t| \"agent.session.write\"\n\t| \"agent.command.run\"\n\t| \"agent.systemPrompt.read\"\n\t| \"agent.systemPrompt.write\"\n\t| \"agent.systemPrompt.fullControl\"\n\t| \"agent.skills.control\"\n\t| \"agent.mcp.control\"\n\t| \"agent.tools.control\"\n\t| \"agent.tools.register\"\n\t| \"agent.toolHandler.execute\"\n\t| \"agent.state.read\"\n\t| \"agent.state.write\"\n\t| \"agent.continuation.register\"\n\t| \"agent.runtime.configure\"\n\t| \"app.actions.register\"\n\t| \"app.actionHandler.execute\"\n\t| \"fs.read\"\n\t| \"fs.write\"\n\t| \"network.fetch\"\n\t| \"storage.read\"\n\t| \"storage.write\"\n\t| \"settings.read\"\n\t| \"settings.write\";\n"]}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACzB,gBAAgB,GAChB,sBAAsB,GACtB,sBAAsB,GACtB,sBAAsB,GACtB,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,GACnB,uBAAuB,GACvB,8BAA8B,GAC9B,+BAA+B,GAC/B,0BAA0B,GAC1B,gBAAgB,GAChB,oBAAoB,GACpB,qBAAqB,GACrB,mBAAmB,GACnB,qBAAqB,GACrB,yBAAyB,GACzB,0BAA0B,GAC1B,gCAAgC,GAChC,sBAAsB,GACtB,mBAAmB,GACnB,qBAAqB,GACrB,sBAAsB,GACtB,2BAA2B,GAC3B,kBAAkB,GAClB,mBAAmB,GACnB,6BAA6B,GAC7B,yBAAyB,GACzB,sBAAsB,GACtB,2BAA2B,GAC3B,SAAS,GACT,UAAU,GACV,eAAe,GACf,cAAc,GACd,eAAe,GACf,eAAe,GACf,gBAAgB,CAAC","sourcesContent":["export type PluginPermission =\n\t| \"ui.slot.global\"\n\t| \"ui.slot.file-preview\"\n\t| \"ui.slot.activity-tab\"\n\t| \"ui.slot.input-action\"\n\t| \"ui.slot.message\"\n\t| \"ui.slot.tool-call\"\n\t| \"ui.slot.turn-card\"\n\t| \"ui.shortcuts.register\"\n\t| \"ui.file-explorer.decorations\"\n\t| \"ui.file-explorer.context-menu\"\n\t| \"ui.file-explorer.toolbar\"\n\t| \"workspace.read\"\n\t| \"agent.session.read\"\n\t| \"agent.session.write\"\n\t| \"agent.command.run\"\n\t| \"agent.command.spawn\"\n\t| \"agent.systemPrompt.read\"\n\t| \"agent.systemPrompt.write\"\n\t| \"agent.systemPrompt.fullControl\"\n\t| \"agent.skills.control\"\n\t| \"agent.mcp.control\"\n\t| \"agent.tools.control\"\n\t| \"agent.tools.register\"\n\t| \"agent.toolHandler.execute\"\n\t| \"agent.state.read\"\n\t| \"agent.state.write\"\n\t| \"agent.continuation.register\"\n\t| \"agent.runtime.configure\"\n\t| \"app.actions.register\"\n\t| \"app.actionHandler.execute\"\n\t| \"fs.read\"\n\t| \"fs.write\"\n\t| \"network.fetch\"\n\t| \"storage.read\"\n\t| \"storage.write\"\n\t| \"settings.read\"\n\t| \"settings.write\";\n"]}

package/dist/permissions.js.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"","sourcesContent":["export type PluginPermission =\n\t| \"ui.slot.global\"\n\t| \"ui.slot.file-preview\"\n\t| \"ui.slot.activity-tab\"\n\t| \"ui.slot.input-action\"\n\t| \"ui.slot.message\"\n\t| \"ui.slot.tool-call\"\n\t| \"ui.slot.turn-card\"\n\t| \"agent.session.read\"\n\t| \"agent.session.write\"\n\t| \"agent.command.run\"\n\t| \"agent.systemPrompt.read\"\n\t| \"agent.systemPrompt.write\"\n\t| \"agent.systemPrompt.fullControl\"\n\t| \"agent.skills.control\"\n\t| \"agent.mcp.control\"\n\t| \"agent.tools.control\"\n\t| \"agent.tools.register\"\n\t| \"agent.toolHandler.execute\"\n\t| \"agent.state.read\"\n\t| \"agent.state.write\"\n\t| \"agent.continuation.register\"\n\t| \"agent.runtime.configure\"\n\t| \"app.actions.register\"\n\t| \"app.actionHandler.execute\"\n\t| \"fs.read\"\n\t| \"fs.write\"\n\t| \"network.fetch\"\n\t| \"storage.read\"\n\t| \"storage.write\"\n\t| \"settings.read\"\n\t| \"settings.write\";\n"]}
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"","sourcesContent":["export type PluginPermission =\n\t| \"ui.slot.global\"\n\t| \"ui.slot.file-preview\"\n\t| \"ui.slot.activity-tab\"\n\t| \"ui.slot.input-action\"\n\t| \"ui.slot.message\"\n\t| \"ui.slot.tool-call\"\n\t| \"ui.slot.turn-card\"\n\t| \"ui.shortcuts.register\"\n\t| \"ui.file-explorer.decorations\"\n\t| \"ui.file-explorer.context-menu\"\n\t| \"ui.file-explorer.toolbar\"\n\t| \"workspace.read\"\n\t| \"agent.session.read\"\n\t| \"agent.session.write\"\n\t| \"agent.command.run\"\n\t| \"agent.command.spawn\"\n\t| \"agent.systemPrompt.read\"\n\t| \"agent.systemPrompt.write\"\n\t| \"agent.systemPrompt.fullControl\"\n\t| \"agent.skills.control\"\n\t| \"agent.mcp.control\"\n\t| \"agent.tools.control\"\n\t| \"agent.tools.register\"\n\t| \"agent.toolHandler.execute\"\n\t| \"agent.state.read\"\n\t| \"agent.state.write\"\n\t| \"agent.continuation.register\"\n\t| \"agent.runtime.configure\"\n\t| \"app.actions.register\"\n\t| \"app.actionHandler.execute\"\n\t| \"fs.read\"\n\t| \"fs.write\"\n\t| \"network.fetch\"\n\t| \"storage.read\"\n\t| \"storage.write\"\n\t| \"settings.read\"\n\t| \"settings.write\";\n"]}

package/dist/shortcuts.d.ts

@@ -0,0 +1,60 @@
+import type { Disposable } from "./disposable.js";
+/**
+ * Keyboard shortcut scopes (priority high → low), mirroring the host stack:
+ * - modal: dialogs (often exclusive)
+ * - overlay: pickers / floating UI
+ * - surface: previews, panels, editors
+ *
+ * Plugins cannot register `app` — that layer is reserved for host-configurable
+ * global actions (settings → shortcuts).
+ */
+export type PluginShortcutScopeKind = "surface" | "overlay" | "modal";
+export type PluginShortcutWhen = "always" | "editable" | "not-editable";
+export interface PluginShortcutBinding {
+    /**
+     * Serialized combo matching the host `eventToShortcut` format, e.g.
+     * `"mod+s"`, `"escape"`, `"arrowleft"`, `"="`, `"-"`.
+     */
+    key: string;
+    run: (event: KeyboardEvent) => void;
+    /** Default `"always"`. Restrict to / out of editable targets. */
+    when?: PluginShortcutWhen;
+    /** Default true. */
+    preventDefault?: boolean;
+    /** Default true. */
+    stopPropagation?: boolean;
+}
+export interface PluginShortcutScopeContribution {
+    /** Local id; host namespaces as `pluginId:id`. */
+    id: string;
+    kind: PluginShortcutScopeKind;
+    /** When true, unmatched keys do not fall through to lower scopes. */
+    exclusive?: boolean;
+    /** Dynamic gate; re-checked on every keydown. */
+    enabled?: () => boolean;
+    /**
+     * Static list or factory. Factories are read each keydown so handlers can
+     * close over the latest component state without re-registering.
+     */
+    bindings: readonly PluginShortcutBinding[] | (() => readonly PluginShortcutBinding[]);
+}
+export type PluginRegisterShortcutScope = (contribution: PluginShortcutScopeContribution) => Disposable;
+export interface UsePluginShortcutScopeOptions {
+    /** Stable local id (host namespaces with plugin id). */
+    id: string;
+    kind: PluginShortcutScopeKind;
+    /** When false, scope is not registered. Default true. */
+    active?: boolean;
+    exclusive?: boolean;
+    enabled?: () => boolean;
+    bindings: readonly PluginShortcutBinding[];
+}
+/**
+ * Component-scoped shortcut registration for plugins.
+ *
+ * Pass `ctx.ui.registerShortcutScope` captured in `activate` (module-level),
+ * same pattern as `notify`. While `active` is true, bindings participate in the
+ * host ShortcutScopeStack — do not add ad-hoc `document` keydown listeners.
+ */
+export declare function usePluginShortcutScope(register: PluginRegisterShortcutScope | null | undefined, options: UsePluginShortcutScopeOptions): void;
+//# sourceMappingURL=shortcuts.d.ts.map

package/dist/shortcuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcuts.d.ts","sourceRoot":"","sources":["../src/shortcuts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEtE,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,UAAU,GAAG,cAAc,CAAC;AAExE,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IACpC,iEAAiE;IACjE,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,oBAAoB;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oBAAoB;IACpB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,+BAA+B;IAC/C,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,uBAAuB,CAAC;IAC9B,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;IACxB;;;OAGG;IACH,QAAQ,EAAE,SAAS,qBAAqB,EAAE,GAAG,CAAC,MAAM,SAAS,qBAAqB,EAAE,CAAC,CAAC;CACtF;AAED,MAAM,MAAM,2BAA2B,GAAG,CAAC,YAAY,EAAE,+BAA+B,KAAK,UAAU,CAAC;AAExG,MAAM,WAAW,6BAA6B;IAC7C,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,uBAAuB,CAAC;IAC9B,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;IACxB,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACrC,QAAQ,EAAE,2BAA2B,GAAG,IAAI,GAAG,SAAS,EACxD,OAAO,EAAE,6BAA6B,GACpC,IAAI,CAyBN","sourcesContent":["import { useEffect, useRef } from \"react\";\nimport type { Disposable } from \"./disposable.js\";\n\n/**\n * Keyboard shortcut scopes (priority high → low), mirroring the host stack:\n * - modal: dialogs (often exclusive)\n * - overlay: pickers / floating UI\n * - surface: previews, panels, editors\n *\n * Plugins cannot register `app` — that layer is reserved for host-configurable\n * global actions (settings → shortcuts).\n */\nexport type PluginShortcutScopeKind = \"surface\" | \"overlay\" | \"modal\";\n\nexport type PluginShortcutWhen = \"always\" | \"editable\" | \"not-editable\";\n\nexport interface PluginShortcutBinding {\n\t/**\n\t * Serialized combo matching the host `eventToShortcut` format, e.g.\n\t * `\"mod+s\"`, `\"escape\"`, `\"arrowleft\"`, `\"=\"`, `\"-\"`.\n\t */\n\tkey: string;\n\trun: (event: KeyboardEvent) => void;\n\t/** Default `\"always\"`. Restrict to / out of editable targets. */\n\twhen?: PluginShortcutWhen;\n\t/** Default true. */\n\tpreventDefault?: boolean;\n\t/** Default true. */\n\tstopPropagation?: boolean;\n}\n\nexport interface PluginShortcutScopeContribution {\n\t/** Local id; host namespaces as `pluginId:id`. */\n\tid: string;\n\tkind: PluginShortcutScopeKind;\n\t/** When true, unmatched keys do not fall through to lower scopes. */\n\texclusive?: boolean;\n\t/** Dynamic gate; re-checked on every keydown. */\n\tenabled?: () => boolean;\n\t/**\n\t * Static list or factory. Factories are read each keydown so handlers can\n\t * close over the latest component state without re-registering.\n\t */\n\tbindings: readonly PluginShortcutBinding[] | (() => readonly PluginShortcutBinding[]);\n}\n\nexport type PluginRegisterShortcutScope = (contribution: PluginShortcutScopeContribution) => Disposable;\n\nexport interface UsePluginShortcutScopeOptions {\n\t/** Stable local id (host namespaces with plugin id). */\n\tid: string;\n\tkind: PluginShortcutScopeKind;\n\t/** When false, scope is not registered. Default true. */\n\tactive?: boolean;\n\texclusive?: boolean;\n\tenabled?: () => boolean;\n\tbindings: readonly PluginShortcutBinding[];\n}\n\n/**\n * Component-scoped shortcut registration for plugins.\n *\n * Pass `ctx.ui.registerShortcutScope` captured in `activate` (module-level),\n * same pattern as `notify`. While `active` is true, bindings participate in the\n * host ShortcutScopeStack — do not add ad-hoc `document` keydown listeners.\n */\nexport function usePluginShortcutScope(\n\tregister: PluginRegisterShortcutScope | null | undefined,\n\toptions: UsePluginShortcutScopeOptions,\n): void {\n\tconst bindingsRef = useRef(options.bindings);\n\tbindingsRef.current = options.bindings;\n\tconst enabledRef = useRef(options.enabled);\n\tenabledRef.current = options.enabled;\n\n\tconst keySignature = options.bindings.map((b) => `${b.key}:${b.when ?? \"always\"}`).join(\"|\");\n\tconst active = options.active !== false;\n\n\tuseEffect(() => {\n\t\tif (!register || !active) return;\n\t\tconst handle = register({\n\t\t\tid: options.id,\n\t\t\tkind: options.kind,\n\t\t\texclusive: options.exclusive,\n\t\t\tenabled: enabledRef.current\n\t\t\t\t? () => {\n\t\t\t\t\t\tconst gate = enabledRef.current;\n\t\t\t\t\t\treturn gate ? gate() : true;\n\t\t\t\t\t}\n\t\t\t\t: undefined,\n\t\t\tbindings: () => bindingsRef.current,\n\t\t});\n\t\treturn () => handle.dispose();\n\t}, [register, options.id, options.kind, options.exclusive, active, keySignature]);\n}\n"]}

package/dist/shortcuts.js

@@ -0,0 +1,34 @@
+import { useEffect, useRef } from "react";
+/**
+ * Component-scoped shortcut registration for plugins.
+ *
+ * Pass `ctx.ui.registerShortcutScope` captured in `activate` (module-level),
+ * same pattern as `notify`. While `active` is true, bindings participate in the
+ * host ShortcutScopeStack — do not add ad-hoc `document` keydown listeners.
+ */
+export function usePluginShortcutScope(register, options) {
+    const bindingsRef = useRef(options.bindings);
+    bindingsRef.current = options.bindings;
+    const enabledRef = useRef(options.enabled);
+    enabledRef.current = options.enabled;
+    const keySignature = options.bindings.map((b) => `${b.key}:${b.when ?? "always"}`).join("|");
+    const active = options.active !== false;
+    useEffect(() => {
+        if (!register || !active)
+            return;
+        const handle = register({
+            id: options.id,
+            kind: options.kind,
+            exclusive: options.exclusive,
+            enabled: enabledRef.current
+                ? () => {
+                    const gate = enabledRef.current;
+                    return gate ? gate() : true;
+                }
+                : undefined,
+            bindings: () => bindingsRef.current,
+        });
+        return () => handle.dispose();
+    }, [register, options.id, options.kind, options.exclusive, active, keySignature]);
+}
+//# sourceMappingURL=shortcuts.js.map

package/dist/shortcuts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcuts.js","sourceRoot":"","sources":["../src/shortcuts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AA2D1C;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACrC,QAAwD,EACxD,OAAsC,EAC/B;IACP,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7C,WAAW,CAAC,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IACvC,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAErC,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,IAAI,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7F,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC;IAExC,SAAS,CAAC,GAAG,EAAE,CAAC;QACf,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM;YAAE,OAAO;QACjC,MAAM,MAAM,GAAG,QAAQ,CAAC;YACvB,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,OAAO,EAAE,UAAU,CAAC,OAAO;gBAC1B,CAAC,CAAC,GAAG,EAAE,CAAC;oBACN,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC;oBAChC,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;gBAAA,CAC5B;gBACF,CAAC,CAAC,SAAS;YACZ,QAAQ,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO;SACnC,CAAC,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IAAA,CAC9B,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;AAAA,CAClF","sourcesContent":["import { useEffect, useRef } from \"react\";\nimport type { Disposable } from \"./disposable.js\";\n\n/**\n * Keyboard shortcut scopes (priority high → low), mirroring the host stack:\n * - modal: dialogs (often exclusive)\n * - overlay: pickers / floating UI\n * - surface: previews, panels, editors\n *\n * Plugins cannot register `app` — that layer is reserved for host-configurable\n * global actions (settings → shortcuts).\n */\nexport type PluginShortcutScopeKind = \"surface\" | \"overlay\" | \"modal\";\n\nexport type PluginShortcutWhen = \"always\" | \"editable\" | \"not-editable\";\n\nexport interface PluginShortcutBinding {\n\t/**\n\t * Serialized combo matching the host `eventToShortcut` format, e.g.\n\t * `\"mod+s\"`, `\"escape\"`, `\"arrowleft\"`, `\"=\"`, `\"-\"`.\n\t */\n\tkey: string;\n\trun: (event: KeyboardEvent) => void;\n\t/** Default `\"always\"`. Restrict to / out of editable targets. */\n\twhen?: PluginShortcutWhen;\n\t/** Default true. */\n\tpreventDefault?: boolean;\n\t/** Default true. */\n\tstopPropagation?: boolean;\n}\n\nexport interface PluginShortcutScopeContribution {\n\t/** Local id; host namespaces as `pluginId:id`. */\n\tid: string;\n\tkind: PluginShortcutScopeKind;\n\t/** When true, unmatched keys do not fall through to lower scopes. */\n\texclusive?: boolean;\n\t/** Dynamic gate; re-checked on every keydown. */\n\tenabled?: () => boolean;\n\t/**\n\t * Static list or factory. Factories are read each keydown so handlers can\n\t * close over the latest component state without re-registering.\n\t */\n\tbindings: readonly PluginShortcutBinding[] | (() => readonly PluginShortcutBinding[]);\n}\n\nexport type PluginRegisterShortcutScope = (contribution: PluginShortcutScopeContribution) => Disposable;\n\nexport interface UsePluginShortcutScopeOptions {\n\t/** Stable local id (host namespaces with plugin id). */\n\tid: string;\n\tkind: PluginShortcutScopeKind;\n\t/** When false, scope is not registered. Default true. */\n\tactive?: boolean;\n\texclusive?: boolean;\n\tenabled?: () => boolean;\n\tbindings: readonly PluginShortcutBinding[];\n}\n\n/**\n * Component-scoped shortcut registration for plugins.\n *\n * Pass `ctx.ui.registerShortcutScope` captured in `activate` (module-level),\n * same pattern as `notify`. While `active` is true, bindings participate in the\n * host ShortcutScopeStack — do not add ad-hoc `document` keydown listeners.\n */\nexport function usePluginShortcutScope(\n\tregister: PluginRegisterShortcutScope | null | undefined,\n\toptions: UsePluginShortcutScopeOptions,\n): void {\n\tconst bindingsRef = useRef(options.bindings);\n\tbindingsRef.current = options.bindings;\n\tconst enabledRef = useRef(options.enabled);\n\tenabledRef.current = options.enabled;\n\n\tconst keySignature = options.bindings.map((b) => `${b.key}:${b.when ?? \"always\"}`).join(\"|\");\n\tconst active = options.active !== false;\n\n\tuseEffect(() => {\n\t\tif (!register || !active) return;\n\t\tconst handle = register({\n\t\t\tid: options.id,\n\t\t\tkind: options.kind,\n\t\t\texclusive: options.exclusive,\n\t\t\tenabled: enabledRef.current\n\t\t\t\t? () => {\n\t\t\t\t\t\tconst gate = enabledRef.current;\n\t\t\t\t\t\treturn gate ? gate() : true;\n\t\t\t\t\t}\n\t\t\t\t: undefined,\n\t\t\tbindings: () => bindingsRef.current,\n\t\t});\n\t\treturn () => handle.dispose();\n\t}, [register, options.id, options.kind, options.exclusive, active, keySignature]);\n}\n"]}

package/dist/ui.d.ts

@@ -4,6 +4,7 @@ import type { Disposable } from "./disposable.js";
 import type { PluginImageRef } from "./images.js";
 import type { PluginPromptAttachment } from "./prompt-attachment.js";
 import type { ConversationScenario } from "./scenario.js";
+import type { PluginShortcutScopeContribution } from "./shortcuts.js";
 export interface PluginGlobalSlotContribution {
     id: string;
     component: ComponentType;
@@ -306,6 +307,14 @@ export interface PluginUiApi {
      * (fail-closed). Needs the `ui.slot.turn-card` permission.
      */
     registerTurnCard(contribution: PluginTurnCardContribution): Disposable;
+    /**
+     * Register a keyboard shortcut scope on the host's shared ShortcutScopeStack
+     * (same path as host UI: modal > overlay > surface > app). Needs
+     * `ui.shortcuts.register`. Plugins cannot use kind `"app"` (reserved for
+     * host-configurable global actions). Prefer {@link usePluginShortcutScope}
+     * from React components with a module-captured `registerShortcutScope`.
+     */
+    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`
@@ -329,6 +338,15 @@ export interface PluginUiApi {
      * no-op（无处记录），插件应在会话就绪后重新判定。
      */
     setActivityTabVisible(tabId: string, visible: boolean): void;
+    /**
+     * 直接设置活动面板宽度：像素值，或 `"max"` 表示当前窗口下的最大宽度（宿主仍
+     * 会夹到自己的 min/max 内，必要时自动收起侧边栏）。
+     *
+     * 与 `openActivityTab(id, { width })` 的区别：那里的宽度只在标签卡首次 attach
+     * 时生效（避免 activate 重放覆盖用户手拖的宽度）；这个是命令式的，每次调用都
+     * 生效，供插件在自己的标签卡被激活、进入某种视图时按需调整。用户随后仍可拖动。
+     */
+    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,
@@ -355,6 +373,13 @@ export interface PluginUiApi {
      * Requires `ui.slot.activity-tab`.
      */
     captureRegion(rect: PluginCaptureRegion, defaultFileName: string): Promise<string | null>;
+    /**
+     * Copy an image to the system clipboard. Takes a `data:image/...;base64,`
+     * URL and goes through the native clipboard, so it does not depend on the
+     * renderer's `ClipboardItem` support. No permission required — the plugin
+     * can only write what it already rendered.
+     */
+    copyImage(dataUrl: 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

package/dist/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,WAAW,4BAA4B;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IACnC,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACvC,iEAAiE;IACjE,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,+BAA+B;IAC/B,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAClC,8DAA8D;IAC9D,MAAM,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,MAAM,CAAC;IAClD;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,UAAU,CAAC;IACxC;;;OAGG;IACH,gBAAgB,CAAC,IAAI,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,iBAAiB,CAAC;CACxB;AAED,MAAM,WAAW,6BAA6B;IAC7C,2DAA2D;IAC3D,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC5C;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,uDAAuD;AACvD,MAAM,WAAW,4BAA4B;IAC5C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IACnC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,6BAA6B;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,wEAAwE;IACxE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC5C;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAAC;IAC3C;;;OAGG;IACH,cAAc,CAAC,IAAI,sBAAsB,GAAG,IAAI,CAAC;CACjD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,UAAU,EAAE,cAAc,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,mBAAmB,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,8BAA8B;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK,cAAc,GAAG,IAAI,CAAC;CACxE;AAED,uDAAuD;AACvD,MAAM,WAAW,0BAA0B;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,EAAE,0BAA0B,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,8BAA8B;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC,uBAAuB,CAAC,CAAC;CAClD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,0BAA0B;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,aAAa,CAAC;IACzB;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC5C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACnD;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC3B,kBAAkB,CAAC,YAAY,EAAE,4BAA4B,GAAG,UAAU,CAAC;IAC3E;;;;OAIG;IACH,mBAAmB,CAAC,YAAY,EAAE,6BAA6B,GAAG,UAAU,CAAC;IAC7E;;;;OAIG;IACH,mBAAmB,CAAC,YAAY,EAAE,6BAA6B,GAAG,UAAU,CAAC;IAC7E;;;OAGG;IACH,mBAAmB,CAAC,YAAY,EAAE,6BAA6B,GAAG,UAAU,CAAC;IAC7E;;;;;;OAMG;IACH,oBAAoB,CAAC,YAAY,EAAE,8BAA8B,GAAG,UAAU,CAAC;IAC/E;;;;OAIG;IACH,oBAAoB,CAAC,YAAY,EAAE,8BAA8B,GAAG,UAAU,CAAC;IAC/E;;;;;;OAMG;IACH,gBAAgB,CAAC,YAAY,EAAE,0BAA0B,GAAG,UAAU,CAAC;IACvE;;;;;;;;;;OAUG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,4BAA4B,GAAG,IAAI,CAAC;IAC7E;;;;;;;;;OASG;IACH,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7D;;;;OAIG;IACH,mBAAmB,CAAC,UAAU,EAAE,sBAAsB,GAAG,IAAI,GAAG,IAAI,CAAC;IACrE;;;;;;OAMG;IACH,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IAClE;;;;OAIG;IACH,kBAAkB,IAAI,IAAI,CAAC;IAC3B;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1F;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC3C","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"]}
+{"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 { PluginPromptAttachment } from \"./prompt-attachment.js\";\nimport type { ConversationScenario } from \"./scenario.js\";\nimport type { PluginShortcutScopeContribution } from \"./shortcuts.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 * Register a keyboard shortcut scope on the host's shared ShortcutScopeStack\n\t * (same path as host UI: modal > overlay > surface > app). Needs\n\t * `ui.shortcuts.register`. Plugins cannot use kind `\"app\"` (reserved for\n\t * host-configurable global actions). Prefer {@link usePluginShortcutScope}\n\t * from React components with a module-captured `registerShortcutScope`.\n\t */\n\tregisterShortcutScope(contribution: PluginShortcutScopeContribution): 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 * 直接设置活动面板宽度：像素值，或 `\"max\"` 表示当前窗口下的最大宽度（宿主仍\n\t * 会夹到自己的 min/max 内，必要时自动收起侧边栏）。\n\t *\n\t * 与 `openActivityTab(id, { width })` 的区别：那里的宽度只在标签卡首次 attach\n\t * 时生效（避免 activate 重放覆盖用户手拖的宽度）；这个是命令式的，每次调用都\n\t * 生效，供插件在自己的标签卡被激活、进入某种视图时按需调整。用户随后仍可拖动。\n\t */\n\tsetActivityPanelWidth(width: number | \"max\"): 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 * Copy an image to the system clipboard. Takes a `data:image/...;base64,`\n\t * URL and goes through the native clipboard, so it does not depend on the\n\t * renderer's `ClipboardItem` support. No permission required — the plugin\n\t * can only write what it already rendered.\n\t */\n\tcopyImage(dataUrl: string): Promise<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.map

@@ -1 +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"]}
+{"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\";\nimport type { PluginShortcutScopeContribution } from \"./shortcuts.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 * Register a keyboard shortcut scope on the host's shared ShortcutScopeStack\n\t * (same path as host UI: modal > overlay > surface > app). Needs\n\t * `ui.shortcuts.register`. Plugins cannot use kind `\"app\"` (reserved for\n\t * host-configurable global actions). Prefer {@link usePluginShortcutScope}\n\t * from React components with a module-captured `registerShortcutScope`.\n\t */\n\tregisterShortcutScope(contribution: PluginShortcutScopeContribution): 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 * 直接设置活动面板宽度：像素值，或 `\"max\"` 表示当前窗口下的最大宽度（宿主仍\n\t * 会夹到自己的 min/max 内，必要时自动收起侧边栏）。\n\t *\n\t * 与 `openActivityTab(id, { width })` 的区别：那里的宽度只在标签卡首次 attach\n\t * 时生效（避免 activate 重放覆盖用户手拖的宽度）；这个是命令式的，每次调用都\n\t * 生效，供插件在自己的标签卡被激活、进入某种视图时按需调整。用户随后仍可拖动。\n\t */\n\tsetActivityPanelWidth(width: number | \"max\"): 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 * Copy an image to the system clipboard. Takes a `data:image/...;base64,`\n\t * URL and goes through the native clipboard, so it does not depend on the\n\t * renderer's `ClipboardItem` support. No permission required — the plugin\n\t * can only write what it already rendered.\n\t */\n\tcopyImage(dataUrl: string): Promise<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.1.0",
+	"version": "0.1.1",
 	"type": "module",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",