@ycodium-ai/plugin-api 0.2.3000 → 0.2.3008

package/dist/index.d.ts

@@ -10,14 +10,14 @@ import type * as CapabilityPorts from "./capabilityPorts.ts";
 import type { PluginToolkit } from "./plugin-tools.ts";
 export * from "./capabilityPorts.ts";
 export type * from "./plugin-tools.ts";
-import type { ExecutorContribution, ExecutorSessionCandidate, ExecutorSessionRecord } from "./executor.ts";
-import type { PluginDataPorts, ProjectsGetOutput, ThreadsListOutput } from "./dataPorts.gen.ts";
+import type { ExecutorContribution } from "./executor.ts";
+import type { PluginDataPorts, ThreadsListOutput } from "./dataPorts.gen.ts";
 import type { PluginUserInput } from "./pending-requests.ts";
 export * from "./dataPorts.gen.ts";
 /** 会话目录的一行（`ctx.threads.list` 返回页的 `items`）：只有壳，没有消息正文。 */
 export type PluginThreadShell = ThreadsListOutput["items"][number];
 import type { PluginProcess, PluginSocket, PluginPorts, PluginNetwork } from "./process-socket.ts";
-import type { PluginSettingsCard, PluginSettingsWriteOptions } from "./settings-actions.ts";
+import type { PluginSettingsCard } from "./settings-actions.ts";
 export type * from "./settings-actions.ts";
 export { mergeLaunchEnv } from "./executor.ts";
 export * from "./executorModelOptions.ts";
@@ -46,619 +46,22 @@ export * from "./settings-card-shape.ts";
 export { parseRetryAfterMs } from "./usage.ts";
 export type { ExecutorQuotaBalance, ExecutorQuotaReading, ExecutorQuotaResetResult, ExecutorQuotaUnavailableReason, ExecutorQuotaWindow, ExecutorTokenRecord, ExecutorTokenTotals, ExecutorTokenUsageReading, ExecutorUsage, ExecutorUsageText, } from "./usage.ts";
 export type { ExecutorCard, ExecutorContribution, ExecutorFormControl, ExecutorFormField, ExecutorFormFieldAnnotation, ExecutorHost, ExecutorInstance, ExecutorSessionCandidate, ExecutorSessionRecord, } from "./executor.ts";
-export declare const PLUGIN_API_VERSION = 6;
+import type { PluginCommands, PluginDisposer, PluginNotifications, PluginOperations, PluginSettings } from "./pluginContextCommands.ts";
+import type { PluginEnvironment, PluginProviders } from "./pluginContextProviders.ts";
+import type { PluginProxies, PluginWorkspace } from "./pluginContextWorkspace.ts";
+import type { PluginAttachments, PluginThread, PluginThreadExecution, PluginThreadMessage } from "./pluginContextThreads.ts";
+export type { PluginDisposer, PluginSettings, PluginCommandReceipt, PluginCommandDispatchResult, PluginNotifications, PluginOperationName, PluginOperationCheckInput, PluginOperations, PluginCommands, } from "./pluginContextCommands.ts";
+export type { PluginEnvironment, PluginProviderModel, PluginProviderInstance, PluginProviderSessionBinding, PluginProviderResumeCursorInput, PluginProviderSessions, PluginProviderNativeSessions, PluginProviders, PluginModelSelection, } from "./pluginContextProviders.ts";
+export type { PluginWorkspace, PluginProxy, PluginRequiredProxySelection, PluginProxySelection, PluginProxies, PluginProject, } from "./pluginContextWorkspace.ts";
+export type { PluginActivity, PluginAttachmentInput, PluginAttachment, PluginAttachments, PluginThreadMessage, PluginThreadSession, PluginThreadOrigin, PluginThreadForkPoint, PluginTurnIntent, PluginThreadExecution, PluginThread, } from "./pluginContextThreads.ts";
+export declare const PLUGIN_API_VERSION = 7;
 /**
- * 宿主装载的最旧 apiVersion。低于它太旧；高于 PLUGIN_API_VERSION 则是宿主太旧。6 删掉了
- * `projections.getProject` / `listProjects`（改由登记表组装的 `projects.get` / `projects.list`），用旧成员的
- * 插件装不进来，所以最低版本就是 6 本身。
+ * 宿主装载的最旧 apiVersion。低于它太旧；高于 PLUGIN_API_VERSION 则是宿主太旧。7 换了
+ * `communication.records.get` / `.list` 的形状（按号读交的是视图，正文可以是 null；列表按项目与范围取、
+ * 交的是摘要与游标），照旧形状写的插件读到的东西对不上，所以最低版本就是 7 本身。
  */
-export declare const PLUGIN_API_MIN_VERSION = 6;
-export type PluginApiVersion = 6;
-/**
- * 注册类调用统一返回它；不调用也行，插件 Scope 关闭时宿主会替你撤销。
- *
- * 插件已经 dispose 之后再注册任何贡献（activate 之后异步注册的常见情形）：宿主只记
- * 一条 warning，返回一个 **no-op disposer**，那条贡献不会进已经死掉的记录，也不抛错。
- */
-export type PluginDisposer = () => void;
-export interface PluginSettings<Config> {
-    /** 读本插件在 home patch 层的那份 config（`password` 已解成明文）；home 层没写过就回退到 `ctx.config`，不是空对象。 */
-    readonly read: () => Promise<Config>;
-    /** 整体替换本插件那条 config，之后照 `onChange` 就地换或重启这一个插件；已存的密码引用不被覆盖，存新密码用 options.secrets。 */
-    readonly write: (config: Config, options?: PluginSettingsWriteOptions) => Promise<void>;
-    /**
-     * 配置变了（存卡片、`write`）时宿主不重启插件，把新 config（密码已解）交给 handler，`ctx.config` 也换成新值。
-     * 没注册 handler 的插件照旧重启；handler 抛错或 reject，宿主退回重启这一个插件。返回值取消注册。
-     */
-    readonly onChange: (handler: (config: Config) => void | Promise<void>) => () => void;
-}
-export type PluginCommandReceipt = {
-    readonly status: "absent";
-} | {
-    readonly status: "accepted";
-    readonly sequence: number;
-} | {
-    readonly status: "rejected";
-    readonly error: string | null;
-};
-export interface PluginCommandDispatchResult {
-    /** accepted 只表示命令持久受理；provider 投递确认须查 turn intent。 */
-    readonly status: "accepted" | "noop";
-    readonly sequence: number;
-    readonly replayed: boolean;
-    readonly result?: unknown;
-}
-export interface PluginNotifications {
-    /** 来源须有执行归属，只能通知同项目的来源会话或其祖先；正文走通信记录，唤醒走持久队列。 */
-    readonly send: (input: {
-        readonly threadId: string;
-        readonly sourceThreadId: string;
-        readonly summary: string;
-        /** 同一通知跨重启重试必须复用 generation；返回不表示 provider 已收到。 */
-        readonly generation?: string | undefined;
-    }) => Promise<PluginCommandDispatchResult & {
-        readonly recordId: string;
-    }>;
-}
-/** 宿主会问插件的操作。只增不删：老插件登记过的名字永远还认。 */
-export type PluginOperationName = "server.upgrade" | "project.archive";
-/**
- * 交给 check 的入参，按操作名分派。`server.upgrade` 带发起升级的会话；
- * `project.archive` 带即将归档的项目，拿掉这个项目在这台机器上的文件夹时问的也是它。
- */
-export type PluginOperationCheckInput<O extends PluginOperationName = PluginOperationName> = O extends "server.upgrade" ? {
-    readonly operation: "server.upgrade";
-    readonly threadId: string;
-} : O extends "project.archive" ? {
-    readonly operation: "project.archive";
-    readonly projectId: string;
-    /**
-     * 宿主已提交的事件序号。领域状态由事件异步推进的插件，先追到它再回答，
-     * 才看得见归档前一瞬刚发生的事（同 `commands.guard` 的 throughSequence）。
-     */
-    readonly throughSequence?: number | undefined;
-} : never;
-export interface PluginOperations {
-    /**
-     * 给一类宿主操作加规则，规则随插件停用撤销。
-     *
-     * - `server.upgrade` 只约束本插件创建的会话及其委派后代。
-     * - `project.archive` 在归档这台机器上的某个项目、或拿掉它的文件夹之前，问所有已加载的
-     *   插件，不按会话归属限定。check 只能读、不能派发命令；5 秒不答、抛错都按拒绝处理。
-     *   拒绝原句会点名你的插件，所以 detail 是写给用户看的：说清楚什么还没做完；宿主会折叠
-     *   其中的空白并截到 300 字符。
-     *
-     * 具名声明规则对象时用 `PluginOperationCheckInput<"server.upgrade">` 标 check 的入参。
-     * 不要写 `Parameters<PluginOperations["guard"]>[0]`：泛型 O 取不到具体操作，入参会
-     * 变成全部操作的联合，你的 check 赋不进去。直接内联 `guard({...})`、不标入参类型也可以。
-     */
-    readonly guard: <O extends PluginOperationName>(guard: {
-        readonly operations: readonly O[];
-        readonly check: (input: PluginOperationCheckInput<O>) => Promise<{
-            readonly allowed: true;
-        } | {
-            readonly allowed: false;
-            readonly detail: string;
-        }>;
-    }) => PluginDisposer;
-}
-export interface PluginCommands {
-    /**
-     * 为本插件创建的会话检查起轮准入，覆盖聊天、工具和后台入口。
-     * 检查期间只能读取状态，不能再派发命令；停用时自动撤销。
-     */
-    readonly guard: (guard: {
-        readonly name: string;
-        readonly check: (input: {
-            readonly threadId: string;
-            readonly messageId: string;
-            /** 有值时，这一轮是已持久通信记录的投递物。 */
-            readonly recordId?: string | undefined;
-            readonly throughSequence: number;
-        }) => Promise<{
-            readonly allowed: true;
-        } | {
-            readonly allowed: false;
-            readonly detail: string;
-        }>;
-    }) => PluginDisposer;
-    /**
-     * 派发一条编排 command。形状不合法会 reject。
-     *
-     * **两道门**（路线图 #62）：
-     *
-     * 1. **要声明。** manifest 的 `commands.dispatch` 权限逐条列出你要派的命令类型，
-     *    没声明或不在名单里当场 reject（reason `undeclared` / `not-declared`）。
-     *    能选的命令是宿主定的一张封闭名单——`project.delete`、`thread.delete`、
-     *    `thread.message.assistant.complete` 这类不在里面，写进 manifest 解码就断。
-     * 2. **默认只碰自己开的会话。** 带 `threadId` 的那几条（`thread.turn.start` / `thread.turn.interrupt` /
-     *    `thread.approval.respond` / `thread.user-input.respond` / `thread.turn-intent.run` /
-     *    `thread.turn-intent.cancel` / `thread.turn-queue.resume` / `thread.external-messages.append`）只许落在你用
-     *    `thread.create` 或 `thread.import` 开出来的会话上，别的 reject（reason `foreign-thread`）。
-     *    声明了 `threads.user` 时，除 `thread.external-messages.append` 外，可落到本机某个 project 上的用户会话
-     *    （起轮/审批/提问/插话等）；仍不转交执行归属。**插件挂载所在的那条会话也不算自己的**：
-     *    那是人跟 agent 对话的地方，能在那儿替人按批准等于自己给自己开绿灯。
-     *
-     * 署名只由服务器盖章：命令里自带的 `author`（`thread.turn.start`）与 `createdBy`
-     * （`thread.create`）会被宿主剥掉，会话与消息记成没有作者，插件没有可冒用的身份。
-     *
-     * `thread.turn.start` 里的 `intentAction`（服务器内部的「入队即插话」入口）只有
-     * `source: "automatic"` 的会被放行，其余被剥掉；用户式的插话与打断走
-     * `thread.turn-intent.run`。
-     *
-     * `thread.create` 的执行归属由宿主持久保存，按安装条目与插件身份认：重新挂载或数据搬了位置后仍可控制原会话，重放也认回原收据。
-     * 同项目的 continuation 沿来源链继承归属，显式新归属优先；普通委派或分叉不继承。`thread.import` 的临时执行权限不跨挂载；已有历史跟读授权
-     * 不会因重启或重放导入回执而变成执行权限。停用后的旧实例不可继续派发命令。`result` 是命令类型定的业务结果（如新建对象的号），同号重放同一份，多数命令没有。
-     */
-    readonly dispatch: (command: unknown) => Promise<PluginCommandDispatchResult>;
-    /** 仅查询已声明的命令；落在既有会话上的命令（起轮、分叉等）要带 threadId 并要求线程执行归属，开会话、导入与其余命令按安装身份映射 commandId、可省略 threadId，只查得到自己派的。 */
-    readonly getReceipt: (input: {
-        readonly commandId: string;
-        readonly commandType: string;
-        readonly threadId?: string;
-    }) => Promise<PluginCommandReceipt>;
-}
-/** 这台 environment 的身份。用户看到的名字是「机器」。 */
-export interface PluginEnvironment {
-    /** 服务器持久化的 environment id，不是主机名：两台机器可以同名。 */
-    readonly id: string;
-}
-/**
- * provider 实例当前报出来的一个模型。挑模型只要这三个字段，快照里其余的
- * （能力位、上下文窗口、隐藏标记）是界面的事。
- */
-export interface PluginProviderModel {
-    /** 发起 turn 时写进 modelSelection 的那个值。 */
-    readonly slug: string;
-    readonly name: string;
-    /** 该实例的默认模型。一个实例最多一个。 */
-    readonly isDefault: boolean;
-}
-/**
- * 一个 provider 实例的高层视图。宿主替插件解析各 driver 的 home 布局，
- * 插件不抄这些细节。字段只增不改。
- */
-export interface PluginProviderInstance {
-    readonly instanceId: string;
-    /** `claudeAgent`、`codex`、`cursor`…… 宿主的 driver 名。 */
-    readonly driver: string;
-    readonly displayName: string | null;
-    readonly enabled: boolean;
-    /** 只有解析得出 home 布局的 driver 有值（当前是 claude / codex），其余是 null。 */
-    readonly homePath: string | null;
-    /** provider CLI 自己的会话转录目录；解析不出来是 null。 */
-    readonly transcriptDir: string | null;
-    /**
-     * provider CLI 读自己配置文件的那个目录：claude 的 `settings.json`、codex 的
-     * `config.toml` 都在这里。解析不出来是 null。
-     *
-     * 判断「这个实例连的到底是不是官方服务」要读这些文件，路径只有宿主算得准
-     * （`CLAUDE_CONFIG_DIR` 的优先级、codex 的 auth overlay 布局）。读它本身仍然要
-     * `fs.read` 声明覆盖到这个目录。
-     */
-    readonly configDirPath: string | null;
-    /**
-     * 用户为这个实例配了哪些环境变量：只有名字（排序），**不给值**，也不含宿主进程环境。
-     *
-     * 实例变量里常是 API key，插件拿不到它的值。要判断「用户为这个 provider 配了密钥吗」
-     * 看名字在不在这里就够了。
-     */
-    readonly environmentKeys: ReadonlyArray<string>;
-    /**
-     * 这个实例的 **driver 专属设置**，只含名片 `configSchema` 声明过的标量字段（字符串、数字、
-     * 布尔），去掉设置表单里画成密码框（`x-ycodium-form.control: "password"`）的字段；未声明的键、
-     * 对象与数组字段一律不给——里面可能夹着凭据。
-     *
-     * **形状随 driver 变，恕不另行通知。** 上面那些字段是宿主挑出来、并且承诺稳定的；
-     * 这一份不是承诺，是逃生口——它存在的理由是**不必为每个新需求往上面那张表里再加一个
-     * 字段**。读之前必须自己收窄类型；键不存在、类型不对、driver 换了写法，都要能不炸地
-     * 退回默认行为。
-     *
-     * 实例根本没配 driver 设置时是空对象，不是 undefined —— 少一层判空。
-     */
-    readonly driverConfig: Readonly<Record<string, unknown>>;
-    /**
-     * 实例配置里的启动参数原文；没有就是空串。
-     *
-     * 与 `apiEndpoint` 一样，是 Usage 搬迁时从 `driverConfig` 里挑出来单开的字段。留着是
-     * 因为拿掉会弄坏既有插件，不是因为它们比别的键更重要。**新需求走 `driverConfig`**，
-     * 别再往这张表上加 driver 专属字段。
-     */
-    readonly launchArgs: string;
-    /** 实例配置里的自定义 API endpoint（cursor 的 `-e`）；没配是 null。见 `launchArgs`。 */
-    readonly apiEndpoint: string | null;
-    /**
-     * 这个实例当前可选的模型，来自与客户端共用的 provider 模型目录，包含已恢复的缓存。
-     *
-     * **缺席不等于没有模型**：它表示这个实例在注册表里还没加载出来（driver 没注册、
-     * 配置解不动、快照还没建好）。要给一条新 thread 挑模型的插件必须把缺席当作
-     * 「这个实例现在起不了 turn」处理，而不是退到某个猜的 slug。
-     */
-    readonly models?: readonly PluginProviderModel[] | undefined;
-}
-/**
- * provider 会话目录里的一条绑定：哪条 thread 挂在哪个 provider 实例上，以及
- * 重开原生会话要用的游标。
- */
-export interface PluginProviderSessionBinding {
-    readonly threadId: string;
-    /** 绑定写下的 driver kind（`claudeAgent`、`codex`……），不是实例 id。 */
-    readonly driver: string;
-    /** 绑定所属的 provider 实例；老库里的行可能没有，缺就是 null。 */
-    readonly instanceId: string | null;
-    /**
-     * 各 driver 自己的形状（claude 是 `{ resume }`，codex 是 `{ threadId }`），宿主
-     * 不替插件解析 —— 原生会话 id 藏在哪个字段是 driver 的事。没有游标是 null。
-     */
-    readonly resumeCursor: unknown;
-    /** 绑定记下的会话运行状态；读不出来是 null。 */
-    readonly status: string | null;
-    /** 这条绑定最后一次被写的时间（ISO）。 */
-    readonly lastSeenAt: string;
-}
-export interface PluginProviderResumeCursorInput {
-    readonly instanceId: string;
-    readonly threadId: string;
-    /** 写进绑定的游标原文，形状由 driver 定。 */
-    readonly cursor: unknown;
-}
-/**
- * provider 会话绑定。`list` 只读；`setResumeCursor` 是插件面上**唯一的写口**，
- * 边界刻意收得很窄：
- *
- * - 只能写 `resumeCursor` 一个字段。driver kind 由宿主按 `instanceId` 解析，
- *   状态、runtimeMode、runtimePayload 都归编排，插件碰不到。
- * - 目标 thread 必须存在；`instanceId` 必须是这台机器上配着的 provider 实例。
- * - thread 已经绑在**另一个**实例上时拒绝 —— 把别人的会话改道过来是数据损坏，
- *   不是配置。要换实例走编排命令，不走这里。
- *
- * 拒绝时宿主留一条带 pluginId 的 warning。
- */
-export interface PluginProviderSessions {
-    readonly list: () => Promise<readonly PluginProviderSessionBinding[]>;
-    readonly setResumeCursor: (input: PluginProviderResumeCursorInput) => Promise<void>;
-    /**
-     * 停掉一条 thread 的 provider 会话进程。第二个写口，边界同样收得很窄：
-     *
-     * - 只停，不启、不重启、不发消息。重开是下一条用户消息的事，由编排决定。
-     * - thread 必须存在，且此刻确实挂着一个**活着**的会话（`running` / `starting`）。
-     *   空闲、已停、压根没建过会话的一律拒绝——"停一个没在跑的东西"是插件算错了状态，
-     *   静默成功会把那个错误一直藏着。
-     * - 会话正在跑一个 turn 时照停：这正是它存在的理由（原生记录被别处写了，常驻进程
-     *   拿的是过期的上下文）。
-     *
-     * 拿不到"这条 thread 是不是本插件建的"这个事实（`ThreadOrigin` 不区分导入），所以
-     * 归属判不了；能查证的三条上面写全了。拒绝时宿主留一条带 pluginId 的 warning。
-     */
-    readonly stop: (threadId: string) => Promise<void>;
-}
-/**
- * 一只手的原生会话入口：终端里跑过、留在磁盘上的那些会话。
- *
- * 形状就是执行器契约里的 `ExecutorSessionCandidate` / `ExecutorSessionRecord`——
- * 宿主只把插件给的值原样递过来，不翻译、不另造同义字段。
- *
- * `scan` 只报手看得见的事实：`availability` 一律是 `"importable"`，「已经有 thread
- * 绑着它了」是宿主的账，调用方自己按 `sessions.list()` 盖上去。
- */
-export interface PluginProviderNativeSessions {
-    readonly scan: (input: {
-        readonly projectId: string;
-        readonly directory?: string;
-        readonly signal?: AbortSignal;
-    }) => Promise<{
-        readonly candidates: ReadonlyArray<ExecutorSessionCandidate>;
-    }>;
-    readonly read: (input: {
-        readonly nativeSessionId: string;
-        readonly cwd: string;
-        readonly signal?: AbortSignal;
-    }) => Promise<ExecutorSessionRecord>;
-}
-export interface PluginProviders {
-    readonly listInstances: () => Promise<readonly PluginProviderInstance[]>;
-    readonly getRouting: () => Promise<{
-        readonly allowlistOnly: boolean;
-        readonly roles: Readonly<Record<string, {
-            readonly instanceId: string;
-            readonly model: string;
-        }>>;
-    }>;
-    /** 按当前路由与可用实例解析选择；读取失败或目标不可用时拒绝。 */
-    readonly resolveSelection: (input: {
-        readonly base: PluginModelSelection | null;
-        readonly instanceId?: string;
-        readonly model?: string;
-        readonly options?: PluginModelSelection["options"];
-        readonly routingKey?: string;
-    }) => Promise<{
-        readonly modelSelection: PluginModelSelection;
-    }>;
-    readonly sessions: PluginProviderSessions;
-    /**
-     * 这个实例那只手自己会扫原生会话时给出入口；不会扫（宿主内置的 driver，或手没
-     * 实现 `sessions`）返回 null，调用方回落到自己那份扫描。
-     *
-     * 未知 instanceId **拒绝**，不悄悄返回 null：那会把「实例 id 写错了」伪装成
-     * 「这只手不会扫」，回落之后照样出结果，没人发现走的一直是自己那份。
-     */
-    readonly nativeSessions: (instanceId: string) => Promise<PluginProviderNativeSessions | null>;
-}
-export interface PluginWorkspace {
-    /** 为本插件创建的独立工作树会话运行项目已配置的 setup 脚本，沿用宿主终端。 */
-    readonly setupThread: (threadId: string) => Promise<{
-        readonly status: "no-script";
-    } | {
-        readonly status: "started";
-        readonly scriptId: string;
-        readonly scriptName: string;
-        readonly terminalId: string;
-        readonly cwd: string;
-    }>;
-}
-/**
- * 这台机器上配着的一个代理。**不含密码**：宿主自己往连接上加 `Proxy-Authorization`，
- * 插件不需要、也拿不到那份凭据。
- */
-export interface PluginProxy {
-    readonly id: string;
-    readonly displayName?: string | undefined;
-    readonly protocol: "http" | "https";
-    readonly host: string;
-    readonly port: number;
-    /** 不经这个代理直连的地址，逗号分隔。本机地址是硬约束，不在这里出现。 */
-    readonly bypass?: string | undefined;
-    /** 这一个就是机器的全局默认。整张表都没有 true 时，默认即直连。 */
-    readonly isDefault: boolean;
-}
-/**
- * 选哪个代理。与设置里每条功能的代理选择同义：
- *
- * - **省略 / `undefined`** —— 跟这台机器的全局默认走。
- * - **`null`** —— 不加 Ycodium 配的代理。注意它只停 Ycodium 这一份：机器环境里的
- *   `HTTP_PROXY` / `HTTPS_PROXY` 照旧生效，宿主不去剥它们。
- * - **代理 id** —— 用那一个。指向一个不存在的 id **静默退化成直连**。
- * - **`{ required: id }`** —— 必须用那一个。代理不存在、设置读不出来、连不上
- *   都 **reject**，不改走直连。订阅凭据这种不能从本机打出去的请求用这一档。
- *
- * 三态里悬空 id 仍静默直连，与 `ctx.http` 同一条规则：手改配置文件不该把长连接搞挂。
- * 要确认某个 id 现在还在，先 `list()`。
- */
-export type PluginRequiredProxySelection = {
-    readonly required: string;
-};
-export type PluginProxySelection = string | null | PluginRequiredProxySelection;
-/**
- * 按代理出网。列出这台机器配了什么，然后挑一个出网 —— IM 桥那种「每个实例各配
- * 各的代理」的功能靠它，不必给每个实例塞一份自己的 HTTP 客户端。
- */
-export interface PluginProxies {
-    /** 这台机器配着的代理，按 id 升序。一个都没配就是空数组，不是错误。 */
-    readonly list: () => Promise<readonly PluginProxy[]>;
-    /**
-     * 按三态选择出网的 fetch。选择在**调用时**解析（跟着当前设置走），拿到的 fetch
-     * 之后一直走那个代理 —— 所以设置改了要重新调一次，别把返回值缓存一辈子。
-     *
-     * `ctx.http` 等价于建插件时调过一次 `fetch()`（省略参数那一档）：一样的解析规则、
-     * 一样的连接池，只是解析发生在宿主建能力面的时刻。想让改过的代理设置立刻生效而
-     * 不重启，就用这条重新要一个。
-     */
-    readonly fetch: (proxy?: PluginProxySelection | undefined) => Promise<typeof globalThis.fetch>;
-}
-/** 投影出来的一条线程活动。payload 保持 unknown，由插件按 kind 收窄。 */
-export interface PluginActivity {
-    readonly activityId: string;
-    readonly threadId: string;
-    readonly turnId: string | null;
-    readonly kind: string;
-    readonly tone?: string | undefined;
-    readonly summary: string;
-    readonly payload: unknown;
-    readonly createdAt: string;
-}
-/** 在某个 provider 实例上选定的一个模型。发起 turn 的命令载荷用的就是这个形状。 */
-export interface PluginModelSelection {
-    readonly instanceId: string;
-    readonly model: string;
-    readonly options?: readonly {
-        readonly id: string;
-        readonly value: string | boolean;
-    }[];
-}
-/**
- * 一个 project：`ctx.projects.get` 的结果、`ctx.projects.list` 的一行，形状由公共契约生成。项目号是 `id`；
- * 仓库身份在 `repositoryIdentity`（工作区不是 git 仓库、没有可用 remote、或远端地址认不准时是 null），
- * 其中 `canonicalKey` 是跨机器可比的 `host/owner/repo`，`provider` 认不出托管方时缺席，远端在 `locator` 里
- * （地址已去掉凭据，只供显示与取主机名）。`archivedAt` 缺席或 null 都表示未归档。
- */
-export type PluginProject = ProjectsGetOutput;
-/** thread 里的一条消息。附件、逐条模型选择这类界面用的字段不透出。 */
-/**
- * 一份要落成会话附件的字节。
- *
- * 大小上限沿用宿主对聊天附件的那一份（按 mime 分档，图片与文件不同），超了就 reject
- * —— 插件不该有一条比人从网页上传更宽的路。
- */
-export interface PluginAttachmentInput {
-    /** 附件挂在哪条会话下。落盘目录按它分，删会话时一起回收。 */
-    readonly threadId: string;
-    readonly name: string;
-    readonly mimeType: string;
-    readonly bytes: Uint8Array;
-}
-/** 落好盘的附件。原样塞进 `thread.turn.start` 的 `message.attachments` 即可。 */
-export interface PluginAttachment {
-    /** mime 是 `image/*` 就是 `image`，其余都是 `file`。 */
-    readonly type: "image" | "file";
-    readonly id: string;
-    readonly name: string;
-    readonly mimeType: string;
-    readonly sizeBytes: number;
-}
-/**
- * 把字节落成会话附件。插件面上唯一的字节写口。
- *
- * 为什么需要它：`ctx.commands.dispatch` 收的是**已经规范化**的命令，附件那一格只认
- * 落好盘的记录（`{id, name, mimeType, sizeBytes}`），不认 data URL —— 网页客户端那条
- * 路由宿主的规范化器代劳，插件得自己先落一次。
- */
-export interface PluginAttachments {
-    readonly store: (input: PluginAttachmentInput) => Promise<PluginAttachment>;
-    /**
-     * 按 id 读回字节。附件不在这台机器上就 reject，不回空字节 —— 「没有」与「是空的」
-     * 是两回事。
-     *
-     * 不需要声明：这些 id 本来就写在 `getThread` / `getThreadMessage` 读得到的消息上，
-     * 这条只是把「看得见记录」补成「读得到内容」。
-     */
-    readonly read: (attachmentId: string) => Promise<Uint8Array>;
-}
-export interface PluginThreadMessage {
-    readonly messageId: string;
-    readonly role: string;
-    readonly text: string;
-    readonly turnId: string | null;
-    readonly createdAt: string;
-    readonly modelSelection?: PluginModelSelection | undefined;
-    readonly source?: {
-        readonly kind: "native-session";
-        readonly provider: "claude" | "codex";
-        readonly sessionId: string;
-        readonly messageId: string;
-        readonly turnId?: string | undefined;
-        readonly order: number;
-    } | undefined;
-    /** 这条消息带的附件；要字节走 `ctx.attachments.read(id)`。 */
-    readonly attachments: readonly PluginAttachment[];
-}
-/** thread 当前的 provider 会话状态。没建过会话是 null。 */
-export interface PluginThreadSession {
-    /** `idle` / `starting` / `running` / `stopped`…… 宿主的会话状态名。 */
-    readonly status: string;
-    readonly providerInstanceId: string | null;
-    /** 正在跑的 turn；空闲是 null。 */
-    readonly activeTurnId: string | null;
-    readonly lastError?: string | null | undefined;
-    readonly updatedAt?: string | undefined;
-    readonly endReason?: "server-restart" | undefined;
-}
-export interface PluginThreadOrigin {
-    readonly parentThreadId: string;
-    readonly delegationDepth: number;
-    readonly requestedBy: "agent" | "continuation";
-    readonly notificationPolicy?: "wake" | "activity-only" | undefined;
-}
-export interface PluginThreadForkPoint {
-    readonly sourceThreadId: string;
-    readonly sourceMessageId: string;
-}
-export interface PluginTurnIntent {
-    readonly intentId: string;
-    readonly threadId: string;
-    readonly sequence: number;
-    readonly commandId: string;
-    readonly messageId: string;
-    readonly revision: number;
-    readonly turn: {
-        readonly turnId: string | null;
-        readonly userMessageId: string;
-        readonly state: "pending" | "running" | "interrupted" | "completed" | "error";
-        readonly requestedAt: string;
-        readonly startedAt: string | null;
-        readonly completedAt: string | null;
-        readonly waitSpans: readonly {
-            readonly kind: "approval" | "userInput";
-            readonly requestId: string;
-            readonly startedAt: string;
-            readonly completedAt: string | null;
-        }[];
-    } | null;
-    readonly status: "queued" | "preparing" | "dispatching" | "running" | "completed" | "interrupted" | "failed" | "reconciling" | "blocked" | "cancelled" | "abandoned";
-    readonly deliveryCertainty: "not-dispatched" | "confirmed" | "unknown";
-    readonly attempt: {
-        readonly attemptId: string;
-        readonly workerEpoch: number;
-        readonly sourceBindingId: string | null;
-        readonly targetBindingId: string | null;
-        readonly stage: "preparing" | "dispatching" | "running" | "reconciling";
-        readonly deliveryCertainty: "not-dispatched" | "confirmed" | "unknown";
-        readonly nativeLocator: {
-            readonly sessionId?: string | undefined;
-            readonly turnId?: string | undefined;
-            readonly generationId?: string | undefined;
-        } | null;
-        readonly createdAt: string;
-        readonly updatedAt: string;
-    } | null;
-    readonly blockedReason: string | null;
-    readonly replacementIntentId: string | null;
-    readonly createdAt: string;
-    readonly updatedAt: string;
-}
-/** 不加载消息历史；持久状态在同一数据库快照内读取，进程存活另取当前 provider 句柄。 */
-export interface PluginThreadExecution {
-    readonly threadId: string;
-    readonly projectId: string;
-    readonly title: string;
-    readonly modelSelection: PluginModelSelection;
-    readonly runtimeMode: "approval-required" | "auto-accept-edits" | "auto" | "full-access";
-    readonly interactionMode: "default" | "plan";
-    readonly branch: string | null;
-    readonly worktreePath: string | null;
-    readonly origin: PluginThreadOrigin | null;
-    readonly forkedFrom: PluginThreadForkPoint | null;
-    readonly archivedAt: string | null;
-    readonly createdAt: string;
-    readonly updatedAt: string;
-    readonly session: (PluginThreadSession & {
-        readonly lastError: string | null;
-        readonly updatedAt: string;
-    }) | null;
-    readonly latestTurn: {
-        readonly turnId: string;
-        readonly state: "running" | "interrupted" | "completed" | "error";
-        readonly requestedAt: string;
-        readonly startedAt: string | null;
-        readonly completedAt: string | null;
-        readonly userMessageId?: string | undefined;
-        readonly assistantMessageId: string | null;
-        readonly waitSpans?: readonly {
-            readonly kind: "approval" | "userInput";
-            readonly requestId: string;
-            readonly startedAt: string;
-            readonly completedAt: string | null;
-        }[] | undefined;
-    } | null;
-    readonly turnIntents: readonly PluginTurnIntent[];
-    readonly queuePaused: boolean;
-    readonly providerProcessLive: boolean;
-    readonly hasPendingApprovals: boolean;
-    readonly hasPendingUserInput: boolean;
-    readonly pendingApprovalCount: number;
-    readonly pendingUserInputCount: number;
-    /** 持久 turn-start-requested 事实总数，含普通客户端入口；与导入用户消息数不同。 */
-    readonly turnStartCount: number;
-}
-/**
- * 一条 thread 的只读视图：消息列表加会话状态。
- *
- * 默认不带活动、checkpoint、提案计划；原生历史对齐可显式请求有界活动窗口。
- */
-export interface PluginThread {
-    readonly threadId: string;
-    readonly projectId: string;
-    readonly title: string;
-    readonly modelSelection: PluginModelSelection;
-    readonly origin?: PluginThreadOrigin | null | undefined;
-    readonly forkedFrom?: PluginThreadForkPoint | null | undefined;
-    /** 归档过的 thread 有值；活着的是 null。 */
-    readonly archivedAt: string | null;
-    readonly messages: readonly PluginThreadMessage[];
-    /** 仅显式请求时带回当前有界窗口的活动，供原生历史对齐；不含检查点或提案。 */
-    readonly activities?: readonly PluginActivity[] | undefined;
-    readonly session: PluginThreadSession | null;
-    readonly updatedAt: string;
-}
+export declare const PLUGIN_API_MIN_VERSION = 7;
+export type PluginApiVersion = 7;
 /**
  * 只读投影查询。写投影是编排的事，插件碰不到。
  *