@ycodium-ai/plugin-api 0.2.3484 → 0.2.3502

package/README.md

@@ -56,7 +56,7 @@ import { definePlugin } from "@ycodium-ai/plugin-api";
 
 export default definePlugin({
   id: "my-plugin",
-  apiVersion: 39,
+  apiVersion: 41,
   activate: (ctx) => {
     ctx.log.info("hello");
 
@@ -260,14 +260,80 @@ npm search keywords:ycodium-plugin
 Ycodium's plugin settings search the same way, so a published package with that keyword
 shows up there without anyone registering it.
 
+## Auxiliary executor operations
+
+Forward the host's abort signal through every auxiliary operation, including
+`readCliVersion(signal)` and `refreshModelCatalog({ force, signal })`.
+The host cancels each completed or interrupted operation and waits for its work and owned processes
+to settle; instance disposal closes the boundary to new operations.
+
+Import `runProcessOperation` from `@ycodium-ai/plugin-api/process-operation` for a one-shot command.
+It owns concurrent stdout/stderr consumption, bounded output, input writes, cancellation, deadlines
+and process teardown. Nonzero exit codes remain results for the executor to interpret. Output beyond
+the configured cap is drained and rejected, never returned as a complete answer.
+
+Use `withProcessOperation` for SDK or protocol reads. Start children through `operation.spawn`,
+register consumer promises with `track`, and register protocol cleanup with `defer`. The protocol
+keeps sole ownership of its output parser. Cleanup has a separate bounded budget; a late spawn still
+belongs to the closing operation. If `isOperationCleanupError(error)` is true, retain temporary
+directories and preserve the error for the host rather than wrapping it as a normal generation error.
+
+Shared servers belong to the executor instance, with balanced borrowing and release. Cancelling one
+borrower must not kill another borrower's server. Instance disposal must stop new borrowing and clear
+idle timers; an externally configured server is never owned by this operation. Long-lived conversation
+sessions continue using the streaming process interface.
+
 ## THERE WILL BE COMPATIBILITY-BREAKING CHANGES
 
-The definition's `apiVersion` is a closed window: the host loads 39, and refuses every other
+The definition's `apiVersion` is a closed window: the host loads 41, 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 39. Plugins
+`PLUGIN_API_VERSION` to make the declaration automatically match. The current API is 41. 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 39 is refused until Ycodium itself is updated, with no update button.
+declares a version newer than 41 is refused until Ycodium itself is updated, with no update button.
+
+API 41 adds the `process-operation` executor utility, forwards cancellation through auxiliary calls,
+and waits for their cleanup before releasing the operation. `readCliVersion` and `refreshModelCatalog`
+accept cancellation signals. Plugins must preserve incomplete-cleanup errors and retain temporary
+resources until cleanup is confirmed. See [Auxiliary executor operations](#auxiliary-executor-operations).
+
+API 40 adds what a project with several folders on one machine needs, and hands a session its other
+folders.
+
+- `ctx.projects.folders.relocate({ projectId, folderId, path, requestId? })` gives an attached folder
+  a new path and keeps its id, so the conversations that use the folder follow it. Nothing on disk
+  moves. It is refused when another project already uses the new path or the folder's clone has not
+  finished. Declare `project.folder.relocate` in `commands.dispatch`; the generated types are
+  `ProjectsFoldersRelocateInput` and `ProjectsFoldersRelocateOutput`.
+- Three optional input fields. `ThreadsUpdateInput.folderIds` is the folders the conversation hands
+  its agent: it must include the conversation's start folder, every id must still be attached to
+  the project on this machine, it takes effect from the next turn, and leaving it out changes
+  nothing. `ProjectsUpdateInput.defaultFolderId` is the folder new conversations on this machine
+  start in (`null` goes back to the first folder still attached; the folder must be attached, and
+  the project's `workspaceRoot` follows it); `ctx.projects.update` still refuses plugins.
+  `ProjectsFoldersAttachInput.threadId` also hands the new folder to that open conversation from
+  its next turn.
+- `capabilities.projectMultiFolder` in `MachineSettingsConfigGetOutput.environment` is true on a
+  machine that accepts several folders per project, `defaultFolderId` and `project.folder.relocate`;
+  an older machine omits it.
+- Executors. `ExecutorSessionStartInput.additionalDirectories` lists the folders other than `cwd`
+  that the session hands to its agent: absolute paths, without duplicates, in the project's order.
+  The host sends it only to an executor whose card declares the new optional capability
+  `ExecutorCapabilities.acceptsAdditionalDirectories` (also in the card capabilities that
+  `providers.executors.list` returns); the executor declares the folders to its CLI as working
+  directories, readable and writable like `cwd` and under the same approval rules. When the folders
+  change mid-session the host calls `startSession` again with the resume state: an executor that
+  fixes its directories at launch restarts, one that sends them every turn may keep the running
+  process and report the generation it already had. Absent or empty means `cwd` only.
+- Conversation host data is now version 18 (`CONVERSATION_HOST_DATA_VERSION`; a conversation view
+  declares `ycodium.conversation.host-data.v18`). New: `ConversationThreadFolder`
+  (`{ id, name, cwd }`: a folder of the conversation's project on this machine, `cwd` being the
+  directory to search, the isolated worktree when the start folder has one) and the optional
+  `ConversationHostData.useThreadFolders(target)`, which lists them with the start folder first
+  (empty for a draft or a project not loaded yet); `ConversationComposerApi.pathSearch.useComposerPathSearchAcross({ environmentId, cwds, query })`,
+  which runs one `@` query in several directories and returns `ConversationComposerPathSearchAcrossState`
+  (`groups` in the order of `cwds`, plus `isPending`); and `CONVERSATION_COMPOSER_PATH_SEARCH_LIMIT`
+  (80), the longest `@` menu, per directory and after merging.
 
 API 39 lets the work assignee be a project member and gives the person handle the member writes.
 
@@ -590,7 +656,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 39.
+the minimum version is 41.
 
 API 8 changed what the UI gets for a communication record. `ConversationCommunicationRecord`
 (from the conversation host's `useCommunicationRecord`) and `CommunicationViewExchange` carry `bodyState`, and their

package/dist/dataPorts.gen.d.ts

@@ -3290,6 +3290,7 @@ export type ProvidersExecutorsListOutput = {
                 readonly "handlesSkillInvocations"?: boolean | undefined;
                 readonly "discoversRepoSkills"?: boolean | undefined;
                 readonly "confirmsToolTermination"?: boolean | undefined;
+                readonly "acceptsAdditionalDirectories"?: boolean | undefined;
                 readonly "inlineImages"?: {
                     readonly "maxBytes": number;
                     readonly "maxEdgePixels"?: number | undefined;