@ycodium-ai/plugin-api 0.2.2972 → 0.2.2976

package/README.md

@@ -56,7 +56,7 @@ import { definePlugin } from "@ycodium-ai/plugin-api";
 
 export default definePlugin({
   id: "my-plugin",
-  apiVersion: 4,
+  apiVersion: 5,
   activate: (ctx) => {
     ctx.log.info("hello");
 
@@ -230,13 +230,25 @@ shows up there without anyone registering it.
 
 ## THERE WILL BE COMPATIBILITY-BREAKING CHANGES
 
-The definition's `apiVersion` is a closed window: the host loads 3 and 4, and refuses every other
+The definition's `apiVersion` is a closed window: the host loads 5, and refuses every other
 value. Declare the version your plugin targets as a literal; do not read the host's
-`PLUGIN_API_VERSION` to make the declaration automatically match. The current API is 4. Plugins
-that still declare 3 continue to load. Plugins targeting API 1 or 2 are refused before activation;
-the message names the version the plugin declared and the ones this Ycodium loads, and the plugin
-card offers an update. A plugin that declares a version newer than 4 is refused until Ycodium
-itself is updated, with no update button.
+`PLUGIN_API_VERSION` to make the declaration automatically match. The current API is 5. Plugins
+targeting an older API are refused before activation; the message names the version the plugin
+declared and the one this Ycodium loads, and the plugin card offers an update. A plugin that
+declares a version newer than 5 is refused until Ycodium itself is updated, with no update button.
+
+API 5 removed four handwritten data members. Their replacements are assembled from the host's data
+capability table and typed by `PluginDataPorts`: the member path is the capability id, the input is
+checked against the capability's public contract, and the result is the same shape a client reads.
+
+| Removed in 5                               | Use instead                                                                                                                                         |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.projections.listThreads(query)`       | `ctx.threads.list(input)`: returns `{ items, nextCursor, snapshotSequence }`; `includeArchived` became `archived: "exclude" \| "include" \| "only"` |
+| `ctx.projections.listPendingApprovals(id)` | `ctx.approvals.pending.list({ threadId })`: `detail`, `appName` and `options` are absent when the provider gave none; a missing thread rejects      |
+| `ctx.communication.listForThreads(input)`  | `ctx.communication.records.list(input)`: same fields; a `limit` outside 1–1000 is refused instead of clamped                                        |
+| `ctx.communication.getByIds(recordIds)`    | `ctx.communication.records.get({ recordIds })`: at most 100 ids per call; records carry every field a client reads                                  |
+
+`ctx.threads.history(input)` is new in 5: the thread detail a client opens a session with.
 
 ### API 4
 
@@ -272,6 +284,20 @@ your plugin's install, so you only see receipts for commands your plugin dispatc
 `threadId` may be left out for them; commands on an existing thread still need `threadId` and
 thread ownership. Both are optional additions, so the API version was not bumped.
 
+Added within API 4, for a plugin that draws its own settings in the `settings.section` seat. None
+of these bumped the API version.
+
+- `presentation: "hidden"` on `ctx.settingsCard`: clients stop drawing the card's form. Keep the
+  field declarations: a `kind: "proxy"` field is how the host knows which proxy you use, and
+  `password` fields and columns are how it knows which positions are secrets.
+- `clearSecrets` in the options of `ctx.settings.write`: paths whose stored password is removed.
+  The host drops the key at each path from the config it writes, whatever you put there. A path
+  listed in both `secrets` and `clearSecrets` rejects the write.
+- `bridge.ui.QRCodeSvg` and `bridge.ui.ProxyChoiceSelect`, typed by `QRCodeSvgProps` and
+  `ProxyChoiceSelectProps` in `@ycodium-ai/plugin-api/ui`. The proxy select draws the options you
+  pass it; get them from `ctx.proxies.list()` in a command of your own. An older host does not
+  have them, so check that they exist before rendering.
+
 ### API 3
 
 API 3 deletes the host's old usage path and fixes the executor contract that the built-in agents
@@ -308,12 +334,12 @@ Added (all optional unless noted):
   `placeholderKey`) resolved from the plugin's own `locales/`, and the pure validation helpers
   are published as `@ycodium-ai/plugin-api/settings-card`.
 - `ctx.fs.createReadStream(path, { start, end })` reads an inclusive byte range.
-- `ctx.communication.listForThreads({ threadIds, since, until, before, limit })` (**required** on the context):
-  read-only host communication records that have a side in those threads, newest `limit` in time
-  order, with their three stages. Subscribe to the `communication.record-*` events to re-read.
-  `ctx.communication.getByIds(recordIds)` (**required** on the context) reads up to
-  `PLUGIN_COMMUNICATION_MAX_RECORDS` (1000) records by id, skipping unknown ids; stage events name only the owning thread, so read a record back to see
-  both sides.
+- `ctx.communication.records.list({ threadIds, since, until, before, limit })` (**required** on the
+  context): read-only host communication records that have a side in those threads, newest `limit`
+  in time order, with their three stages. Subscribe to the `communication.record-*` events to
+  re-read. `ctx.communication.records.get({ recordIds })` (**required** on the context) reads up to
+  100 records by id, skipping unknown ids; stage events name only the owning thread, so read a
+  record back to see both sides.
 - Conversation views: tool rows may carry `toolIcon`, and `ConversationHostData.SiteIcon` draws
   a site icon. Trajectory rows for a sent message carry `communication` (record id, delivery,
   recipient with its thread title), and `ConversationHostData.useCommunicationRecord` watches

package/dist/communication.d.ts

@@ -1,86 +1,20 @@
 /**
- * 宿主通信记录的只读查询（`ctx.communication`）。会话之间、会话与人之间每发一句，宿主记一条
- * 记录，带三段状态：落盘、已交给 agent（收件方取件了）、已回。从包根导出。
+ * 宿主通信记录的形状。会话之间、会话与人之间每发一句，宿主记一条记录，带三段状态：落盘、已交给 agent
+ * （收件方取件了）、已回。从包根导出。
  *
- * 只读：发信走编排工具 `send_message`，插件写不了记录。
+ * 读走登记表组装的端口 `ctx.communication.records.get` / `ctx.communication.records.list`（见
+ * `PluginDataPorts`）；这里的两个名字是它们返回的那份记录。只读：发信走编排工具 `send_message`。
  *
  * @module @ycodium-ai/plugin-api/communication
  */
+import type { CommunicationRecordsGetOutput } from "./dataPorts.gen.ts";
+/**
+ * 一条通信记录，与客户端读到的同一份。`delivery`：`quiet` 等收件方下次取件，`wake` 叫醒收件方，`steer` 插进
+ * 收件方正在跑的那一轮。`stages.handedOff.certainty`：`confirmed` 是收件方取件了，`not-dispatched` 是还没取，
+ * `unknown` 是投递结果不明（不会重投）。`stages.replied` 带 `recordId` 是收件方那条回信，只有 `turnId` 表示
+ * 处理它的那一轮结束了。`to` 只有回填的历史团队消息在角色当时没人挂接时才是 null。
+ */
+export type PluginCommunicationRecord = CommunicationRecordsGetOutput[number];
 /** 记录的一方：会话（一个会话就是一个 agent）或人（账号快照）。 */
-export type PluginCommunicationParticipant = {
-    readonly kind: "thread";
-    /** 缺省 = 记录所在的这台机器；从旧团队信箱回填的历史记录一律缺省。 */
-    readonly environmentId?: string | undefined;
-    readonly threadId: string;
-} | {
-    readonly kind: "user";
-    readonly userId: string;
-    readonly displayName: string;
-};
-export interface PluginCommunicationRecord {
-    readonly recordId: string;
-    readonly from: PluginCommunicationParticipant;
-    /** 只有回填的历史团队消息在角色当时没人挂接时才是 null。 */
-    readonly to: PluginCommunicationParticipant | null;
-    /** 这条在回哪一条。 */
-    readonly replyTo: string | null;
-    readonly text: string;
-    /** `quiet` 等收件方下次取件；`wake` 叫醒收件方；`steer` 插进收件方正在跑的那一轮。 */
-    readonly delivery: "quiet" | "wake" | "steer";
-    readonly createdAt: string;
-    readonly stages: {
-        /** 落盘时刻，与 `createdAt` 同值。 */
-        readonly persisted: string;
-        /**
-         * 交给 agent：`confirmed` 是收件方取件了；`not-dispatched` 是还没取；`unknown` 是投递结果
-         * 不明（不会重投）。
-         */
-        readonly handedOff: {
-            readonly certainty: "not-dispatched" | "confirmed" | "unknown";
-            /** 确认凭的是什么：`pickup` 是收件方自己取走了正文。旧记录当时没记，就没有这一格。 */
-            readonly evidence?: "pickup" | undefined;
-            readonly turnId?: string | undefined;
-            readonly at?: string | undefined;
-        };
-        /** 回了：`recordId` 是收件方那条回信（界面显示「已回」）；只有 `turnId` 表示处理它的那一轮结束了。 */
-        readonly replied: {
-            readonly recordId?: string | undefined;
-            readonly turnId?: string | undefined;
-            readonly at: string;
-        } | null;
-    };
-}
-/** 一次最多取这么多条：`listForThreads` 的 `limit` 与 `getByIds` 的号数都以它为上限。 */
-export declare const PLUGIN_COMMUNICATION_MAX_RECORDS = 1000;
-export interface PluginCommunicationListForThreadsInput {
-    /** 一方（发件或收件）落在这些会话里的记录都算。 */
-    readonly threadIds: readonly string[];
-    /** 只要这一刻（ISO 时间）之后落盘的；缺省从头取。 */
-    readonly since?: string | null | undefined;
-    /**
-     * 只要这一刻（ISO 时间）及之前落盘的；缺省不限。按它过滤发生在取 `limit` 条之前，所以一页
-     * 不满就说明这个范围里更早的已经没有了（已结束的 run 按结束时间传它）。
-     */
-    readonly until?: string | null | undefined;
-    /**
-     * 往上翻页：只要排在这条记录之前的（按落盘时间、同一刻再按记录号）。传手里最旧那条的
-     * `recordId`；这条记录不存在时结果为空。缺省从最新取。
-     */
-    readonly before?: string | null | undefined;
-    /** 取最新的多少条，缺省 200，最多 1000。 */
-    readonly limit?: number | undefined;
-}
-export interface PluginCommunication {
-    /**
-     * 一方落在这些会话里的记录，取最新的 `limit` 条，按落盘时间从旧到新返回。`threadIds` 为空
-     * 返回空数组。三段状态是读那一刻的值；要跟着变，订 `communication.record-sent`、
-     * `communication.record-handed-off`、`communication.record-replied` 三种事件后重读。
-     */
-    readonly listForThreads: (input: PluginCommunicationListForThreadsInput) => Promise<readonly PluginCommunicationRecord[]>;
-    /**
-     * 按记录号取记录，一次最多 1000 个；不存在的号跳过，返回顺序不保证。用来跟着三种通信事件
-     * 更新手里那几条：阶段事件只带归属会话，不带两端，要判一条记录属于谁就按号读回来。
-     */
-    readonly getByIds: (recordIds: readonly string[]) => Promise<readonly PluginCommunicationRecord[]>;
-}
+export type PluginCommunicationParticipant = PluginCommunicationRecord["from"];
 //# sourceMappingURL=communication.d.ts.map

package/dist/communication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"communication.d.ts","sourceRoot":"","sources":["../src/communication.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wCAAwC;AACxC,MAAM,MAAM,8BAA8B,GACtC;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAErF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,8BAA8B,CAAC;IAC9C,oCAAoC;IACpC,QAAQ,CAAC,EAAE,EAAE,8BAA8B,GAAG,IAAI,CAAC;IACnD,eAAe;IACf,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE;QACf,6BAA6B;QAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B;;;WAGG;QACH,QAAQ,CAAC,SAAS,EAAE;YAClB,QAAQ,CAAC,SAAS,EAAE,gBAAgB,GAAG,WAAW,GAAG,SAAS,CAAC;YAC/D,mDAAmD;YACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;YACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;YACrC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;SAClC,CAAC;QACF,iEAAiE;QACjE,QAAQ,CAAC,OAAO,EAAE;YAChB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;YACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;YACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;SACrB,GAAG,IAAI,CAAC;KACV,CAAC;CACH;AAED,mEAAmE;AACnE,eAAO,MAAM,gCAAgC,OAAO,CAAC;AAErD,MAAM,WAAW,sCAAsC;IACrD,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,gCAAgC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC5C,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,CACvB,KAAK,EAAE,sCAAsC,KAC1C,OAAO,CAAC,SAAS,yBAAyB,EAAE,CAAC,CAAC;IACnD;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,CACjB,SAAS,EAAE,SAAS,MAAM,EAAE,KACzB,OAAO,CAAC,SAAS,yBAAyB,EAAE,CAAC,CAAC;CACpD"}
+{"version":3,"file":"communication.d.ts","sourceRoot":"","sources":["../src/communication.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,oBAAoB,CAAC;AAExE;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,6BAA6B,CAAC,MAAM,CAAC,CAAC;AAE9E,wCAAwC;AACxC,MAAM,MAAM,8BAA8B,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC"}

package/dist/communication.js

@@ -1,11 +1,2 @@
-/**
- * 宿主通信记录的只读查询（`ctx.communication`）。会话之间、会话与人之间每发一句，宿主记一条
- * 记录，带三段状态：落盘、已交给 agent（收件方取件了）、已回。从包根导出。
- *
- * 只读：发信走编排工具 `send_message`，插件写不了记录。
- *
- * @module @ycodium-ai/plugin-api/communication
- */
-/** 一次最多取这么多条：`listForThreads` 的 `limit` 与 `getByIds` 的号数都以它为上限。 */
-export const PLUGIN_COMMUNICATION_MAX_RECORDS = 1000;
+export {};
 //# sourceMappingURL=communication.js.map

package/dist/communication.js.map

@@ -1 +1 @@
-{"version":3,"file":"communication.js","sourceRoot":"","sources":["../src/communication.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA8CH,mEAAmE;AACnE,MAAM,CAAC,MAAM,gCAAgC,GAAG,IAAI,CAAC"}
+{"version":3,"file":"communication.js","sourceRoot":"","sources":["../src/communication.ts"],"names":[],"mappings":""}