@ycodium-ai/plugin-api 0.2.3208 → 0.2.3210

package/README.md

@@ -56,7 +56,7 @@ import { definePlugin } from "@ycodium-ai/plugin-api";
 
 export default definePlugin({
   id: "my-plugin",
-  apiVersion: 19,
+  apiVersion: 20,
   activate: (ctx) => {
     ctx.log.info("hello");
 
@@ -239,12 +239,24 @@ shows up there without anyone registering it.
 
 ## THERE WILL BE COMPATIBILITY-BREAKING CHANGES
 
-The definition's `apiVersion` is a closed window: the host loads 19, and refuses every other
+The definition's `apiVersion` is a closed window: the host loads 20, 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 19. Plugins
+`PLUGIN_API_VERSION` to make the declaration automatically match. The current API is 20. 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 19 is refused until Ycodium itself is updated, with no update button.
+declares a version newer than 20 is refused until Ycodium itself is updated, with no update button.
+
+API 20 adds `ctx.machineSettings.editors.get` and `ctx.machineSettings.providers.get`; neither
+requires a declared permission. `ctx.threads.list` accepts optional `collection: "page" | "all"`
+and an optional `include` array containing `"summary"` and/or `"runtime"`. Its result has optional `historyEpoch`, and each row
+has optional `summary` and `runtime` blocks requested through `include`. The result of
+`ctx.threads.history` also has optional `historyEpoch`; plugins must handle its absence.
+`ProxyChoiceOption` is now exported from the main `@ycodium-ai/plugin-api` entry so server code can
+use it; `@ycodium-ai/plugin-api/ui` still re-exports it, so existing imports keep working.
+Manifest pages accept optional `ui.pages[].placements`, an array of `"web-pages"`, `"mobile-home"` and
+`"mobile-pages"` decoded strictly (D389). Omitted, a page appears only in the web and mobile-settings
+plugin page lists; an array shows it only where listed, an empty array shows it nowhere. Direct routes
+to the page are not restricted.
 
 API 19 adds the data port `ctx.machineSettings.keybindings.get` (the machine's key bindings and the issues found while reading them; no permission needed) and optional `ConversationHostData.useCommandFailureText`. Its hook returns a function that explains failures of dispatched commands. During preparation it returns `null`, so the plugin keeps the original error. When an older host omits the hook, the plugin also displays the original error (D386).
 
@@ -367,7 +379,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 19.
+the minimum version is 20.
 
 API 8 changed what the UI gets for a communication record. `ConversationCommunicationRecord`
 (from the conversation host's `useCommunicationRecord`) and `CommunicationViewExchange` carry `bodyState`, and their
@@ -395,12 +407,12 @@ API 5 removed four handwritten data members. Their replacements are assembled fr
 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                                  |
+| Removed in 5                               | Use instead                                                                                                                                                                                                                              |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.projections.listThreads(query)`       | `ctx.threads.list(input)`: returns `{ items, nextCursor, snapshotSequence, historyEpoch? }`; accepts `archived: "exclude" \| "include" \| "only"`, `collection: "page" \| "all"` (default `page`), and `include: ["summary", "runtime"]` |
+| `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.