@ycodium-ai/plugin-api 0.2.3976 → 0.2.3990

package/README.md

@@ -61,7 +61,7 @@ import { definePlugin } from "@ycodium-ai/plugin-api";
 
 export default definePlugin({
   id: "my-plugin",
-  apiVersion: 75,
+  apiVersion: 77,
   activate: (ctx) => {
     ctx.log.info("hello");
 
@@ -288,6 +288,40 @@ borrower must not kill another borrower's server. Instance disposal must stop ne
 idle timers; an externally configured server is never owned by this operation. Long-lived conversation
 sessions continue using the streaming process interface.
 
+## Executor session channel tests
+
+Each `startSession(input)` receives its own `input.events.emit(event)` channel. Keep that
+channel in the session context; the host assigns event generations. When reusing a process,
+return its original `bindingGeneration` and keep emitting through its original channel.
+
+The `@ycodium-ai/plugin-api/testing` subpath has no runtime dependencies or test framework.
+Wrap your executor with `withTestChannels(instance)`, use its session methods, then call
+`assertGenerationSettled(instance.recorded, generation)`. Assertion failures throw `Error`.
+`recorded.accepted` contains host-stamped events; `recorded.afterClose` records attempted
+delivery to a closed channel. Successful stops close channels, replacements close the old
+channel, and failed starts close their candidate and the previous channel unless a stop already owns it.
+Successful disposal closes all channels.
+
+A generation must emit exactly one `session.exited`, with every `task.*` before it. A clean
+stop, replacement, or successful disposal must settle each open task with a terminal status or `idle`.
+Generations that already exited before the operation are checked as crashes. When a task may outlive
+the process, emit `idle` with `outcomeUnknown: true`: observation for this generation ends,
+while the external task's result remains unknown. Events emitted after channel closure fail
+the check. Crashes must still report an exit; unconfirmed task outcomes need not be invented.
+
+```ts
+import { withTestChannels, assertGenerationSettled } from "@ycodium-ai/plugin-api/testing";
+
+const executor = withTestChannels(await createInstance(config, host));
+try {
+  const session = await executor.startSession({ threadId: "test", runtimeMode: "full-access" });
+  await executor.stopSession("test");
+  assertGenerationSettled(executor.recorded, session.bindingGeneration ?? 1);
+} finally {
+  await executor.dispose();
+}
+```
+
 ## THERE WILL BE COMPATIBILITY-BREAKING CHANGES
 
 The definition's `apiVersion` is checked against a closed window: the host loads every version from
@@ -304,7 +338,11 @@ update against the new types and republish.
 
 <!-- plugin-api-versions:start (generated by scripts/gen-plugin-api-version.ts from packages/plugin-api/version-history.json; edit that file) -->
 
-The current API is **75**. This Ycodium loads plugins declaring 73 through 75.
+The current API is **77**. This Ycodium loads plugins declaring 76 through 77.
+
+API 77 adds ctx.threads.tasks.list to read persisted task activations with filtering and cursor pagination. Summary and last tool name are bounded display text with truncation flags; stored task text is unchanged.
+
+API 76 replaces ExecutorInstance.events with a required events channel on each startSession input. Provider plugins must retain input.events for that session and emit every event there, remove originBindingGeneration from events, and return the original bindingGeneration when reusing a process. The testing subpath provides withTestChannels and assertGenerationSettled.
 
 API 75 adds the optional executor card field `keepsBackgroundServices`, the default for the instance switch that keeps an instance's background program after a session ends (off when absent), and the optional `keepBackgroundServices` on `PluginProviderInstance` and `providers.instances.list` entries, the switch's effective value.
 

package/dist/dataPorts.gen.d.ts

@@ -3448,6 +3448,39 @@ export type ThreadsAgentsGetOutput = {
         readonly "errorWindow"?: Objects_56;
     };
 };
+export type ThreadsTasksListInput = {
+    readonly "threadId": string;
+    readonly "kind"?: "agent" | "background" | "inert";
+    readonly "active"?: boolean;
+    readonly "limit"?: number;
+    readonly "after"?: string;
+};
+export type ThreadsTasksListOutput = {
+    readonly "tasks": ReadonlyArray<{
+        readonly "taskKey": string;
+        readonly "activationKey": string;
+        readonly "provider": string;
+        readonly "taskId": string;
+        readonly "activationSequence": number;
+        readonly "bindingGeneration": number | null;
+        readonly "kind": "agent" | "background" | "inert";
+        readonly "taskType"?: string;
+        readonly "ownerAgentId"?: string;
+        readonly "timelineBypass"?: boolean;
+        readonly "status": "pending" | "running" | "waiting" | "idle" | "completed" | "failed" | "cancelled" | "interrupted";
+        readonly "statusInferred": boolean;
+        readonly "title": string;
+        readonly "originTurnId": string | null;
+        readonly "startedAt": string;
+        readonly "endedAt": string | null;
+        readonly "updatedAt": string;
+        readonly "lastToolName"?: string;
+        readonly "lastToolNameTruncated"?: boolean;
+        readonly "summary"?: string;
+        readonly "summaryTruncated"?: boolean;
+    }>;
+    readonly "nextCursor": string | null;
+};
 export type ThreadsTurnChangesGetInput = {
     readonly "threadId": string;
     readonly "turnId": string;
@@ -8517,6 +8550,9 @@ export interface PluginDataPorts {
             readonly list: (input: ThreadsAgentsListInput) => Promise<ThreadsAgentsListOutput>;
             readonly get: (input: ThreadsAgentsGetInput) => Promise<ThreadsAgentsGetOutput>;
         };
+        readonly tasks: {
+            readonly list: (input: ThreadsTasksListInput) => Promise<ThreadsTasksListOutput>;
+        };
         readonly getTurnChanges?: (input: ThreadsTurnChangesGetInput) => Promise<ThreadsTurnChangesGetOutput>;
         readonly toolCall: {
             readonly get: (input: ThreadsToolCallGetInput) => Promise<ThreadsToolCallGetOutput>;
@@ -9035,6 +9071,10 @@ export interface PluginUiDataReads {
         readonly input: ThreadsAgentsGetInput;
         readonly output: ThreadsAgentsGetOutput;
     };
+    readonly "threads.tasks.list": {
+        readonly input: ThreadsTasksListInput;
+        readonly output: ThreadsTasksListOutput;
+    };
     readonly "threads.turn.changes.get": {
         readonly input: ThreadsTurnChangesGetInput;
         readonly output: ThreadsTurnChangesGetOutput;