@ycodium-ai/plugin-api 0.2.3671 → 0.2.3710

package/README.md

@@ -56,7 +56,7 @@ import { definePlugin } from "@ycodium-ai/plugin-api";
 
 export default definePlugin({
   id: "my-plugin",
-  apiVersion: 51,
+  apiVersion: 53,
   activate: (ctx) => {
     ctx.log.info("hello");
 
@@ -285,12 +285,108 @@ 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 53, 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 53. 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 53 is refused until Ycodium itself is updated, with no update button.
+
+API 53 moves the board's general rules into the host: the host delivers mentions, replies and completion notices,
+and a plugin adds its own rules through two interfaces instead of dispatching by itself.
+
+- The `work.dispatch` guard is now a dispatch gate. Its input gains `reason` (`item`, `comment` or `group`), the
+  `threadId` the host picked for the member (`null` when it would open a new one), and `commentId` / `recordId` for
+  comments and group messages; `workItemId` is `null` for a group message. `allowed: false` now means "not now"
+  (the host asks again on the next trigger or the minute sweep), no longer "my plugin dispatches this". Without a
+  plugin the host dispatches as usual. Plugins that read the old input must handle the new fields. An
+  `{ allowed: true }` answer may carry `threadId`: the host then delivers and wakes in that session (same project, not
+  archived or deleted, otherwise it holds) instead of the one it picked, with the same de-duplication, supplements and
+  hand-over record. Plugins pointing the member to different sessions hold the wake.
+- New `ctx.operations.supplement({ operations: ["work.dispatch"], add })`: before the host wakes a member for an
+  item, `add(input: PluginWakeSupplementInput)` returns text appended to the host's wake message (`null` adds
+  nothing). A throw or a 5 second timeout holds the wake until the next trigger.
+- Raw events gain `work.item-dispatched` (the host handed an item to a member's session; needs `work.read`).
+  `communication.record-sent` and record views carry an optional `workItem` when the record is a board delivery.
+- History gains the verbs `paused`, `resumed`, `trial-passed`, `trial-failed` and `trial-skipped`, the target
+  kind `member`, and the change fields `member` and `note`. A history page skips entries and changes the reader
+  does not know, so later additions no longer fail the page.
+- Arrays that tolerate newer elements are typed with their element instead of `unknown` on the encoded side: the UI
+  reads `work.history.list`, `threads.history`, `plugins.installed.list` and the machine settings reads of editors,
+  providers and keybindings.
+
+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 52 also adds machine browser viewport and page zoom, site data clearing, developer tools, the context menu and clipboard, downloads, and cookie import:
+
+- Human page input (`threads.browser.input`) also accepts `setViewport` and `setZoom`. Page state also carries
+  optional `viewportSetting` and `zoomFactor`.
+- Human page input also accepts `clearCookies` and `clearCache` (clear that profile's cookies or HTTP cache;
+  people and agents share the profile). The machine capabilities in `machineSettings.config.get` gain optional
+  `browserZoomOperations`, `browserSiteDataOperations`, and `browserDevtoolsOperations` (`openDevTools`).
+- Humans also get `threads.browser.context` (selection, link, and image for the local clipboard) and an optional
+  `editingCommand` of `Cut`, `Copy`, or `SelectAll` on key input.
+- Humans also get `threads.browser.downloadUrl`, a signed URL, valid for five minutes, for a finished file from a
+  machine page. The file stays on that machine; the URL stops working when the page closes or agent access to
+  its profile is turned off. The new port `threads.browser.downloadCancel` cancels a running download or clears
+  a finished one and deletes its file on the machine. Plugins declare `thread.browser.download.cancel` and are
+  refused with `agent-access-denied` when the page's profile has agent access turned off. Download entries in
+  the page state gain an optional `stalled` flag for a running download with no progress for a while.
+- Humans, agents, and plugins that declare `machineSettings.browser.cookies.import` can call
+  `machineSettings.browser.cookies.firefoxProfiles`, `machineSettings.browser.cookies.chromiumProfiles`
+  and `machineSettings.browser.cookies.import` (counts only, with no cookie names, values, or domains;
+  Firefox is read on that machine by an opaque id; `chromiumProfiles` lists Chrome, Edge, Brave and other
+  Chromium-family profiles on that machine by browser key, profile directory name, and display name, and an
+  import source of kind `chromium` takes that browser and directory name and decrypts the cookies on that
+  machine with its system key store; a rejection reason `unsupported` means they cannot be decrypted there;
+  agents and plugins are refused when that profile's agent access is off, and turning it off stops an import in progress; the profile must exist, otherwise `profile-not-found`).
+- Session snapshots gain an optional `favicon` (PNG data URL, origin, and capture time). `browser.reportStatus`
+  may omit `favicon`, send `null`, or send an icon: omission keeps the current icon and `null` clears it.
+- Page state's optional `downloads` lists each download of the page with `id`, `fileName`, `state`, `receivedBytes`, `fetchable`, and optional `totalBytes`, `stalled` and `leftover`; there is no count limit. `leftover` marks a download of a page that has closed whose file could not be deleted on the machine yet: every page on that profile lists it, and `threads.browser.downloadCancel` with its `id` retries the deletion. `threads.browser.downloadCancel` is refused with `cancel-unconfirmed` when the browser does not confirm stopping the download, and with `cleanup-failed` when the file could not be deleted on the machine; the download stays listed and calling again retries. Machine settings reads and writes gain optional `machineBrowserDefaultViewport`, `machineBrowserDefaultZoomFactor`, and `machineBrowserDefaultAppearance` (the starting values of new machine pages). `BrowserAutomationOperation` gains `setZoom`, `clearCookies`, `clearCache`, and `openDevTools`. A favicon's `capturedAt` is an integer in milliseconds.
+
+The machine browser additions in API 52 are additive.
+
+API 52 also adds one rule for which model option is the reasoning effort (same unreleased window):
+`isReasoningEffortOptionId(id)` and `findReasoningEffortDescriptor(descriptors)` (from `@ycodium-ai/plugin-api` and
+`/executor`). `effort`, `reasoningEffort`, `reasoning` and `variant` count; `fastMode`, `agent` and `serviceTier` get
+their own titles but are not the reasoning effort. Executors that read the actual model only after
+`turn.started` (a CLI's init message, or the reply to an in-session model switch) report it with a
+`thread.metadata.updated` event for that turn, whose payload may now carry `model` and `modelSource`
+(`reported` or `echo`; absent means `echo`). The host records it with the same rule as `turn.started`'s `model`:
+within one selection an `echo` is upgraded to `reported`, a `reported` is never overwritten. Additive.
 
 API 51 adds team state on the board and board dispatch, and the host side of model choice:
 
@@ -891,7 +987,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 53.
 
 API 8 changed what the UI gets for a communication record. `ConversationCommunicationRecord`
 (from the conversation host's `useCommunicationRecord`) and `CommunicationViewExchange` carry `bodyState`, and their