@vetta-org/plugin-sdk 0.1.1 → 0.3.0

package/dist/artifacts.d.ts

@@ -0,0 +1,31 @@
+export interface PluginArtifactRef {
+    id: string;
+    mimeType: string;
+    sizeBytes: number;
+    lifetime: "temporary";
+    name?: string;
+}
+export type PluginArtifactDestination = {
+    type: "plugin-blob";
+    blobId?: string;
+} | {
+    type: "workspace-file";
+    path: string;
+};
+export type PluginPersistedArtifact = {
+    type: "plugin-blob";
+    blobId: string;
+    url: string;
+    mimeType: string;
+    sizeBytes: number;
+} | {
+    type: "workspace-file";
+    path: string;
+    mimeType: string;
+    sizeBytes: number;
+};
+export interface PluginArtifactsApi {
+    persist(artifact: PluginArtifactRef | string, destination: PluginArtifactDestination): Promise<PluginPersistedArtifact>;
+    release(artifact: PluginArtifactRef | string): Promise<void>;
+}
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,WAAW,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,yBAAyB,GAClC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C,MAAM,MAAM,uBAAuB,GAChC;IACA,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACjB,GACD;IACA,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACjB,CAAC;AAEL,MAAM,WAAW,kBAAkB;IAClC,OAAO,CACN,QAAQ,EAAE,iBAAiB,GAAG,MAAM,EACpC,WAAW,EAAE,yBAAyB,GACpC,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACpC,OAAO,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D","sourcesContent":["export interface PluginArtifactRef {\n\tid: string;\n\tmimeType: string;\n\tsizeBytes: number;\n\tlifetime: \"temporary\";\n\tname?: string;\n}\n\nexport type PluginArtifactDestination =\n\t| { type: \"plugin-blob\"; blobId?: string }\n\t| { type: \"workspace-file\"; path: string };\n\nexport type PluginPersistedArtifact =\n\t| {\n\t\t\ttype: \"plugin-blob\";\n\t\t\tblobId: string;\n\t\t\turl: string;\n\t\t\tmimeType: string;\n\t\t\tsizeBytes: number;\n\t  }\n\t| {\n\t\t\ttype: \"workspace-file\";\n\t\t\tpath: string;\n\t\t\tmimeType: string;\n\t\t\tsizeBytes: number;\n\t  };\n\nexport interface PluginArtifactsApi {\n\tpersist(\n\t\tartifact: PluginArtifactRef | string,\n\t\tdestination: PluginArtifactDestination,\n\t): Promise<PluginPersistedArtifact>;\n\trelease(artifact: PluginArtifactRef | string): Promise<void>;\n}\n"]}

package/dist/artifacts.js

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

package/dist/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"","sourcesContent":["export interface PluginArtifactRef {\n\tid: string;\n\tmimeType: string;\n\tsizeBytes: number;\n\tlifetime: \"temporary\";\n\tname?: string;\n}\n\nexport type PluginArtifactDestination =\n\t| { type: \"plugin-blob\"; blobId?: string }\n\t| { type: \"workspace-file\"; path: string };\n\nexport type PluginPersistedArtifact =\n\t| {\n\t\t\ttype: \"plugin-blob\";\n\t\t\tblobId: string;\n\t\t\turl: string;\n\t\t\tmimeType: string;\n\t\t\tsizeBytes: number;\n\t  }\n\t| {\n\t\t\ttype: \"workspace-file\";\n\t\t\tpath: string;\n\t\t\tmimeType: string;\n\t\t\tsizeBytes: number;\n\t  };\n\nexport interface PluginArtifactsApi {\n\tpersist(\n\t\tartifact: PluginArtifactRef | string,\n\t\tdestination: PluginArtifactDestination,\n\t): Promise<PluginPersistedArtifact>;\n\trelease(artifact: PluginArtifactRef | string): Promise<void>;\n}\n"]}

package/dist/browser.d.ts

@@ -0,0 +1,119 @@
+export type PluginBrowserSource = "managed" | "attach";
+export type PluginBrowserRuntimePhase = "checking" | "missing" | "outdated" | "browser-missing" | "ready" | "installing-runtime" | "installing-browser" | "error";
+export interface PluginBrowserRuntimeStatus {
+    phase: PluginBrowserRuntimePhase;
+    version?: string;
+    message?: string;
+    recentOutput?: string;
+}
+export type PluginBrowserProfile = {
+    type: "ephemeral";
+} | {
+    type: "persistent";
+    id: string;
+};
+export type PluginBrowserSessionStatus = "starting" | "ready" | "closed" | "error";
+export interface PluginBrowserSession {
+    id: string;
+    source: PluginBrowserSource;
+    profile: PluginBrowserProfile;
+    headed: boolean;
+    status: PluginBrowserSessionStatus;
+    createdAt: number;
+}
+export interface PluginBrowserSessionOptions {
+    source?: PluginBrowserSource;
+    profile?: PluginBrowserProfile;
+    headed?: boolean;
+    /** Optional subset of plugin.json browser.allowedHosts for this session. */
+    allowedHosts?: string[];
+}
+export interface PluginBrowserPageState {
+    sessionId: string;
+    revision: number;
+    url: string;
+    title?: string;
+}
+export interface PluginBrowserSnapshot extends PluginBrowserPageState {
+    content: string;
+}
+export interface PluginBrowserTextContent {
+    sessionId: string;
+    url: string;
+    title?: string;
+    text: string;
+    truncated: boolean;
+}
+export interface PluginBrowserScreenshot {
+    sessionId: string;
+    revision: number;
+    dataUrl: string;
+}
+export type PluginBrowserAction = {
+    type: "click";
+    target: string;
+} | {
+    type: "fill";
+    target: string;
+    value: string;
+} | {
+    type: "type";
+    target: string;
+    value: string;
+} | {
+    type: "select";
+    target: string;
+    value: string;
+} | {
+    type: "check";
+    target: string;
+    checked: boolean;
+} | {
+    type: "press";
+    key: string;
+} | {
+    type: "scroll";
+    direction: "up" | "down" | "left" | "right";
+    amount?: number;
+} | {
+    type: "wait";
+    milliseconds?: number;
+    target?: string;
+} | {
+    type: "back";
+} | {
+    type: "reload";
+};
+export interface PluginBrowserActionResult extends PluginBrowserPageState {
+    output?: string;
+}
+export interface PluginBrowserApi {
+    /**
+     * Open a URL in the host's built-in browser panel. This is a display-only
+     * operation; it does not grant page content access or automation privileges.
+     */
+    open(url: string): void;
+    runtime: {
+        status(): Promise<PluginBrowserRuntimeStatus>;
+        install(step: "runtime" | "browser"): Promise<PluginBrowserRuntimeStatus>;
+    };
+    sessions: {
+        create(options?: PluginBrowserSessionOptions): Promise<PluginBrowserSession>;
+        get(sessionId: string): Promise<PluginBrowserSession>;
+        close(sessionId: string): Promise<void>;
+    };
+    navigate(sessionId: string, url: string): Promise<PluginBrowserPageState>;
+    snapshot(sessionId: string, options?: {
+        interactiveOnly?: boolean;
+    }): Promise<PluginBrowserSnapshot>;
+    readText(sessionId: string, options?: {
+        maxChars?: number;
+    }): Promise<PluginBrowserTextContent>;
+    screenshot(sessionId: string, options?: {
+        fullPage?: boolean;
+    }): Promise<PluginBrowserScreenshot>;
+    act(sessionId: string, action: PluginBrowserAction, options?: {
+        snapshotRevision?: number;
+    }): Promise<PluginBrowserActionResult>;
+}
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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","sourcesContent":["export type PluginBrowserSource = \"managed\" | \"attach\";\nexport type PluginBrowserRuntimePhase =\n\t| \"checking\"\n\t| \"missing\"\n\t| \"outdated\"\n\t| \"browser-missing\"\n\t| \"ready\"\n\t| \"installing-runtime\"\n\t| \"installing-browser\"\n\t| \"error\";\n\nexport interface PluginBrowserRuntimeStatus {\n\tphase: PluginBrowserRuntimePhase;\n\tversion?: string;\n\tmessage?: string;\n\trecentOutput?: string;\n}\n\nexport type PluginBrowserProfile = { type: \"ephemeral\" } | { type: \"persistent\"; id: string };\nexport type PluginBrowserSessionStatus = \"starting\" | \"ready\" | \"closed\" | \"error\";\n\nexport interface PluginBrowserSession {\n\tid: string;\n\tsource: PluginBrowserSource;\n\tprofile: PluginBrowserProfile;\n\theaded: boolean;\n\tstatus: PluginBrowserSessionStatus;\n\tcreatedAt: number;\n}\n\nexport interface PluginBrowserSessionOptions {\n\tsource?: PluginBrowserSource;\n\tprofile?: PluginBrowserProfile;\n\theaded?: boolean;\n\t/** Optional subset of plugin.json browser.allowedHosts for this session. */\n\tallowedHosts?: string[];\n}\n\nexport interface PluginBrowserPageState {\n\tsessionId: string;\n\trevision: number;\n\turl: string;\n\ttitle?: string;\n}\n\nexport interface PluginBrowserSnapshot extends PluginBrowserPageState {\n\tcontent: string;\n}\n\nexport interface PluginBrowserTextContent {\n\tsessionId: string;\n\turl: string;\n\ttitle?: string;\n\ttext: string;\n\ttruncated: boolean;\n}\n\nexport interface PluginBrowserScreenshot {\n\tsessionId: string;\n\trevision: number;\n\tdataUrl: string;\n}\n\nexport type PluginBrowserAction =\n\t| { type: \"click\"; target: string }\n\t| { type: \"fill\"; target: string; value: string }\n\t| { type: \"type\"; target: string; value: string }\n\t| { type: \"select\"; target: string; value: string }\n\t| { type: \"check\"; target: string; checked: boolean }\n\t| { type: \"press\"; key: string }\n\t| { type: \"scroll\"; direction: \"up\" | \"down\" | \"left\" | \"right\"; amount?: number }\n\t| { type: \"wait\"; milliseconds?: number; target?: string }\n\t| { type: \"back\" }\n\t| { type: \"reload\" };\n\nexport interface PluginBrowserActionResult extends PluginBrowserPageState {\n\toutput?: string;\n}\n\nexport interface PluginBrowserApi {\n\t/**\n\t * Open a URL in the host's built-in browser panel. This is a display-only\n\t * operation; it does not grant page content access or automation privileges.\n\t */\n\topen(url: string): void;\n\truntime: {\n\t\tstatus(): Promise<PluginBrowserRuntimeStatus>;\n\t\tinstall(step: \"runtime\" | \"browser\"): Promise<PluginBrowserRuntimeStatus>;\n\t};\n\tsessions: {\n\t\tcreate(options?: PluginBrowserSessionOptions): Promise<PluginBrowserSession>;\n\t\tget(sessionId: string): Promise<PluginBrowserSession>;\n\t\tclose(sessionId: string): Promise<void>;\n\t};\n\tnavigate(sessionId: string, url: string): Promise<PluginBrowserPageState>;\n\tsnapshot(sessionId: string, options?: { interactiveOnly?: boolean }): Promise<PluginBrowserSnapshot>;\n\treadText(sessionId: string, options?: { maxChars?: number }): Promise<PluginBrowserTextContent>;\n\tscreenshot(sessionId: string, options?: { fullPage?: boolean }): Promise<PluginBrowserScreenshot>;\n\tact(\n\t\tsessionId: string,\n\t\taction: PluginBrowserAction,\n\t\toptions?: { snapshotRevision?: number },\n\t): Promise<PluginBrowserActionResult>;\n}\n"]}

package/dist/browser.js

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

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"","sourcesContent":["export type PluginBrowserSource = \"managed\" | \"attach\";\nexport type PluginBrowserRuntimePhase =\n\t| \"checking\"\n\t| \"missing\"\n\t| \"outdated\"\n\t| \"browser-missing\"\n\t| \"ready\"\n\t| \"installing-runtime\"\n\t| \"installing-browser\"\n\t| \"error\";\n\nexport interface PluginBrowserRuntimeStatus {\n\tphase: PluginBrowserRuntimePhase;\n\tversion?: string;\n\tmessage?: string;\n\trecentOutput?: string;\n}\n\nexport type PluginBrowserProfile = { type: \"ephemeral\" } | { type: \"persistent\"; id: string };\nexport type PluginBrowserSessionStatus = \"starting\" | \"ready\" | \"closed\" | \"error\";\n\nexport interface PluginBrowserSession {\n\tid: string;\n\tsource: PluginBrowserSource;\n\tprofile: PluginBrowserProfile;\n\theaded: boolean;\n\tstatus: PluginBrowserSessionStatus;\n\tcreatedAt: number;\n}\n\nexport interface PluginBrowserSessionOptions {\n\tsource?: PluginBrowserSource;\n\tprofile?: PluginBrowserProfile;\n\theaded?: boolean;\n\t/** Optional subset of plugin.json browser.allowedHosts for this session. */\n\tallowedHosts?: string[];\n}\n\nexport interface PluginBrowserPageState {\n\tsessionId: string;\n\trevision: number;\n\turl: string;\n\ttitle?: string;\n}\n\nexport interface PluginBrowserSnapshot extends PluginBrowserPageState {\n\tcontent: string;\n}\n\nexport interface PluginBrowserTextContent {\n\tsessionId: string;\n\turl: string;\n\ttitle?: string;\n\ttext: string;\n\ttruncated: boolean;\n}\n\nexport interface PluginBrowserScreenshot {\n\tsessionId: string;\n\trevision: number;\n\tdataUrl: string;\n}\n\nexport type PluginBrowserAction =\n\t| { type: \"click\"; target: string }\n\t| { type: \"fill\"; target: string; value: string }\n\t| { type: \"type\"; target: string; value: string }\n\t| { type: \"select\"; target: string; value: string }\n\t| { type: \"check\"; target: string; checked: boolean }\n\t| { type: \"press\"; key: string }\n\t| { type: \"scroll\"; direction: \"up\" | \"down\" | \"left\" | \"right\"; amount?: number }\n\t| { type: \"wait\"; milliseconds?: number; target?: string }\n\t| { type: \"back\" }\n\t| { type: \"reload\" };\n\nexport interface PluginBrowserActionResult extends PluginBrowserPageState {\n\toutput?: string;\n}\n\nexport interface PluginBrowserApi {\n\t/**\n\t * Open a URL in the host's built-in browser panel. This is a display-only\n\t * operation; it does not grant page content access or automation privileges.\n\t */\n\topen(url: string): void;\n\truntime: {\n\t\tstatus(): Promise<PluginBrowserRuntimeStatus>;\n\t\tinstall(step: \"runtime\" | \"browser\"): Promise<PluginBrowserRuntimeStatus>;\n\t};\n\tsessions: {\n\t\tcreate(options?: PluginBrowserSessionOptions): Promise<PluginBrowserSession>;\n\t\tget(sessionId: string): Promise<PluginBrowserSession>;\n\t\tclose(sessionId: string): Promise<void>;\n\t};\n\tnavigate(sessionId: string, url: string): Promise<PluginBrowserPageState>;\n\tsnapshot(sessionId: string, options?: { interactiveOnly?: boolean }): Promise<PluginBrowserSnapshot>;\n\treadText(sessionId: string, options?: { maxChars?: number }): Promise<PluginBrowserTextContent>;\n\tscreenshot(sessionId: string, options?: { fullPage?: boolean }): Promise<PluginBrowserScreenshot>;\n\tact(\n\t\tsessionId: string,\n\t\taction: PluginBrowserAction,\n\t\toptions?: { snapshotRevision?: number },\n\t): Promise<PluginBrowserActionResult>;\n}\n"]}

package/dist/capture.d.ts

@@ -0,0 +1,64 @@
+export interface PluginOffscreenCaptureOptions {
+    /** 目标页面地址，仅允许 http(s)（如插件自己 spawn 的本地 dev server）。 */
+    url: string;
+    /** 视口宽度（CSS 像素）。 */
+    width: number;
+    /** 视口高度（CSS 像素）。 */
+    height: number;
+    /**
+     * 复用键。同 key 的请求串行执行并复用同一个离屏窗口：url 未变时跳过重新加载，
+     * SPA 页面可用 `prepareScript` 做客户端路由切换，省掉整页加载。省略则本次
+     * 请求独占一个窗口、用完即毁。窗口闲置一段时间后由宿主自动回收。
+     */
+    sessionKey?: string;
+    /** 页面加载完成（或复用窗口）后注入执行的脚本，如 postMessage 切路由。 */
+    prepareScript?: string;
+    /**
+     * 就绪表达式。宿主轮询它直到真值才截图，用于等待页面自己的「渲染完成」信号
+     * （如 `window.__ready === true`）。省略则加载完成即视为就绪。
+     */
+    readyExpression?: string;
+    /** 就绪后的静置时间（毫秒），等图片解码、过渡动画落定。 */
+    settleMs?: number;
+    /**
+     * 探针表达式。在**截图的同一时刻**（就绪 + 静置之后）对页面求值，结果经
+     * `JSON.stringify` 回传到 `PluginOffscreenCaptureResult.probe`。
+     *
+     * 存在的理由：渲染是这条链上最贵的一步，而位图是它最难用的产物——「这段文字换了
+     * 行没有」「这两条边对齐没有」在 DOM 里是确定的度量，在图里只能靠看。同一次渲染
+     * 顺带把度量取回来，比让调用方再渲染一次或让模型看图去猜都更可靠。
+     *
+     * 求值失败（抛错、返回不可序列化的值）不影响截图：`probe` 为 `undefined`，
+     * 位图照常返回。探针是搭车的附加信息，不是截图的前置条件。
+     */
+    probeScript?: string;
+    /** 整体超时（毫秒，含加载与就绪等待），宿主按自身上限收紧。 */
+    timeoutMs?: number;
+    format?: "jpeg" | "png";
+    /** 仅 jpeg 生效，0–1。 */
+    quality?: number;
+}
+export interface PluginOffscreenCaptureResult {
+    dataUrl: string;
+    /**
+     * 实际生效的设备像素比：位图物理像素 = CSS 尺寸 × 此值。离屏窗口跟随主显示器
+     * 的缩放（Retina 为 2），插件不可指定——按需自行缩放位图。
+     */
+    scaleFactor: number;
+    /**
+     * `probeScript` 的求值结果，经 JSON 往返。没传探针、求值抛错或结果不可序列化时
+     * 为 `undefined`——调用方无法从这里区分三者，探针本就不该承担错误报告。
+     */
+    probe?: unknown;
+}
+/**
+ * 主进程离屏窗口截图。与 DOM 克隆类方案（html-to-image 等）不同，这里走真实的
+ * Chromium 渲染管线，产出与页面在屏显示逐像素一致的位图，不存在克隆重排带来的
+ * 断行/亚像素偏差。需要 `capture.offscreen` 权限。
+ */
+export interface PluginCaptureApi {
+    offscreen(options: PluginOffscreenCaptureOptions): Promise<PluginOffscreenCaptureResult>;
+    /** 释放 sessionKey 对应的离屏窗口；下次同 key 请求会重新加载页面。幂等。 */
+    releaseOffscreen(sessionKey: string): Promise<void>;
+}
+//# sourceMappingURL=capture.d.ts.map

package/dist/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,6BAA6B;IAC7C,gGAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,sCAAoB;IACpB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qGAA+C;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qFAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2FAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,iCAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,4BAA4B;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAChC,SAAS,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;IACzF,sGAAkD;IAClD,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD","sourcesContent":["export interface PluginOffscreenCaptureOptions {\n\t/** 目标页面地址，仅允许 http(s)（如插件自己 spawn 的本地 dev server）。 */\n\turl: string;\n\t/** 视口宽度（CSS 像素）。 */\n\twidth: number;\n\t/** 视口高度（CSS 像素）。 */\n\theight: number;\n\t/**\n\t * 复用键。同 key 的请求串行执行并复用同一个离屏窗口：url 未变时跳过重新加载，\n\t * SPA 页面可用 `prepareScript` 做客户端路由切换，省掉整页加载。省略则本次\n\t * 请求独占一个窗口、用完即毁。窗口闲置一段时间后由宿主自动回收。\n\t */\n\tsessionKey?: string;\n\t/** 页面加载完成（或复用窗口）后注入执行的脚本，如 postMessage 切路由。 */\n\tprepareScript?: string;\n\t/**\n\t * 就绪表达式。宿主轮询它直到真值才截图，用于等待页面自己的「渲染完成」信号\n\t * （如 `window.__ready === true`）。省略则加载完成即视为就绪。\n\t */\n\treadyExpression?: string;\n\t/** 就绪后的静置时间（毫秒），等图片解码、过渡动画落定。 */\n\tsettleMs?: number;\n\t/**\n\t * 探针表达式。在**截图的同一时刻**（就绪 + 静置之后）对页面求值，结果经\n\t * `JSON.stringify` 回传到 `PluginOffscreenCaptureResult.probe`。\n\t *\n\t * 存在的理由：渲染是这条链上最贵的一步，而位图是它最难用的产物——「这段文字换了\n\t * 行没有」「这两条边对齐没有」在 DOM 里是确定的度量，在图里只能靠看。同一次渲染\n\t * 顺带把度量取回来，比让调用方再渲染一次或让模型看图去猜都更可靠。\n\t *\n\t * 求值失败（抛错、返回不可序列化的值）不影响截图：`probe` 为 `undefined`，\n\t * 位图照常返回。探针是搭车的附加信息，不是截图的前置条件。\n\t */\n\tprobeScript?: string;\n\t/** 整体超时（毫秒，含加载与就绪等待），宿主按自身上限收紧。 */\n\ttimeoutMs?: number;\n\tformat?: \"jpeg\" | \"png\";\n\t/** 仅 jpeg 生效，0–1。 */\n\tquality?: number;\n}\n\nexport interface PluginOffscreenCaptureResult {\n\tdataUrl: string;\n\t/**\n\t * 实际生效的设备像素比：位图物理像素 = CSS 尺寸 × 此值。离屏窗口跟随主显示器\n\t * 的缩放（Retina 为 2），插件不可指定——按需自行缩放位图。\n\t */\n\tscaleFactor: number;\n\t/**\n\t * `probeScript` 的求值结果，经 JSON 往返。没传探针、求值抛错或结果不可序列化时\n\t * 为 `undefined`——调用方无法从这里区分三者，探针本就不该承担错误报告。\n\t */\n\tprobe?: unknown;\n}\n\n/**\n * 主进程离屏窗口截图。与 DOM 克隆类方案（html-to-image 等）不同，这里走真实的\n * Chromium 渲染管线，产出与页面在屏显示逐像素一致的位图，不存在克隆重排带来的\n * 断行/亚像素偏差。需要 `capture.offscreen` 权限。\n */\nexport interface PluginCaptureApi {\n\toffscreen(options: PluginOffscreenCaptureOptions): Promise<PluginOffscreenCaptureResult>;\n\t/** 释放 sessionKey 对应的离屏窗口；下次同 key 请求会重新加载页面。幂等。 */\n\treleaseOffscreen(sessionKey: string): Promise<void>;\n}\n"]}

package/dist/capture.js

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

package/dist/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"","sourcesContent":["export interface PluginOffscreenCaptureOptions {\n\t/** 目标页面地址，仅允许 http(s)（如插件自己 spawn 的本地 dev server）。 */\n\turl: string;\n\t/** 视口宽度（CSS 像素）。 */\n\twidth: number;\n\t/** 视口高度（CSS 像素）。 */\n\theight: number;\n\t/**\n\t * 复用键。同 key 的请求串行执行并复用同一个离屏窗口：url 未变时跳过重新加载，\n\t * SPA 页面可用 `prepareScript` 做客户端路由切换，省掉整页加载。省略则本次\n\t * 请求独占一个窗口、用完即毁。窗口闲置一段时间后由宿主自动回收。\n\t */\n\tsessionKey?: string;\n\t/** 页面加载完成（或复用窗口）后注入执行的脚本，如 postMessage 切路由。 */\n\tprepareScript?: string;\n\t/**\n\t * 就绪表达式。宿主轮询它直到真值才截图，用于等待页面自己的「渲染完成」信号\n\t * （如 `window.__ready === true`）。省略则加载完成即视为就绪。\n\t */\n\treadyExpression?: string;\n\t/** 就绪后的静置时间（毫秒），等图片解码、过渡动画落定。 */\n\tsettleMs?: number;\n\t/**\n\t * 探针表达式。在**截图的同一时刻**（就绪 + 静置之后）对页面求值，结果经\n\t * `JSON.stringify` 回传到 `PluginOffscreenCaptureResult.probe`。\n\t *\n\t * 存在的理由：渲染是这条链上最贵的一步，而位图是它最难用的产物——「这段文字换了\n\t * 行没有」「这两条边对齐没有」在 DOM 里是确定的度量，在图里只能靠看。同一次渲染\n\t * 顺带把度量取回来，比让调用方再渲染一次或让模型看图去猜都更可靠。\n\t *\n\t * 求值失败（抛错、返回不可序列化的值）不影响截图：`probe` 为 `undefined`，\n\t * 位图照常返回。探针是搭车的附加信息，不是截图的前置条件。\n\t */\n\tprobeScript?: string;\n\t/** 整体超时（毫秒，含加载与就绪等待），宿主按自身上限收紧。 */\n\ttimeoutMs?: number;\n\tformat?: \"jpeg\" | \"png\";\n\t/** 仅 jpeg 生效，0–1。 */\n\tquality?: number;\n}\n\nexport interface PluginOffscreenCaptureResult {\n\tdataUrl: string;\n\t/**\n\t * 实际生效的设备像素比：位图物理像素 = CSS 尺寸 × 此值。离屏窗口跟随主显示器\n\t * 的缩放（Retina 为 2），插件不可指定——按需自行缩放位图。\n\t */\n\tscaleFactor: number;\n\t/**\n\t * `probeScript` 的求值结果，经 JSON 往返。没传探针、求值抛错或结果不可序列化时\n\t * 为 `undefined`——调用方无法从这里区分三者，探针本就不该承担错误报告。\n\t */\n\tprobe?: unknown;\n}\n\n/**\n * 主进程离屏窗口截图。与 DOM 克隆类方案（html-to-image 等）不同，这里走真实的\n * Chromium 渲染管线，产出与页面在屏显示逐像素一致的位图，不存在克隆重排带来的\n * 断行/亚像素偏差。需要 `capture.offscreen` 权限。\n */\nexport interface PluginCaptureApi {\n\toffscreen(options: PluginOffscreenCaptureOptions): Promise<PluginOffscreenCaptureResult>;\n\t/** 释放 sessionKey 对应的离屏窗口；下次同 key 请求会重新加载页面。幂等。 */\n\treleaseOffscreen(sessionKey: string): Promise<void>;\n}\n"]}

package/dist/cli-provider.d.ts

@@ -0,0 +1,18 @@
+import type { PluginCommandRunOptions, PluginCommandRunResult, PluginCommandSpawnHandle, PluginCommandSpawnOptions } from "./command.js";
+import type { Disposable } from "./disposable.js";
+export type PluginCliProviderPhase = "disabled" | "checking" | "installing" | "verifying" | "ready" | "failed";
+export interface PluginCliProviderStatus {
+    providerId: string;
+    phase: PluginCliProviderPhase;
+    message?: string;
+    recentOutput: string;
+}
+/** Host-managed CLI dependency declared by `plugin.json#providers.cli`. */
+export interface PluginCliProviderApi {
+    getStatus(providerId: string): Promise<PluginCliProviderStatus>;
+    onStatusChanged(listener: (status: PluginCliProviderStatus) => void): Disposable;
+    retry(providerId: string): Promise<void>;
+    run(providerId: string, args?: string[], options?: PluginCommandRunOptions): Promise<PluginCommandRunResult>;
+    spawn(providerId: string, args?: string[], options?: PluginCommandSpawnOptions): Promise<PluginCommandSpawnHandle>;
+}
+//# sourceMappingURL=cli-provider.d.ts.map

package/dist/cli-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-provider.d.ts","sourceRoot":"","sources":["../src/cli-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/G,MAAM,WAAW,uBAAuB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,sBAAsB,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACpC,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAChE,eAAe,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,GAAG,UAAU,CAAC;IACjF,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,GAAG,CACF,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,OAAO,CAAC,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACnC,KAAK,CACJ,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,OAAO,CAAC,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACrC","sourcesContent":["import type {\n\tPluginCommandRunOptions,\n\tPluginCommandRunResult,\n\tPluginCommandSpawnHandle,\n\tPluginCommandSpawnOptions,\n} from \"./command.js\";\nimport type { Disposable } from \"./disposable.js\";\n\nexport type PluginCliProviderPhase = \"disabled\" | \"checking\" | \"installing\" | \"verifying\" | \"ready\" | \"failed\";\n\nexport interface PluginCliProviderStatus {\n\tproviderId: string;\n\tphase: PluginCliProviderPhase;\n\tmessage?: string;\n\trecentOutput: string;\n}\n\n/** Host-managed CLI dependency declared by `plugin.json#providers.cli`. */\nexport interface PluginCliProviderApi {\n\tgetStatus(providerId: string): Promise<PluginCliProviderStatus>;\n\tonStatusChanged(listener: (status: PluginCliProviderStatus) => void): Disposable;\n\tretry(providerId: string): Promise<void>;\n\trun(\n\t\tproviderId: string,\n\t\targs?: string[],\n\t\toptions?: PluginCommandRunOptions,\n\t): Promise<PluginCommandRunResult>;\n\tspawn(\n\t\tproviderId: string,\n\t\targs?: string[],\n\t\toptions?: PluginCommandSpawnOptions,\n\t): Promise<PluginCommandSpawnHandle>;\n}\n"]}

package/dist/cli-provider.js

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

package/dist/cli-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-provider.js","sourceRoot":"","sources":["../src/cli-provider.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n\tPluginCommandRunOptions,\n\tPluginCommandRunResult,\n\tPluginCommandSpawnHandle,\n\tPluginCommandSpawnOptions,\n} from \"./command.js\";\nimport type { Disposable } from \"./disposable.js\";\n\nexport type PluginCliProviderPhase = \"disabled\" | \"checking\" | \"installing\" | \"verifying\" | \"ready\" | \"failed\";\n\nexport interface PluginCliProviderStatus {\n\tproviderId: string;\n\tphase: PluginCliProviderPhase;\n\tmessage?: string;\n\trecentOutput: string;\n}\n\n/** Host-managed CLI dependency declared by `plugin.json#providers.cli`. */\nexport interface PluginCliProviderApi {\n\tgetStatus(providerId: string): Promise<PluginCliProviderStatus>;\n\tonStatusChanged(listener: (status: PluginCliProviderStatus) => void): Disposable;\n\tretry(providerId: string): Promise<void>;\n\trun(\n\t\tproviderId: string,\n\t\targs?: string[],\n\t\toptions?: PluginCommandRunOptions,\n\t): Promise<PluginCommandRunResult>;\n\tspawn(\n\t\tproviderId: string,\n\t\targs?: string[],\n\t\toptions?: PluginCommandSpawnOptions,\n\t): Promise<PluginCommandSpawnHandle>;\n}\n"]}

package/dist/context.d.ts

@@ -1,27 +1,47 @@
 import type { PluginAgentApi } from "./agent.js";
+import type { PluginAiApi } from "./ai.js";
 import type { PluginAppActionsApi } from "./app-actions.js";
+import type { PluginArtifactsApi } from "./artifacts.js";
+import type { PluginBrowserApi } from "./browser.js";
+import type { PluginCaptureApi } from "./capture.js";
 import type { PluginCommandApi } from "./command.js";
+import type { PluginCliProviderApi } from "./cli-provider.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 { PluginGatewayApi } from "./gateway.js";
 import type { PluginI18nApi } from "./i18n.js";
+import type { PluginJobsApi } from "./jobs.js";
+import type { PluginMediaApi } from "./media.js";
+import type { OcrClient } from "./ocr.js";
+import type { PluginModelsApi } from "./models.js";
 import type { PluginNetworkApi } from "./network.js";
 import type { PluginOfficialApi } from "./official.js";
 import type { PluginPermission } from "./permissions.js";
-import type { PluginSettingsApi } from "./settings.js";
+import type { PluginSecretsApi } from "./secrets.js";
+import type { PluginServiceApi } from "./service-provider.js";
 import type { PluginStorageApi } from "./storage.js";
 import type { PluginUiApi } from "./ui.js";
 export interface PluginPermissionApi {
     has(permission: PluginPermission): boolean;
     require(permission: PluginPermission): void;
 }
-/** 工作模式（agent_mode 轴，见 ADR-0046）。宿主 Work/Coding，未来可能扩展。 */
-export type AgentMode = "work" | "coding";
+/**
+ * 工作模式 id。合法值由宿主的模式注册表定义（ADR-0071），插件不应硬编码枚举；
+ * 需要区分模式时按 id 字符串比较，未知 id 一律按通用处理。
+ */
+export type AgentMode = string;
 export interface PluginContext {
     plugin: {
         id: string;
         version: string;
+        /**
+         * Host-resolved brand icon from `plugin.json#icon` (if declared).
+         * Opaque string for `<img src>` / Iconify — plugins must not invent
+         * host protocols; use this or omit Activity Tab `icon` to inherit it.
+         */
+        iconUrl?: string;
     };
     permissions: PluginPermissionApi;
     ui: PluginUiApi;
@@ -29,20 +49,52 @@ export interface PluginContext {
     conversation: PluginConversationApi;
     agent: PluginAgentApi;
     appActions: PluginAppActionsApi;
+    ai: PluginAiApi;
     official: PluginOfficialApi;
     fs: PluginFsApi;
     command: PluginCommandApi;
+    cliProviders: PluginCliProviderApi;
+    /** Plugin-provisioned, host-managed local services declared by `plugin.json#providers.services`. */
+    services: PluginServiceApi;
+    /** Explicitly permissioned model provider owned by this plugin's id namespace. */
+    models: PluginModelsApi;
+    media: PluginMediaApi;
+    ocr: OcrClient;
+    jobs: PluginJobsApi;
+    artifacts: PluginArtifactsApi;
+    /** 主进程离屏窗口截图（`capture.offscreen` 权限）。旧宿主上为 `undefined`，使用前判空。 */
+    capture?: PluginCaptureApi;
+    /** 宿主管理的浏览器能力；各具体方法会根据插件权限单独校验。 */
+    browser: PluginBrowserApi;
     network: PluginNetworkApi;
+    /**
+     * Vetta 服务端网关调用（ADR-0056）。**仅内置 official 插件可用**，
+     * 第三方插件读到 `undefined`，故使用前必须判空。
+     */
+    gateway?: PluginGatewayApi;
     storage: PluginStorageApi;
-    settings: PluginSettingsApi;
+    /** Encrypted per-plugin secret storage (`secrets.read` / `secrets.write`). */
+    secrets: PluginSecretsApi;
     i18n: PluginI18nApi;
-    /** 当前工作模式（agent_mode 轴）。开发者据此做模式定制。见 ADR-0046。 */
+    /**
+     * 当前的**新会话默认工作模式**（agent_mode 轴，见 ADR-0046 及其 2026-08 修订）。
+     *
+     * 工作模式只在会话创建时固化，之后会话内不可变，因此这里读到的是用户此刻的设置值，
+     * **不是**某个已存在会话正在使用的模式，不要用它推断进行中的会话。
+     * 模式也不再隐藏任何插件能力，只适合做展示层的软性定制，不要据此隐藏功能入口。
+     */
     getAgentMode(): AgentMode;
-    /** 订阅工作模式变更（纯全局实时切换）。返回 Disposable 取消订阅。 */
+    /** 订阅默认工作模式变更（用户改设置时触发）。返回 Disposable 取消订阅。 */
     onAgentModeChanged(listener: (mode: AgentMode) => void): Disposable;
 }
+export type PluginActivationCleanup = Disposable | (() => void | Promise<void>);
 export interface PluginDefinition {
-    activate(ctx: PluginContext): void | Promise<void>;
+    /**
+     * Activate one plugin instance. Returning a cleanup binds resource ownership to
+     * this specific activation, including overlapping hot-reload activations.
+     */
+    activate(ctx: PluginContext): void | PluginActivationCleanup | Promise<void | PluginActivationCleanup>;
+    /** Legacy module-level cleanup. Prefer an activation-scoped cleanup return value. */
     deactivate?(): void | Promise<void>;
 }
 export declare function definePlugin(plugin: PluginDefinition): PluginDefinition;

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,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"]}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PluginAgentApi } from \"./agent.js\";\nimport type { PluginAiApi } from \"./ai.js\";\nimport type { PluginAppActionsApi } from \"./app-actions.js\";\nimport type { PluginArtifactsApi } from \"./artifacts.js\";\nimport type { PluginBrowserApi } from \"./browser.js\";\nimport type { PluginCaptureApi } from \"./capture.js\";\nimport type { PluginCommandApi } from \"./command.js\";\nimport type { PluginCliProviderApi } from \"./cli-provider.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 { PluginGatewayApi } from \"./gateway.js\";\nimport type { PluginI18nApi } from \"./i18n.js\";\nimport type { PluginJobsApi } from \"./jobs.js\";\nimport type { PluginMediaApi } from \"./media.js\";\nimport type { OcrClient } from \"./ocr.js\";\nimport type { PluginModelsApi } from \"./models.js\";\nimport type { PluginNetworkApi } from \"./network.js\";\nimport type { PluginOfficialApi } from \"./official.js\";\nimport type { PluginPermission } from \"./permissions.js\";\nimport type { PluginSecretsApi } from \"./secrets.js\";\nimport type { PluginServiceApi } from \"./service-provider.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/**\n * 工作模式 id。合法值由宿主的模式注册表定义（ADR-0071），插件不应硬编码枚举；\n * 需要区分模式时按 id 字符串比较，未知 id 一律按通用处理。\n */\nexport type AgentMode = string;\n\nexport interface PluginContext {\n\tplugin: {\n\t\tid: string;\n\t\tversion: string;\n\t\t/**\n\t\t * Host-resolved brand icon from `plugin.json#icon` (if declared).\n\t\t * Opaque string for `<img src>` / Iconify — plugins must not invent\n\t\t * host protocols; use this or omit Activity Tab `icon` to inherit it.\n\t\t */\n\t\ticonUrl?: string;\n\t};\n\tpermissions: PluginPermissionApi;\n\tui: PluginUiApi;\n\tfileExplorer: PluginFileExplorerApi;\n\tconversation: PluginConversationApi;\n\tagent: PluginAgentApi;\n\tappActions: PluginAppActionsApi;\n\tai: PluginAiApi;\n\tofficial: PluginOfficialApi;\n\tfs: PluginFsApi;\n\tcommand: PluginCommandApi;\n\tcliProviders: PluginCliProviderApi;\n\t/** Plugin-provisioned, host-managed local services declared by `plugin.json#providers.services`. */\n\tservices: PluginServiceApi;\n\t/** Explicitly permissioned model provider owned by this plugin's id namespace. */\n\tmodels: PluginModelsApi;\n\tmedia: PluginMediaApi;\n\tocr: OcrClient;\n\tjobs: PluginJobsApi;\n\tartifacts: PluginArtifactsApi;\n\t/** 主进程离屏窗口截图（`capture.offscreen` 权限）。旧宿主上为 `undefined`，使用前判空。 */\n\tcapture?: PluginCaptureApi;\n\t/** 宿主管理的浏览器能力；各具体方法会根据插件权限单独校验。 */\n\tbrowser: PluginBrowserApi;\n\tnetwork: PluginNetworkApi;\n\t/**\n\t * Vetta 服务端网关调用（ADR-0056）。**仅内置 official 插件可用**，\n\t * 第三方插件读到 `undefined`，故使用前必须判空。\n\t */\n\tgateway?: PluginGatewayApi;\n\tstorage: PluginStorageApi;\n\t/** Encrypted per-plugin secret storage (`secrets.read` / `secrets.write`). */\n\tsecrets: PluginSecretsApi;\n\ti18n: PluginI18nApi;\n\t/**\n\t * 当前的**新会话默认工作模式**（agent_mode 轴，见 ADR-0046 及其 2026-08 修订）。\n\t *\n\t * 工作模式只在会话创建时固化，之后会话内不可变，因此这里读到的是用户此刻的设置值，\n\t * **不是**某个已存在会话正在使用的模式，不要用它推断进行中的会话。\n\t * 模式也不再隐藏任何插件能力，只适合做展示层的软性定制，不要据此隐藏功能入口。\n\t */\n\tgetAgentMode(): AgentMode;\n\t/** 订阅默认工作模式变更（用户改设置时触发）。返回 Disposable 取消订阅。 */\n\tonAgentModeChanged(listener: (mode: AgentMode) => void): Disposable;\n}\n\nexport type PluginActivationCleanup = Disposable | (() => void | Promise<void>);\n\nexport interface PluginDefinition {\n\t/**\n\t * Activate one plugin instance. Returning a cleanup binds resource ownership to\n\t * this specific activation, including overlapping hot-reload activations.\n\t */\n\tactivate(ctx: PluginContext): void | PluginActivationCleanup | Promise<void | PluginActivationCleanup>;\n\t/** Legacy module-level cleanup. Prefer an activation-scoped cleanup return value. */\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":"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"]}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAyGA,MAAM,UAAU,YAAY,CAAC,MAAwB,EAAoB;IACxE,OAAO,MAAM,CAAC;AAAA,CACd","sourcesContent":["import type { PluginAgentApi } from \"./agent.js\";\nimport type { PluginAiApi } from \"./ai.js\";\nimport type { PluginAppActionsApi } from \"./app-actions.js\";\nimport type { PluginArtifactsApi } from \"./artifacts.js\";\nimport type { PluginBrowserApi } from \"./browser.js\";\nimport type { PluginCaptureApi } from \"./capture.js\";\nimport type { PluginCommandApi } from \"./command.js\";\nimport type { PluginCliProviderApi } from \"./cli-provider.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 { PluginGatewayApi } from \"./gateway.js\";\nimport type { PluginI18nApi } from \"./i18n.js\";\nimport type { PluginJobsApi } from \"./jobs.js\";\nimport type { PluginMediaApi } from \"./media.js\";\nimport type { OcrClient } from \"./ocr.js\";\nimport type { PluginModelsApi } from \"./models.js\";\nimport type { PluginNetworkApi } from \"./network.js\";\nimport type { PluginOfficialApi } from \"./official.js\";\nimport type { PluginPermission } from \"./permissions.js\";\nimport type { PluginSecretsApi } from \"./secrets.js\";\nimport type { PluginServiceApi } from \"./service-provider.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/**\n * 工作模式 id。合法值由宿主的模式注册表定义（ADR-0071），插件不应硬编码枚举；\n * 需要区分模式时按 id 字符串比较，未知 id 一律按通用处理。\n */\nexport type AgentMode = string;\n\nexport interface PluginContext {\n\tplugin: {\n\t\tid: string;\n\t\tversion: string;\n\t\t/**\n\t\t * Host-resolved brand icon from `plugin.json#icon` (if declared).\n\t\t * Opaque string for `<img src>` / Iconify — plugins must not invent\n\t\t * host protocols; use this or omit Activity Tab `icon` to inherit it.\n\t\t */\n\t\ticonUrl?: string;\n\t};\n\tpermissions: PluginPermissionApi;\n\tui: PluginUiApi;\n\tfileExplorer: PluginFileExplorerApi;\n\tconversation: PluginConversationApi;\n\tagent: PluginAgentApi;\n\tappActions: PluginAppActionsApi;\n\tai: PluginAiApi;\n\tofficial: PluginOfficialApi;\n\tfs: PluginFsApi;\n\tcommand: PluginCommandApi;\n\tcliProviders: PluginCliProviderApi;\n\t/** Plugin-provisioned, host-managed local services declared by `plugin.json#providers.services`. */\n\tservices: PluginServiceApi;\n\t/** Explicitly permissioned model provider owned by this plugin's id namespace. */\n\tmodels: PluginModelsApi;\n\tmedia: PluginMediaApi;\n\tocr: OcrClient;\n\tjobs: PluginJobsApi;\n\tartifacts: PluginArtifactsApi;\n\t/** 主进程离屏窗口截图（`capture.offscreen` 权限）。旧宿主上为 `undefined`，使用前判空。 */\n\tcapture?: PluginCaptureApi;\n\t/** 宿主管理的浏览器能力；各具体方法会根据插件权限单独校验。 */\n\tbrowser: PluginBrowserApi;\n\tnetwork: PluginNetworkApi;\n\t/**\n\t * Vetta 服务端网关调用（ADR-0056）。**仅内置 official 插件可用**，\n\t * 第三方插件读到 `undefined`，故使用前必须判空。\n\t */\n\tgateway?: PluginGatewayApi;\n\tstorage: PluginStorageApi;\n\t/** Encrypted per-plugin secret storage (`secrets.read` / `secrets.write`). */\n\tsecrets: PluginSecretsApi;\n\ti18n: PluginI18nApi;\n\t/**\n\t * 当前的**新会话默认工作模式**（agent_mode 轴，见 ADR-0046 及其 2026-08 修订）。\n\t *\n\t * 工作模式只在会话创建时固化，之后会话内不可变，因此这里读到的是用户此刻的设置值，\n\t * **不是**某个已存在会话正在使用的模式，不要用它推断进行中的会话。\n\t * 模式也不再隐藏任何插件能力，只适合做展示层的软性定制，不要据此隐藏功能入口。\n\t */\n\tgetAgentMode(): AgentMode;\n\t/** 订阅默认工作模式变更（用户改设置时触发）。返回 Disposable 取消订阅。 */\n\tonAgentModeChanged(listener: (mode: AgentMode) => void): Disposable;\n}\n\nexport type PluginActivationCleanup = Disposable | (() => void | Promise<void>);\n\nexport interface PluginDefinition {\n\t/**\n\t * Activate one plugin instance. Returning a cleanup binds resource ownership to\n\t * this specific activation, including overlapping hot-reload activations.\n\t */\n\tactivate(ctx: PluginContext): void | PluginActivationCleanup | Promise<void | PluginActivationCleanup>;\n\t/** Legacy module-level cleanup. Prefer an activation-scoped cleanup return value. */\n\tdeactivate?(): void | Promise<void>;\n}\n\nexport function definePlugin(plugin: PluginDefinition): PluginDefinition {\n\treturn plugin;\n}\n"]}

package/dist/conversation.d.ts

@@ -24,6 +24,22 @@ export type ConversationEvent = {
 } | {
     type: "message-updated";
     delta: string;
+}
+/**
+ * 模型还在生成这次调用，流式参数已解析出新的键。
+ *
+ * 用它做「agent 正在动某个目标」这类实时 UI：`edit` / `write` 真正耗时的是
+ * 生成参数（一整份文件正文），执行只要几毫秒，等 `tool-call-start` 到手时活
+ * 已经干完了。目标路径通常是参数里的第一个键，所以能提前几秒拿到。
+ *
+ * 天然是残缺的：后面的键还没到，正在生成的那个键也不含在内。要权威全量参数
+ * 请用 `tool-call-start`。同一次调用会随键数增长发多次，不会逐 token 发。
+ */
+ | {
+    type: "tool-call-args";
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
 } | {
     type: "tool-call-start";
     toolCallId: string;
@@ -37,10 +53,58 @@ export type ConversationEvent = {
 } | {
     type: "conversation-changed";
     conversation: ConversationState;
+} | {
+    type: "queue-changed";
+    queue: ConversationQueueState;
 };
+/** 会话输入队列快照（ADR-0060）：排队中的 prompt 与暂停状态。 */
+export interface ConversationQueueState {
+    /** abort/error 后队列暂停；恢复由用户在宿主 UI 操作。 */
+    paused: boolean;
+    items: Array<{
+        id: string;
+        displayText: string;
+    }>;
+}
+/**
+ * sendPrompt 的回执（ADR-0060）。streaming 中发送不再静默排队：返回 `queued` 与
+ * 队列条目 id，插件可结合 `queue-changed` 事件呈现「已排队/已发出/被移除」状态。
+ */
+export interface SendPromptResult {
+    status: "sent" | "queued" | "failed";
+    error?: {
+        message: string;
+    };
+    queueItemId?: string;
+}
+/** createSession 的可选项。 */
+export interface CreateSessionOptions {
+    /**
+     * false 时会话照常创建并设为活跃，但宿主停留在当前路由（后台任务用）。
+     * 默认 true：与用户在新会话页手动发送的观感一致，发出去就进对话页。
+     */
+    navigate?: boolean;
+}
 export interface PluginConversationApi {
-    /** Send a prompt into the active conversation (renders as a user turn). */
-    sendPrompt(text: string): Promise<void>;
+    /**
+     * Send a prompt into the active conversation (renders as a user turn).
+     * Streaming 中会进入会话队列并立即 resolve `{ status: "queued" }`；
+     * 队列在本轮自然停止点接力消费，abort/error 后暂停待用户处置。
+     *
+     * 没有活跃会话时抛错。插件若想在这种情况下也把话说出去，先 {@link createSession}。
+     */
+    sendPrompt(text: string): Promise<SendPromptResult>;
+    /**
+     * Create a conversation in `cwd` and make it active, resolving once it is ready
+     * to receive prompts — `await createSession(cwd)` 后可以直接 {@link sendPrompt}。
+     *
+     * 用于宿主此刻没有活跃会话的场景（例如用户停在新会话页，插件侧却已经产生了要
+     * 交给 agent 的工作）。已有活跃会话时照样新建一个，不做复用判断——要不要新开由
+     * 插件按自己的语义决定。
+     *
+     * 执行模式跟随宿主当前选择，插件不感知。
+     */
+    createSession(cwd: string, options?: CreateSessionOptions): Promise<ConversationState>;
     /** Fill the input bar without sending; the user can edit and send. */
     insertText(text: string): void;
     /** Abort the active conversation's current turn. */

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,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"]}
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"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","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/**\n\t * 模型还在生成这次调用，流式参数已解析出新的键。\n\t *\n\t * 用它做「agent 正在动某个目标」这类实时 UI：`edit` / `write` 真正耗时的是\n\t * 生成参数（一整份文件正文），执行只要几毫秒，等 `tool-call-start` 到手时活\n\t * 已经干完了。目标路径通常是参数里的第一个键，所以能提前几秒拿到。\n\t *\n\t * 天然是残缺的：后面的键还没到，正在生成的那个键也不含在内。要权威全量参数\n\t * 请用 `tool-call-start`。同一次调用会随键数增长发多次，不会逐 token 发。\n\t */\n\t| { type: \"tool-call-args\"; toolCallId: string; toolName: string; args: Record<string, unknown> }\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\t| { type: \"queue-changed\"; queue: ConversationQueueState };\n\n/** 会话输入队列快照（ADR-0060）：排队中的 prompt 与暂停状态。 */\nexport interface ConversationQueueState {\n\t/** abort/error 后队列暂停；恢复由用户在宿主 UI 操作。 */\n\tpaused: boolean;\n\titems: Array<{ id: string; displayText: string }>;\n}\n\n/**\n * sendPrompt 的回执（ADR-0060）。streaming 中发送不再静默排队：返回 `queued` 与\n * 队列条目 id，插件可结合 `queue-changed` 事件呈现「已排队/已发出/被移除」状态。\n */\nexport interface SendPromptResult {\n\tstatus: \"sent\" | \"queued\" | \"failed\";\n\terror?: { message: string };\n\tqueueItemId?: string;\n}\n\n/** createSession 的可选项。 */\nexport interface CreateSessionOptions {\n\t/**\n\t * false 时会话照常创建并设为活跃，但宿主停留在当前路由（后台任务用）。\n\t * 默认 true：与用户在新会话页手动发送的观感一致，发出去就进对话页。\n\t */\n\tnavigate?: boolean;\n}\n\nexport interface PluginConversationApi {\n\t/**\n\t * Send a prompt into the active conversation (renders as a user turn).\n\t * Streaming 中会进入会话队列并立即 resolve `{ status: \"queued\" }`；\n\t * 队列在本轮自然停止点接力消费，abort/error 后暂停待用户处置。\n\t *\n\t * 没有活跃会话时抛错。插件若想在这种情况下也把话说出去，先 {@link createSession}。\n\t */\n\tsendPrompt(text: string): Promise<SendPromptResult>;\n\t/**\n\t * Create a conversation in `cwd` and make it active, resolving once it is ready\n\t * to receive prompts — `await createSession(cwd)` 后可以直接 {@link sendPrompt}。\n\t *\n\t * 用于宿主此刻没有活跃会话的场景（例如用户停在新会话页，插件侧却已经产生了要\n\t * 交给 agent 的工作）。已有活跃会话时照样新建一个，不做复用判断——要不要新开由\n\t * 插件按自己的语义决定。\n\t *\n\t * 执行模式跟随宿主当前选择，插件不感知。\n\t */\n\tcreateSession(cwd: string, options?: CreateSessionOptions): Promise<ConversationState>;\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; 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"]}
+{"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/**\n\t * 模型还在生成这次调用，流式参数已解析出新的键。\n\t *\n\t * 用它做「agent 正在动某个目标」这类实时 UI：`edit` / `write` 真正耗时的是\n\t * 生成参数（一整份文件正文），执行只要几毫秒，等 `tool-call-start` 到手时活\n\t * 已经干完了。目标路径通常是参数里的第一个键，所以能提前几秒拿到。\n\t *\n\t * 天然是残缺的：后面的键还没到，正在生成的那个键也不含在内。要权威全量参数\n\t * 请用 `tool-call-start`。同一次调用会随键数增长发多次，不会逐 token 发。\n\t */\n\t| { type: \"tool-call-args\"; toolCallId: string; toolName: string; args: Record<string, unknown> }\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\t| { type: \"queue-changed\"; queue: ConversationQueueState };\n\n/** 会话输入队列快照（ADR-0060）：排队中的 prompt 与暂停状态。 */\nexport interface ConversationQueueState {\n\t/** abort/error 后队列暂停；恢复由用户在宿主 UI 操作。 */\n\tpaused: boolean;\n\titems: Array<{ id: string; displayText: string }>;\n}\n\n/**\n * sendPrompt 的回执（ADR-0060）。streaming 中发送不再静默排队：返回 `queued` 与\n * 队列条目 id，插件可结合 `queue-changed` 事件呈现「已排队/已发出/被移除」状态。\n */\nexport interface SendPromptResult {\n\tstatus: \"sent\" | \"queued\" | \"failed\";\n\terror?: { message: string };\n\tqueueItemId?: string;\n}\n\n/** createSession 的可选项。 */\nexport interface CreateSessionOptions {\n\t/**\n\t * false 时会话照常创建并设为活跃，但宿主停留在当前路由（后台任务用）。\n\t * 默认 true：与用户在新会话页手动发送的观感一致，发出去就进对话页。\n\t */\n\tnavigate?: boolean;\n}\n\nexport interface PluginConversationApi {\n\t/**\n\t * Send a prompt into the active conversation (renders as a user turn).\n\t * Streaming 中会进入会话队列并立即 resolve `{ status: \"queued\" }`；\n\t * 队列在本轮自然停止点接力消费，abort/error 后暂停待用户处置。\n\t *\n\t * 没有活跃会话时抛错。插件若想在这种情况下也把话说出去，先 {@link createSession}。\n\t */\n\tsendPrompt(text: string): Promise<SendPromptResult>;\n\t/**\n\t * Create a conversation in `cwd` and make it active, resolving once it is ready\n\t * to receive prompts — `await createSession(cwd)` 后可以直接 {@link sendPrompt}。\n\t *\n\t * 用于宿主此刻没有活跃会话的场景（例如用户停在新会话页，插件侧却已经产生了要\n\t * 交给 agent 的工作）。已有活跃会话时照样新建一个，不做复用判断——要不要新开由\n\t * 插件按自己的语义决定。\n\t *\n\t * 执行模式跟随宿主当前选择，插件不感知。\n\t */\n\tcreateSession(cwd: string, options?: CreateSessionOptions): Promise<ConversationState>;\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"]}