@ycodium-ai/plugin-api 0.2.3671 → 0.2.3681

package/README.md

@@ -56,7 +56,7 @@ import { definePlugin } from "@ycodium-ai/plugin-api";
 
 export default definePlugin({
   id: "my-plugin",
-  apiVersion: 51,
+  apiVersion: 52,
   activate: (ctx) => {
     ctx.log.info("hello");
 
@@ -285,12 +285,47 @@ sessions continue using the streaming process interface.
 
 ## THERE WILL BE COMPATIBILITY-BREAKING CHANGES
 
-The definition's `apiVersion` is a closed window: the host loads 51, and refuses every other
+The definition's `apiVersion` is a closed window: the host loads 52, 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 51. Plugins
+`PLUGIN_API_VERSION` to make the declaration automatically match. The current API is 52. 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 51 is refused until Ycodium itself is updated, with no update button.
+declares a version newer than 52 is refused until Ycodium itself is updated, with no update button.
+
+API 52 brings the board's second batch, and narrows a member's `identity` to a person (see the member model below).
+The board part is additive:
+
+- Work items carry `priority` (`urgent`, `high`, `medium`, `low`, `none`) and `labelIds` on create, update and every
+  read; summaries carry `archivedAt`. `ctx.work.items.list` filters by `priorities`, `labelIds` and `archived`
+  (`exclude` by default, `include`, `only`) and orders by `priority`.
+- `ctx.work.items.archive` / `unarchive` (declare `work.item.archive` / `work.item.unarchive`) take a completed or
+  cancelled item off the board and bring it back.
+- `ctx.work.labels.list` / `create` / `update` / `remove` / `restore` manage a project's labels (declare
+  `work.label.create` / `update` / `remove` / `restore`).
+- `ctx.work.states.create` / `update` / `remove` / `restore` manage custom states (declare `work.state.*`). Removing a
+  state that items still use needs `replacementStateId`, a state in the same group; the default state and the last
+  state of a group cannot be removed. `ctx.work.states.list` takes `includeRemoved`; state views carry `removedAt`.
+- `ctx.work.comments.list` (by item) and `ctx.work.history.list` take an optional `order`: `newest` reads the latest
+  first and the cursor pages back (the cursor is bound to the order).
+- History changes gain the `priority` and `labels` fields. Raw events gain `work.item-archived`,
+  `work.item-unarchived`, `work.label-created` / `updated` / `removed` / `restored` and `work.state-created` /
+  `updated` / `removed` / `restored` (need `work.read`).
+
+API 52 also unifies the member model (same unreleased window). `MemberIdentity` narrows to a person; the remote
+agent identity is gone:
+
+- A member's `identity` is only ever a person (`kind: "human"`). An agent member always has an `agent` segment, and
+  `agent.environmentId` is the only answer to "which machine": a member on another machine names that machine there.
+  Members recorded against a remote agent before this read back with `identity: null` and `agent: null` until a person
+  picks a machine for them.
+- New port `ctx.projects.machines.list` lists the other machines that joined a project: `environmentId`, `name`,
+  `online`, `lastSeenAt`, and the providers each one reported (instance, display name, default model; pass
+  `includeModels: true` to also get each provider's models, which are left out by default). Join
+  codes, removing a machine, joining and leaving (`ctx.projects.machines.joinCode.create`, `remove`, `join`, `leave`)
+  are for people only; a plugin can use them only inside an operator invocation.
+- `work.remoteAgentPending.get` takes an optional `memberId` (that member's work and messages plus those sent to the
+  machine itself). Remote pending items and wakes carry an optional `memberId`, and the remote participant in communication records
+  (`kind: "remote-agent"`) carries an optional `memberId` naming the member on that machine.
 
 API 51 adds team state on the board and board dispatch, and the host side of model choice:
 
@@ -891,7 +926,7 @@ An empty page with a cursor still continues. All failures propagate unchanged, i
 `ThreadNotFoundError` when the thread is missing; use `isThreadNotFound(error)` to identify it.
 `ctx.communication.inbox.read` is gone; that port always rejected a plugin, because only the agent
 in the thread has its own inbox. Plugins targeting these earlier versions are refused on the current host;
-the minimum version is 51.
+the minimum version is 52.
 
 API 8 changed what the UI gets for a communication record. `ConversationCommunicationRecord`
 (from the conversation host's `useCommunicationRecord`) and `CommunicationViewExchange` carry `bodyState`, and their