@ycodium-ai/plugin-api 0.2.2982 → 0.2.2984

package/dist/cache.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 插件的目录与缓存：`ctx.paths`、`ctx.cache`。类型从 `index.ts` 再导出。
+ *
+ * @module @ycodium-ai/plugin-api/cache
+ */
+export interface PluginPaths {
+    /**
+     * 插件代码所在目录（只读地用，宿主不保证可写）。
+     *
+     * 自带翻译包的插件把 catalog 放在这个目录下的 `locales/<locale>.json`
+     * （`en.json`、`zh-CN.json`……），宿主加载时读进 `plugin:<pluginId>` 命名
+     * 空间，缺 locale 回落英文。宿主只加载，不翻译第三方插件的文案。
+     */
+    readonly pluginDir: string;
+    /** `<ycodium home>/plugin-data/<pluginId>`，卸载插件时不动。 */
+    readonly dataDir: string;
+    /**
+     * `<dataDir>/cache`。语义是**可随时重建**：宿主（或用户）随时可以整个删掉，
+     * 插件必须能从零重新算出来。要保留的东西写 `dataDir`。
+     *
+     * 目录惰性创建 —— 读到这个属性时才建，没用过缓存的插件不留空目录。
+     */
+    readonly cacheDir: string;
+}
+export interface PluginCacheResult<T> {
+    readonly value: T;
+    readonly stale: boolean;
+}
+/**
+ * 落 `paths.cacheDir` 下的按 key JSON 缓存（口子 #11）：插件不用自己拼文件名、
+ * 手搓 TTL 判断。文件名是 `sha256(key)` 的十六进制串。
+ *
+ * `getJson` 的过期语义：
+ * - 不传 `maxAgeMs`：文件存在且能解析就返回，`stale` 恒 `false`（不做新鲜度判断，
+ *   写的时候自己决定要不要覆盖）。
+ * - 传了 `maxAgeMs` 且未过期：返回，`stale` `false`。
+ * - 传了 `maxAgeMs` 且已过期：`allowStale` 为 `true` 时照样返回旧值，标
+ *   `stale: true`；否则视同没有缓存，返回 `null`——这是"退回旧结果顶一阵"与
+ *   "过期就必须重新请求"两种插件都要用到的口子，用一个参数分开。
+ * - 缺失 / JSON 解析失败 / 形状不对：返回 `null`；后两种情况宿主会顺手删掉这份
+ *   坏文件，不留着占位置。
+ */
+export interface PluginCache {
+    readonly getJson: <T = unknown>(key: string, maxAgeMs?: number, allowStale?: boolean) => Promise<PluginCacheResult<T> | null>;
+    readonly setJson: (key: string, value: unknown) => Promise<void>;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,OAAO,EAC5B,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,OAAO,KACjB,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE"}

package/dist/cache.js

@@ -0,0 +1,7 @@
+/**
+ * 插件的目录与缓存：`ctx.paths`、`ctx.cache`。类型从 `index.ts` 再导出。
+ *
+ * @module @ycodium-ai/plugin-api/cache
+ */
+export {};
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/cli.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `ycodium x <pluginId> <name>` 子命令：`ctx.cli`。类型从 `index.ts` 再导出。
+ *
+ * @module @ycodium-ai/plugin-api/cli
+ */
+/**
+ * 位置参数。声明顺序即命令行顺序；`variadic` 只能是最后一个。
+ */
+export interface PluginCliArgument {
+    /** 也是 `input.arguments` 里的键。 */
+    readonly name: string;
+    readonly description?: string | undefined;
+    /** 默认 true。可选参数缺席时键不出现。 */
+    readonly required?: boolean | undefined;
+    /** 吃掉剩下的全部参数，值是 `string[]`。只能声明在最后一个。 */
+    readonly variadic?: boolean | undefined;
+}
+/** `--name` 选项。`kind` 决定 `input.options[name]` 的类型。 */
+export interface PluginCliOption {
+    readonly name: string;
+    readonly kind?: "string" | "boolean" | undefined;
+    /** 单字母短名，`-n`。 */
+    readonly alias?: string | undefined;
+    readonly description?: string | undefined;
+    /** 缺省值。不给的话 string 选项缺席即 undefined，boolean 缺席即 false。 */
+    readonly defaultValue?: string | boolean | undefined;
+}
+export interface PluginCliInput {
+    /** 按声明的名字取；variadic 的那个是 `string[]`。 */
+    readonly arguments: Readonly<Record<string, string | readonly string[]>>;
+    readonly options: Readonly<Record<string, string | boolean | undefined>>;
+}
+/** 命令的输出通道。日志走 `ctx.log`，给人看的输出走这里。 */
+export interface PluginCliIo {
+    /** 写一行到 stdout。 */
+    readonly out: (line: string) => void;
+    /** 写一行到 stderr。 */
+    readonly err: (line: string) => void;
+}
+/**
+ * 一条 `ycodium x <pluginId> <name>` 子命令（路线图 #6）。
+ *
+ * 跑它的是 **CLI 进程**，不是服务器进程：那里没有编排引擎也没有数据库，所以
+ * `ctx.commands.dispatch` / `ctx.decisions` / `ctx.projections` / `ctx.providers` /
+ * `ctx.ports` 一律被拒（`reason: "host-unavailable"`）。`ctx.config` / `ctx.fs` /
+ * `ctx.http` / `ctx.process` / `ctx.cache` / `ctx.settings` 照常可用。
+ *
+ * 参数与选项是**声明**，由宿主翻成真正的命令行解析——插件不 import CLI 框架，
+ * `--help`、缺参报错、类型转换都由宿主给。
+ *
+ * 返回值即退出码：`undefined` / 0 表示成功，非 0 会让 `ycodium x` 以该码退出。
+ */
+export interface PluginCliCommand {
+    /** 插件内唯一；重名当场抛错。与 `ctx.command` 是两张名字表，可以同名。 */
+    readonly name: string;
+    readonly description?: string | undefined;
+    readonly arguments?: readonly PluginCliArgument[] | undefined;
+    readonly options?: readonly PluginCliOption[] | undefined;
+    readonly handle: (input: PluginCliInput, io: PluginCliIo) => void | number | Promise<void | number>;
+}
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IACjD,kBAAkB;IAClB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,yDAAyD;IACzD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACtD;AAED,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IACzE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC;CAC1E;AAED,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,mBAAmB;IACnB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,mBAAmB;IACnB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,iBAAiB,EAAE,GAAG,SAAS,CAAC;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,CACf,KAAK,EAAE,cAAc,EACrB,EAAE,EAAE,WAAW,KACZ,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC;CAC7C"}

package/dist/cli.js

@@ -0,0 +1,7 @@
+/**
+ * `ycodium x <pluginId> <name>` 子命令：`ctx.cli`。类型从 `index.ts` 再导出。
+ *
+ * @module @ycodium-ai/plugin-api/cli
+ */
+export {};
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/commands.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 插件命令与流式命令：`ctx.command`、`ctx.stream`，以及它们用的 JSON Schema 子集。类型与常量从
+ * `index.ts` 再导出。
+ *
+ * @module @ycodium-ai/plugin-api/commands
+ */
+/**
+ * 命令被调用时宿主知道的上下文。RPC 是全局作用域（thread-scoped 命令刻意
+ * 推迟），所以这里只有调用方的粗粒度信息；字段只增不改。
+ */
+export interface PluginCommandInvocation {
+    /** 调用方凭据已通过的 scope（"read" 或 "operate"）。 */
+    readonly scope: "read" | "operate";
+}
+/**
+ * JSON Schema，draft-07 的一个**白名单子集**。宿主自带编译器（仓库没有 JSON Schema
+ * 运行时依赖），认不出来的关键字一律编译期报错——插件 activate 当场失败，不会静默
+ * 变成"写了等于没写"。
+ *
+ * 下面这份清单**以 `apps/server/src/pluginHost/jsonSchema.ts` 为准**（`SUPPORTED_KEYWORDS`
+ * 与 `ANNOTATION_KEYWORDS` 两张表），那边改了这里跟着改。
+ *
+ * 支持：`type`（object / string / number / integer / boolean / array / null，也可以
+ * 写成数组表示可空）、`properties`、`required`、`additionalProperties`（布尔或
+ * schema）、`enum`、`const`、`items`（单个 schema，不支持元组形式）、
+ * `minimum` / `maximum` / `exclusiveMinimum` / `exclusiveMaximum`、
+ * `minLength` / `maxLength`、`pattern`（`u` flag 的 RegExp）、`minItems` / `maxItems`、
+ * `oneOf`（至少两个分支，恰好一个匹配才算过）。
+ * 另外接受但不校验这几个注解：`description`、`title`、`default`、`examples`、
+ * `$schema`、`$comment`。
+ *
+ * 判别联合就写 `oneOf`：共有字段留在同层的 `properties` / `required` 上（同层关键字
+ * 与分支一起生效），分支里只写判别键的 `const` 与那一支自己的 `required`，这样
+ * "status 是 ok 却没带 items" 会被挡在出口。
+ *
+ * 不支持：`$ref`、`anyOf` / `allOf` / `not`、`if` / `then` / `else`、
+ * `patternProperties`、`dependencies`、`format`。一个 `oneOf` 足够表达判别联合，
+ * 其余组合关键字是复杂度不换收益。
+ *
+ * 顶层形状只有 `payloadSchema` 有额外限制（必须 `"type": "object"`）；`resultSchema`
+ * 与 `itemSchema` 顶层随意。
+ */
+export type PluginJsonSchema = Record<string, unknown>;
+/**
+ * 请求-响应命令。客户端经宿主的 `plugins.invoke` 单信封调用；payload 在
+ * 信封入口按 payloadSchema 校验，不合格的请求不会到达 handle。handle 抛错
+ * 会以 handler-failed 的错误形状过线，message 原样透出——别把秘密放进异常。
+ *
+ * 要让调用方能**分辨**是哪一类失败，就在抛出的错误上挂一个字符串 `code`：宿主把
+ * 它原样放进过线错误的 `pluginCode`。过线错误的 `code` 字段是宿主自己的信封分类
+ * （plugin-unavailable / invalid-payload / forbidden / handler-failed），插件写不
+ * 进去；调用方也不该去 parse 人读的 message。
+ *
+ * 要让调用方**照着做**（等到几点再试之类），再挂一个 `data`：宿主做一次 JSON 往返
+ * 后放进过线错误的 `pluginData`。只有 JSON 值能过去，序列化不了的整个丢掉；形状由
+ * 插件与它的调用方约定，宿主不解释。速率限制的写法是 `{ retryAt: <epoch ms> }`。
+ */
+/**
+ * 宿主 contracts schema 的名字（如 `"UsageSummary"`），用来替代手写 JSON Schema。
+ *
+ * 只允许第一方包引用宿主已登记的名字；按 manifest 包名判断，目录与 npm 安装一致。
+ * 第三方包须声明自己的 JSON Schema；未知契约名在注册时失败。
+ *
+ * 与同一条命令上对应的 `*Schema` 字段**互斥**：两个都给是注册错误，一个都不给
+ * （payload 侧）也是注册错误。校验只判合法、不改值：contracts 里的
+ * `TrimmedNonEmptyString` 之类是 transformation，宿主丢弃 decode 的产物，命令的
+ * payload 与结果都按原值过线。
+ */
+export type PluginContractName = string;
+export interface PluginCommand {
+    /**
+     * 插件内唯一；跨插件由 pluginId 隔开，不会撞名。
+     *
+     * 同一插件内重复注册同名命令**当场抛错**，不顶掉旧的：命令名是过线的寻址键，静默
+     * 替换会让已经在飞的调用换了含义。抛在 `ctx.command` / `ctx.stream` 调用处，即
+     * activate 失败、整个插件挂载失败。`ctx.command` 与 `ctx.stream` 共用同一张名字表。
+     */
+    readonly name: string;
+    readonly description?: string | undefined;
+    /** 缺省 "read"。声明 "operate" 的命令要求调用方持有 operate 凭据。 */
+    readonly scope?: "read" | "operate" | undefined;
+    /**
+     * 顶层必须是 `"type": "object"`；handle 收到的就是它校验过的形状。与
+     * `payloadContract` 二选一，缺一不可。
+     */
+    readonly payloadSchema?: PluginJsonSchema | undefined;
+    /** 仅第一方插件：按名引用宿主注册表里的 contracts schema，替代 `payloadSchema`。 */
+    readonly payloadContract?: PluginContractName | undefined;
+    /**
+     * 可选。声明了，宿主就在**出口**按它校验 handle 的返回值：不合格的返回值不过线，
+     * 调用方收到 `invalid-result` 错误（detail 是 JSON Pointer 风格的第一条违例），
+     * 宿主同时打一条带 pluginId / command 的 warn。不声明就不校验，返回值原样过线。
+     *
+     * 与 `payloadSchema` 不同，**顶层不限于 `"type": "object"`**：结果可以是数组、
+     * 字符串、数字这类标量，用的是同一个编译器（同一份关键字白名单）。
+     *
+     * 声明它的价值在于形状漂移当场可见：命令结果的类型在插件与调用方两边各写一份，
+     * 只有出口校验能让"少了个字段"在运行期炸出来，而不是客户端拿到半个对象。
+     */
+    readonly resultSchema?: PluginJsonSchema | undefined;
+    /** 仅第一方插件：按名引用宿主注册表里的 contracts schema，替代 `resultSchema`。 */
+    readonly resultContract?: PluginContractName | undefined;
+    /** 返回值必须可 JSON 序列化；形状由插件与自己的 UI/调用方约定。 */
+    readonly handle: (payload: Record<string, unknown>, invocation: PluginCommandInvocation) => Promise<unknown> | unknown;
+}
+/**
+ * `buffer.latest` 的上限。留得越多，慢订阅方压在宿主内存里的东西越多——这个数封的
+ * 正是那个。够用就行：宿主自己的高频流留 8 条。
+ */
+export declare const MAX_PLUGIN_STREAM_BUFFER = 1024;
+/**
+ * 流式命令（`plugins.subscribe`）。emit 的每个值必须可 JSON 序列化；signal
+ * 中止表示订阅方挂断，handle 应尽快返回，之后的 emit 会被宿主静默丢弃。
+ */
+export interface PluginStreamCommand {
+    /** 与 `PluginCommand.name` 同一张表：重复即抛错，activate 失败。 */
+    readonly name: string;
+    readonly description?: string | undefined;
+    readonly scope?: "read" | "operate" | undefined;
+    /**
+     * 顶层必须是 `"type": "object"`；handle 收到的就是它校验过的形状。与
+     * `payloadContract` 二选一，缺一不可。
+     */
+    readonly payloadSchema?: PluginJsonSchema | undefined;
+    /** 仅第一方插件：按名引用宿主注册表里的 contracts schema，替代 `payloadSchema`。 */
+    readonly payloadContract?: PluginContractName | undefined;
+    /**
+     * 可选。声明了，宿主就在出口按它校验**每一个** emit 的值：出现不合格的值时这条流
+     * 立刻以 `invalid-result` 结束（此前已发出的值不撤回），并打一条带 pluginId /
+     * command 的 warn。不声明就不校验。
+     *
+     * 与 `resultSchema` 一样，**顶层不限于 `"type": "object"`** —— 只有 `payloadSchema`
+     * 那一处有这条限制。
+     */
+    readonly itemSchema?: PluginJsonSchema | undefined;
+    /** 仅第一方插件：按名引用宿主注册表里的 contracts schema，替代 `itemSchema`。 */
+    readonly itemContract?: PluginContractName | undefined;
+    /**
+     * 订阅方收得比你发得慢时，积压怎么办。
+     *
+     * **省略＝全留**（今天的行为），适合「跑一次就完」的流——diff 分片、扫描进度：
+     * 丢中间一块等于结果是错的，宁可积压。这类流的总量由那一次操作封顶，涨不到天上去。
+     *
+     * **持续推状态的流必须写 `{ latest: N }`**：只留最近 N 条，慢订阅方丢掉的是**旧的**。
+     * 一秒一份的快照配「全留」，订阅方一慢内存就一直涨——宿主自己的高频流用的正是这个
+     * 策略（`PubSub.sliding(8)`）。N 的上限见 `MAX_PLUGIN_STREAM_BUFFER`。
+     */
+    readonly buffer?: {
+        readonly latest: number;
+    } | undefined;
+    readonly handle: (payload: Record<string, unknown>, emit: (value: unknown) => void, signal: AbortSignal, invocation: PluginCommandInvocation) => Promise<void>;
+}
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAExC,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,oDAAoD;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACtD,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAC1D;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACrD,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACzD,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,CACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,UAAU,EAAE,uBAAuB,KAChC,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CACjC;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACtD,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAC1D;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACnD,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACvD;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,CACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EAC9B,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,uBAAuB,KAChC,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB"}

package/dist/commands.js

@@ -0,0 +1,12 @@
+/**
+ * 插件命令与流式命令：`ctx.command`、`ctx.stream`，以及它们用的 JSON Schema 子集。类型与常量从
+ * `index.ts` 再导出。
+ *
+ * @module @ycodium-ai/plugin-api/commands
+ */
+/**
+ * `buffer.latest` 的上限。留得越多，慢订阅方压在宿主内存里的东西越多——这个数封的
+ * 正是那个。够用就行：宿主自己的高频流留 8 条。
+ */
+export const MAX_PLUGIN_STREAM_BUFFER = 1024;
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4GH;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC"}

package/dist/decisions.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 问人：往会话里贴一张待决定的卡（`ctx.decisions`）。类型从 `index.ts` 再导出。
+ *
+ * @module @ycodium-ai/plugin-api/decisions
+ */
+import type { PluginDisposer } from "./index.ts";
+/** 卡上的一个按钮。`id` 是回答里回传的那个值，一张卡内唯一。 */
+export interface PluginDecisionOption {
+    /** 小写字母开头，`[a-zA-Z0-9._-]`。 */
+    readonly id: string;
+    readonly label: string;
+    /** 只影响按钮的显示档位；`danger` 用于「这一下会拆掉东西」。 */
+    readonly tone?: "default" | "primary" | "danger";
+}
+/**
+ * 一张待决定的卡。内容封顶四样：一行标题、几行说明、一块可折叠的文本或代码、
+ * 若干按钮。塞不进任意组件——渲染只有一份，web / mobile 一致。
+ */
+export interface PluginDecisionRequest {
+    /** 卡挂在哪条会话上。决定卡只有会话级，没有「与任何会话无关」的问法。 */
+    readonly threadId: string;
+    readonly title: string;
+    /** 说明行；给字符串就是一行。最多 8 行，超出截断。 */
+    readonly body?: string | readonly string[];
+    /** 折叠体。`language` 给了就按代码渲染。 */
+    readonly detail?: {
+        readonly label?: string;
+        readonly text: string;
+        readonly language?: string;
+    };
+    /** 1 到 5 个按钮，缺一个卡就按不下去。 */
+    readonly options: readonly PluginDecisionOption[];
+    /**
+     * 幂等键。同一个值重复贴只出一张卡（宿主会在前面加上 `plugin:<你的 id>:`）。
+     * 省略就由宿主发一个。
+     */
+    readonly requestId?: string;
+}
+export interface PluginDecisionAnswer {
+    readonly requestId: string;
+    readonly threadId: string;
+    /** 人按的那个按钮的 `id`。 */
+    readonly optionId: string;
+    readonly answeredAt: string;
+}
+export interface PluginDecisionHandle {
+    /** 宿主发的完整 id，`cancel` 与 `on` 里看到的就是它。 */
+    readonly requestId: string;
+}
+export type PluginDecisionHandler = (answer: PluginDecisionAnswer) => void | Promise<void>;
+/**
+ * 问一个人。**卡上带你的插件 id，用户看得见是谁在问**——所以这里没有权限门。
+ *
+ * 两种等法：`ask` 贴完就走，答案经 `on` 回来；`askAndWait` 等到有人按，
+ * `timeoutMs` 到点自动把卡作废并 resolve 成 null。长活儿用前者：等待占着一条
+ * Promise，插件被停用时它会以 null 收场。
+ *
+ * 没人答的卡会挡住这个项目的归档和拿掉文件夹；不再需要时用 `cancel` 收回。
+ */
+export interface PluginDecisions {
+    /** 贴一张卡就走。返回宿主发的 requestId。 */
+    readonly ask: (request: PluginDecisionRequest) => Promise<PluginDecisionHandle>;
+    /**
+     * 贴一张卡并等回答。超时、被作废、插件停用都 resolve 成 null，不 reject——
+     * 「没人回答」是正常结局，不是错误。
+     */
+    readonly askAndWait: (request: PluginDecisionRequest & {
+        readonly timeoutMs?: number;
+    }) => Promise<PluginDecisionAnswer | null>;
+    /** 收本插件贴的卡的回答。别的插件的卡收不到。 */
+    readonly on: (handler: PluginDecisionHandler) => PluginDisposer;
+    /**
+     * 收回一张还没人答的卡。已经答过的静默忽略。
+     * 没答的卡会挡住这个项目的归档；不再需要它时用这个收回。
+     */
+    readonly cancel: (requestId: string, summary?: string) => Promise<void>;
+}
+//# sourceMappingURL=decisions.d.ts.map

package/dist/decisions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisions.d.ts","sourceRoot":"","sources":["../src/decisions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,sCAAsC;AACtC,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC3C,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAClD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3F;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAChF;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,CACnB,OAAO,EAAE,qBAAqB,GAAG;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAC7D,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IAC1C,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,cAAc,CAAC;IAChE;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE"}

package/dist/decisions.js

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

package/dist/decisions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisions.js","sourceRoot":"","sources":["../src/decisions.ts"],"names":[],"mappings":""}

package/dist/definition.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 插件的默认导出：`PluginDefinition` 与 `definePlugin`。从 `index.ts` 再导出。
+ *
+ * @module @ycodium-ai/plugin-api/definition
+ */
+import type { ExecutorContribution } from "./executor.ts";
+import type { PluginApiVersion, PluginContext } from "./index.ts";
+export interface PluginDefinition<Config = Record<string, unknown>> {
+    /** 必须与 patch 条目 id 的后缀一致，否则宿主拒绝加载。 */
+    readonly id: string;
+    /** 静态声明插件针对的 API 版本，不能用宿主当前的运行时版本替代兼容性声明。 */
+    readonly apiVersion: PluginApiVersion;
+    /**
+     * 执行器贡献。缺席或空数组 = 普通功能插件。非空则 manifest 必须声明
+     * `{ kind: "executor" }`，否则拒载。名片在 activate 之前即可聚合。
+     */
+    readonly executors?: ReadonlyArray<ExecutorContribution>;
+    /** 超过 5 秒未返回视为加载失败，插件被隔离掉。 */
+    readonly activate: (ctx: PluginContext<Config>) => void | Promise<void>;
+}
+/**
+ * 只做类型锚定：默认导出经过它，宿主校验的字段就都被 TS 盯住了。
+ */
+export declare const definePlugin: <Config = Record<string, unknown>>(definition: PluginDefinition<Config>) => PluginDefinition<Config>;
+//# sourceMappingURL=definition.d.ts.map

package/dist/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAElE,MAAM,WAAW,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAChE,sCAAsC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IACzD,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,YAAY,gBAAgB,CAAC,MAAM,CAAC,KACnC,gBAAgB,CAAC,MAAM,CAAe,CAAC"}

package/dist/definition.js

@@ -0,0 +1,5 @@
+/**
+ * 只做类型锚定：默认导出经过它，宿主校验的字段就都被 TS 盯住了。
+ */
+export const definePlugin = (definition) => definition;
+//# sourceMappingURL=definition.js.map

package/dist/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"AAsBA;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,UAAoC,EACV,EAAE,CAAC,UAAU,CAAC"}

package/dist/derivedState.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 托管的跨事件状态：`ctx.derivedState`。类型从 `index.ts` 再导出。
+ *
+ * @module @ycodium-ai/plugin-api/derivedState
+ */
+import type { PluginEvent } from "./events.ts";
+/**
+ * 一块由事件折出来的状态,宿主替你记住、替你重建。
+ *
+ * 什么时候用它:你要记住的东西跨事件、跨重启（看板、名册、信箱）。**别把这种东西攒
+ * 在插件的模块变量或 Map 里** —— 插件停用、宿主重启、会话换进程,那份内存就没了,
+ * 而且没有任何东西会告诉你它没了。
+ *
+ * 只有一条硬规矩,但它排掉一整类缺陷:**`apply` 必须是纯函数**。同样的入参给同样的
+ * 结果,不读时钟、不读随机数、不发请求、不改传进来的 `state`（返回新值）。它会被跑
+ * 两次——事件来的时候一次,重启重建的时候一次——不纯就意味着两次结果不同,而你只会
+ * 在重启之后才发现。
+ *
+ * 状态必须能 JSON 序列化。宿主不校验它的形状:改了形状就把 `version` 加一,宿主会
+ * 丢掉旧的从头重折。不加,旧状态会带着旧规则一直用下去。
+ */
+export interface PluginDerivedState<S> {
+    /** 你自己的名字,插件内唯一。宿主会加上你的插件 id 做前缀,和别人撞不上。 */
+    readonly key: string;
+    /** 折法或状态形状改了就 +1。宿主据此丢掉旧的重折。 */
+    readonly version: number;
+    /** 只折这些事件类型;省略表示全收。过滤在宿主侧做,不进你的进程时间。 */
+    readonly events?: readonly string[] | undefined;
+    /** 空状态。重建从这里起折。 */
+    readonly init: () => S;
+    /** 纯折叠。不许就地改 `state`。 */
+    readonly apply: (state: S, event: PluginEvent) => S;
+}
+/** `ctx.derivedState` 给回来的把手。 */
+export interface PluginDerivedStateHandle<S> {
+    /**
+     * 此刻的状态。在 `reactor` / `events.onRaw` 处理器里读到的,**已经含当前这条事件**
+     * ——宿主先推进状态再把事件发给你。
+     * 指定 throughSequence 会直接补读已提交日志,保证包含该序号;不等待 reactor 队列。
+     * 未提交的未来序号会拒绝,不会挂起等待。
+     */
+    readonly get: (options?: {
+        readonly throughSequence: number;
+    }) => Promise<S>;
+}
+//# sourceMappingURL=derivedState.d.ts.map

package/dist/derivedState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derivedState.d.ts","sourceRoot":"","sources":["../src/derivedState.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wCAAwC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAChD,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvB,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,KAAK,CAAC,CAAC;CACrD;AAED,iCAAiC;AACjC,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9E"}

package/dist/derivedState.js

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

package/dist/derivedState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derivedState.js","sourceRoot":"","sources":["../src/derivedState.ts"],"names":[],"mappings":""}