@ycodium-ai/plugin-api 0.2.3681 → 0.2.3710

package/README.md

@@ -56,7 +56,7 @@ import { definePlugin } from "@ycodium-ai/plugin-api";
 
 export default definePlugin({
   id: "my-plugin",
-  apiVersion: 52,
+  apiVersion: 53,
   activate: (ctx) => {
     ctx.log.info("hello");
 
@@ -285,12 +285,35 @@ sessions continue using the streaming process interface.
 
 ## THERE WILL BE COMPATIBILITY-BREAKING CHANGES
 
-The definition's `apiVersion` is a closed window: the host loads 52, 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 52. 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 52 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:
@@ -327,6 +350,44 @@ agent identity is gone:
   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:
 
 - Work line reads (`ctx.work.lines.list` / `get`) carry optional `pause` (`{ at, by, reason? }`, the whole line is
@@ -926,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 52.
+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