@yaklabs-ai/plugin-sdk 0.13.6 → 0.13.7

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.6"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.7"
   }
 }
 ```
@@ -62,7 +62,7 @@ Every tool the entrypoint registers is declared in the manifest too:
   "description": "Greets people by name.",
   "version": "0.1.0",
   "namespace": "widgets",
-  "compatibility": { "sdk": "^0.13.6" },
+  "compatibility": { "sdk": "^0.13.7" },
   "targets": {
     "kay": {
       "agent": {
@@ -116,14 +116,23 @@ naming both versions, instead of loading it and finding no `activate`.
 
 ## Entrypoints
 
-| Import                                 | What it gives you                                                            |
-| -------------------------------------- | ---------------------------------------------------------------------------- |
-| `@bonsai/plugin-sdk/kay-agent`         | Tools, URI modules, search providers, auth — the per-session agent surface   |
-| `@bonsai/plugin-sdk/kay-app`           | App-lifetime surface: storage, endpoints, app-scoped URI modules             |
-| `@bonsai/plugin-sdk/kay-agent/testing` | `invokeToolForTest`, `fauxAuthContext` — for your own `node --test` runs     |
-| `@bonsai/plugin-sdk/disclosure`        | The conformance audit Bonsai gates your plugin with — run it before you ship |
-| `@bonsai/plugin-sdk/time`              | `Temporal` (Bonsai's own instance) and the time-zone helpers, from 0.13.6    |
-| `@bonsai/plugin-sdk/transcript`        | The active-branch walk, the turn walk and the run records of a session log   |
+| Import                                  | What it gives you                                                               |
+| --------------------------------------- | ------------------------------------------------------------------------------- |
+| `@bonsai/plugin-sdk/kay-agent`          | Tools, URI modules, search providers, auth — the per-session agent surface      |
+| `@bonsai/plugin-sdk/kay-app`            | App-lifetime surface: storage, endpoints, app-scoped URI modules                |
+| `@bonsai/plugin-sdk/kay-agent/testing`  | `invokeToolForTest`, `fauxAuthContext` — for your own `node --test` runs        |
+| `@bonsai/plugin-sdk/disclosure`         | The conformance audit Bonsai gates your plugin with — run it before you ship    |
+| `@bonsai/plugin-sdk/time`               | `Temporal` (Bonsai's own instance) and the time-zone helpers, from 0.13.6       |
+| `@bonsai/plugin-sdk/transcript`         | The active-branch walk; the turn walk and run records from 0.13.6               |
+| `@bonsai/plugin-sdk/transcript-review`  | The review fold: a session's spans, tool-call attempts and records, from 0.13.7 |
+| `@bonsai/plugin-sdk/agent-conversation` | How a session's agent-to-agent traffic groups into conversations, from 0.13.7   |
+| `@bonsai/plugin-sdk/app-data`           | The app-data size caps, on an entry with no other import, from 0.13.7           |
+| `@bonsai/plugin-sdk/vendored-mcp`       | The kit for a plugin built on a vendor's hosted MCP server, from 0.13.7         |
+
+A plugin that imports a subpath declares at least the version its row names (`^0.13.7` for the
+last four). `vendored-mcp` builds the plugin's URI module (its link cards and help); hosting the
+vendor's MCP server itself is a separate host decision, and Bonsai currently makes it only for
+its own bundled plugins.
 
 `kay-agent/host` is intentionally not published; it is Bonsai's own loading
 machinery, not an authoring API.

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.13.6",
+  "version": "0.13.7",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/agent-conversation.d.ts

@@ -0,0 +1,93 @@
+/** The admitted inbox receipt, not a target guessed from tool arguments or prose. */
+export declare function admittedSendSessionId(details: unknown): string | undefined;
+
+/**
+ * The admitted-spawn stamp, or `undefined` when nothing was started.
+ *
+ * Two generations of stamp exist in durable transcripts and both must parse
+ * forever: version 2 (the messaging contract) writes
+ * `{ version: 2, sessionId, displayName, backgroundTaskId }` and exists only
+ * for admitted spawns (rejections are tool errors and stamp nothing);
+ * version 1 wrote `{ version: 1, accepted, childSessionId, label, … }`, where
+ * `accepted: false` carries no child session.
+ */
+export declare function admittedSpawnSessionId(details: unknown): string | undefined;
+
+export declare type AgentConversationBoundaryReason = "assistant_text" | "user" | "spawn" | "custom" | "surface" | "other";
+
+export declare interface AgentConversationPeerGroup<TRef = unknown> {
+    readonly peerId: string;
+    readonly firstItemId: string;
+    readonly items: readonly AgentConversationSourceConversation<TRef>[];
+}
+
+export declare type AgentConversationResultStatus = RunSettlementOutcome;
+
+export declare interface AgentConversationRun<TRef = unknown> {
+    /** The first conversation item's id: stable while the run grows. */
+    readonly id: string;
+    /** Every conversation item, in canonical source order. */
+    readonly items: readonly AgentConversationSourceConversation<TRef>[];
+    /** Peers in first-appearance order. */
+    readonly peers: readonly AgentConversationPeerGroup<TRef>[];
+    /** Work strictly between two of this run's conversation items. */
+    readonly work: readonly AgentConversationRunWork[];
+}
+
+/** Work a run can own: a tool attempt or a folded narration, in source order. */
+declare type AgentConversationRunWork = AgentConversationSourceActivity | AgentConversationSourceNote;
+
+declare interface AgentConversationSourceActivity {
+    readonly kind: "activity";
+    readonly attemptId: string;
+    readonly rowKey: string;
+}
+
+declare interface AgentConversationSourceBoundary {
+    readonly kind: "boundary";
+    readonly id: string;
+    readonly reason: AgentConversationBoundaryReason;
+}
+
+export declare interface AgentConversationSourceConversation<TRef = unknown> {
+    readonly kind: "conversation";
+    /** Source identity: a tool attempt id (outbound) or message item id. */
+    readonly id: string;
+    readonly peerId: string;
+    readonly direction: "inbound" | "outbound" | "result";
+    readonly status?: AgentConversationResultStatus;
+    readonly rowKey: string;
+    readonly ref: TRef;
+}
+
+export declare type AgentConversationSourceItem<TRef = unknown> = AgentConversationSourceConversation<TRef> | AgentConversationRunWork | AgentConversationSourceBoundary;
+
+/** Narration that paints only inside a folded "Did work" rail. */
+declare interface AgentConversationSourceNote {
+    readonly kind: "note";
+    readonly id: string;
+    readonly rowKey: string;
+}
+
+export declare function groupAgentConversationStream<TRef>(stream: readonly AgentConversationSourceItem<TRef>[]): readonly AgentConversationRun<TRef>[];
+
+export declare function immediateFollowingAgentConversationWave<TAttempt extends {
+    readonly id: string;
+}>(run: AgentConversationRun<unknown>, waves: readonly (readonly TAttempt[])[], stream: readonly AgentConversationSourceItem[], order: ReadonlyMap<string, number>, sources: ReadonlyMap<string, {
+    readonly rowKey: string;
+}>, claimedWaveAttemptIds: ReadonlySet<string>): readonly TAttempt[] | undefined;
+
+/** Whether a run changes today's rendering: a pair (2+ items with one peer) or 2+ peers. */
+export declare function isFoldedAgentConversationRun(run: AgentConversationRun<unknown>): boolean;
+
+/** The received metadata that both work ownership and the conversation renderer recognize. */
+export declare function receivedConversation(customType: string | undefined, details: unknown): {
+    readonly peerId: string;
+    readonly direction: "inbound" | "result";
+    readonly status?: AgentConversationResultStatus;
+} | undefined;
+
+/** Terminal daemon-run outcomes shared by stored records and conversation results. */
+declare type RunSettlementOutcome = "completed" | "interrupted" | "cancelled" | "failed";
+
+export { }

package/dist/agent-conversation.js

@@ -0,0 +1,174 @@
+// packages/plugin-protocol/dist/agent-conversation.js
+function workId(work) {
+  return work.kind === "activity" ? work.attemptId : work.id;
+}
+function freezeRun(run) {
+  const peers = /* @__PURE__ */ new Map();
+  for (const item of run.items) {
+    const items = peers.get(item.peerId);
+    if (items === void 0)
+      peers.set(item.peerId, [item]);
+    else
+      items.push(item);
+  }
+  return {
+    id: run.items[0].id,
+    items: run.items,
+    peers: [...peers].map(([peerId, items]) => ({
+      peerId,
+      firstItemId: items[0].id,
+      items
+    })),
+    work: run.work
+  };
+}
+function groupAgentConversationStream(stream) {
+  const runs = [];
+  const claimed = /* @__PURE__ */ new Set();
+  let active;
+  let queued = [];
+  const close = () => {
+    if (active !== void 0)
+      runs.push(freezeRun(active));
+    active = void 0;
+    queued = [];
+  };
+  for (const item of stream) {
+    if (item.kind === "boundary") {
+      close();
+      continue;
+    }
+    if (item.kind === "activity" || item.kind === "note") {
+      if (active !== void 0)
+        queued.push(item);
+      continue;
+    }
+    if (active === void 0) {
+      active = { items: [item], work: [] };
+      continue;
+    }
+    for (const work of queued) {
+      if (claimed.has(workId(work)))
+        continue;
+      claimed.add(workId(work));
+      active.work.push(work);
+    }
+    queued = [];
+    active.items.push(item);
+  }
+  close();
+  return runs;
+}
+function immediateFollowingAgentConversationWave(run, waves, stream, order, sources, claimedWaveAttemptIds) {
+  if (run.work.length === 0)
+    return void 0;
+  const runIds = new Set(run.items.map((item) => item.id));
+  const end = Math.max(...run.items.map((item) => order.get(item.id) ?? -Infinity));
+  if (!Number.isFinite(end))
+    return void 0;
+  let candidate;
+  let candidateStart = Infinity;
+  for (const wave of waves) {
+    const followingAttempts = wave.filter((attempt) => {
+      const position = order.get(attempt.id);
+      return position !== void 0 && position > end && !claimedWaveAttemptIds.has(attempt.id);
+    });
+    if (followingAttempts.length === 0)
+      continue;
+    if (followingAttempts.some((attempt) => sources.get(attempt.id)?.rowKey !== run.items.at(-1)?.rowKey))
+      continue;
+    const start = Math.min(...followingAttempts.map((attempt) => order.get(attempt.id) ?? Infinity));
+    if (start < candidateStart) {
+      candidate = followingAttempts;
+      candidateStart = start;
+    }
+  }
+  if (candidate === void 0)
+    return void 0;
+  const waveIds = new Set(candidate.map((attempt) => attempt.id));
+  for (const item of stream) {
+    const position = order.get(item.kind === "activity" ? item.attemptId : item.id);
+    if (position === void 0 || position <= end || position >= candidateStart)
+      continue;
+    if (item.kind === "conversation" && !runIds.has(item.id))
+      return void 0;
+    if (item.kind !== "activity" && item.kind !== "conversation")
+      return void 0;
+    if (item.kind === "activity" && !waveIds.has(item.attemptId))
+      return void 0;
+  }
+  return candidate;
+}
+function isFoldedAgentConversationRun(run) {
+  return run.peers.length >= 2 || run.peers.some((peer) => peer.items.length >= 2);
+}
+function admittedSpawnSessionId(details) {
+  if (typeof details !== "object" || details === null)
+    return void 0;
+  const record = details;
+  const sessionId = typeof record["sessionId"] === "string" ? record["sessionId"] : record["accepted"] === true && typeof record["childSessionId"] === "string" ? record["childSessionId"] : void 0;
+  return sessionId === void 0 || sessionId.trim() === "" ? void 0 : sessionId.trim();
+}
+function admittedSendSessionId(details) {
+  if (typeof details !== "object" || details === null)
+    return void 0;
+  const record = details;
+  const sessionId = typeof record["sessionId"] === "string" ? record["sessionId"].trim() : "";
+  return sessionId && typeof record["rowId"] === "string" && record["rowId"] !== "" && typeof record["backgroundTaskId"] === "string" ? sessionId : void 0;
+}
+function receivedConversation(customType, details) {
+  if (typeof details !== "object" || details === null)
+    return void 0;
+  const record = details;
+  if (customType === "collaboration_message") {
+    const provenance2 = record["provenance"];
+    if (typeof record["senderSessionId"] !== "string" || record["kind"] !== "message" && record["kind"] !== "progress" || typeof provenance2 !== "object" || provenance2 === null)
+      return void 0;
+    const source = provenance2;
+    if (source["source"] !== "subagent" || typeof source["sourceId"] !== "string")
+      return void 0;
+    return { peerId: record["senderSessionId"], direction: "inbound" };
+  }
+  if (customType !== "subagent_result")
+    return void 0;
+  const provenance = subagentProvenanceOf(record);
+  const status = record["status"];
+  if (provenance === void 0 || provenance.sourceId === "" || status !== "completed" && status !== "failed" && status !== "cancelled" && status !== "interrupted")
+    return void 0;
+  return { peerId: provenance.sourceId, direction: "result", status };
+}
+function subagentProvenanceOf(record) {
+  const provenance = record["provenance"];
+  if (typeof provenance === "object" && provenance !== null) {
+    const p = provenance;
+    if (p["source"] === "subagent" && typeof p["sourceId"] === "string") {
+      const label = p["label"];
+      return {
+        source: "subagent",
+        sourceId: p["sourceId"],
+        ...typeof label === "string" ? { label } : {}
+      };
+    }
+  }
+  const attribution = record["attribution"];
+  if (typeof attribution === "object" && attribution !== null) {
+    const a = attribution;
+    if (a["kind"] === "subagent" && typeof a["childSessionId"] === "string") {
+      const label = a["label"];
+      return {
+        source: "subagent",
+        sourceId: a["childSessionId"],
+        ...typeof label === "string" ? { label } : {}
+      };
+    }
+  }
+  return void 0;
+}
+export {
+  admittedSendSessionId,
+  admittedSpawnSessionId,
+  groupAgentConversationStream,
+  immediateFollowingAgentConversationWave,
+  isFoldedAgentConversationRun,
+  receivedConversation
+};

package/dist/app-data.d.ts

@@ -0,0 +1,7 @@
+/** Maximum UTF-8 JSON size of one plugin app-data live change. */
+export declare const KAY_APP_DATA_CHANGE_MAX_BYTES: number;
+
+/** Maximum UTF-8 JSON size of one plugin app-data snapshot. */
+export declare const KAY_APP_DATA_SNAPSHOT_MAX_BYTES: number;
+
+export { }

package/dist/app-data.js

@@ -0,0 +1,9 @@
+// packages/plugin-protocol/dist/app-data.js
+var KAY_APP_DATA_SNAPSHOT_MAX_BYTES = 16 * 1024 * 1024;
+var KAY_APP_DATA_CHANGE_MAX_BYTES = 256 * 1024;
+var KAY_APP_DATA_READ_REQUEST_MAX_BYTES = 64 * 1024;
+var KAY_APP_DATA_READ_RESULT_MAX_BYTES = 16 * 1024 * 1024;
+export {
+  KAY_APP_DATA_CHANGE_MAX_BYTES,
+  KAY_APP_DATA_SNAPSHOT_MAX_BYTES
+};

package/dist/kay-agent.d.ts

@@ -4919,6 +4919,30 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
         envelope: z.ZodObject<{
             binary: z.ZodString;
         }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"plugin">;
+        slug: z.ZodLiteral<"mcp.host-server">;
+        envelope: z.ZodObject<{
+            name: z.ZodString;
+            url: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"plugin">;
+        slug: z.ZodLiteral<"prompt.resident">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"plugin">;
+        slug: z.ZodLiteral<"skills.declared-source">;
+        envelope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            channel: z.ZodLiteral<"git-clone">;
+            locator: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+            subdir: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            channel: z.ZodLiteral<"installer">;
+            command: z.ZodString;
+            args: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>], "channel">;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodEnum<{
             "kay.agent": "kay.agent";