@yaklabs-ai/plugin-protocol 0.13.5 → 0.13.7

package/README.md

@@ -11,7 +11,7 @@ flow.
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.13.5"
+    "@bonsai/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.13.7"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

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

package/dist/index.d.ts

@@ -1705,9 +1705,44 @@ export declare interface DeclaredKayPluginCompatibility {
     readonly sdk?: string | undefined;
 }
 
+/**
+ * Where a plugin-declared skill source's bytes come from, as the daemon resolved it: the manifest
+ * declaration (`PluginSkillSourceDeclaration`) less its local id and display name, which grant
+ * nothing. The git channel carries the canonical locator plus the ref and subdir, because the same
+ * repository at another ref or folder is a different source the user never approved; the installer
+ * channel carries the command and its argv exactly, never joined into one string.
+ */
+export declare const DeclaredSkillSourceEnvelope: 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">;
+
+export declare type DeclaredSkillSourceEnvelope = z.infer<typeof DeclaredSkillSourceEnvelope>;
+
 /** Drop repeats under {@link sameClaim}, preserving first-seen order (a sort settles the rest). */
 export declare function dedupeClaims(claims: readonly PluginCapabilityClaimV1[]): PluginCapabilityClaimV1[];
 
+/**
+ * The one `toolName` a directory plugin may declare for the tool `localId`: every `.` in
+ * `namespace` becomes `_`, then one more `_` joins `localId`. The directory verdict drops a tool
+ * that declares anything else. Bundled plugins are not held to it.
+ *
+ * Injective over every schema-valid pair, so two directory plugins can only derive the same tool
+ * name by sharing both namespace and localId. Neither input can contain `_` (`PLUGIN_ID_PATTERN`
+ * and `LOCAL_CONTRIBUTION_ID_PATTERN` exclude it), so every `_` in the output was inserted here,
+ * and splitting on `_` recovers the namespace's segments and then `localId` (which has no `.`).
+ *
+ * A `-` is deliberately left alone: mapping it to `_` too would send `("a", "b-c")` and
+ * `("a-b", "c")` to the same `a_b_c`. The tool-name alphabet admits `-` for that reason (#4341).
+ */
+export declare function deriveDirectoryPluginToolName(namespace: string, localId: string): string;
+
 export declare const DeviceDelegationContribution: z.ZodObject<{
     localId: z.ZodString;
     device: z.ZodEnum<{
@@ -1933,6 +1968,12 @@ export declare type InteractionDriverContribution = z.infer<typeof InteractionDr
 /** Whether the report permits the plugin to load. */
 export declare function isCompatible(report: KayPluginCompatibilityReport): boolean;
 
+/**
+ * Whether a refusal `code` came from the compatibility check: the plugin was written for another
+ * SDK or protocol, as opposed to being malformed.
+ */
+export declare function isKayPluginCompatibilityRefusal(code: string): code is KayPluginCompatibilityRefusalCode;
+
 /**
  * Discriminates a grant's auth-scheme reference between a local id and an
  * already-qualified global id. Local contribution ids cannot contain dots.
@@ -2015,8 +2056,10 @@ export declare const KAY_APP_DATA_SNAPSHOT_MAX_BYTES: number;
  */
 export declare const KAY_EVENT_PUBLISHER_ID: "kay";
 
+declare const KAY_PLUGIN_COMPATIBILITY_REFUSAL_CODES: readonly ["unsupported-protocol", "sdk-range-unsatisfied", "sdk-range-unsupported", "host-sdk-version-invalid"];
+
 /** Released SDK contracts still implemented by the host, alongside its current SDK. */
-export declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly ["0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.9.0", "0.9.1", "0.10.0", "0.11.0", "0.11.1", "0.12.0", "0.12.1", "0.12.2", "0.12.3", "0.12.4", "0.12.5", "0.13.0", "0.13.1", "0.13.2", "0.13.3", "0.13.4"];
+export declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly ["0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.9.0", "0.9.1", "0.10.0", "0.11.0", "0.11.1", "0.12.0", "0.12.1", "0.12.2", "0.12.3", "0.12.4", "0.12.5", "0.13.0", "0.13.1", "0.13.2", "0.13.3", "0.13.4", "0.13.5", "0.13.6"];
 
 /** The file whose presence makes a directory a plugin. A directory without one is not a plugin. */
 export declare const KAY_PLUGIN_MANIFEST_FILENAME = "kay-plugin.json";
@@ -2281,11 +2324,36 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.13.5 loads a `kay.agent` or `kay.app` entrypoint's default export when the manifest's
  * `entrypoint.export` names none, the way Pi writes extensions; a module with no default export
- * still loads from a named `activate`. No API changes. A plugin whose entrypoint has only a default
+ * still loads from a named `activate`. A plugin whose entrypoint has only a default
  * export declares `^0.13.5`, so an older host, which reads only `activate`, refuses it at load
- * instead of failing to find the export.
+ * instead of failing to find the export. It also renamed three published types with no aliases,
+ * a break in the authoring types that shipped in this patch: `kay-app`'s `SessionTreeEntry`
+ * became `TranscriptEntry`, and `transcript`'s `TranscriptEntry` and `TranscriptSourceEntry`
+ * became `TranscriptEntryLike` and `TranscriptSourceEntryLike`.
+ *
+ * 0.13.6 publishes the pure contracts Bonsai's own plugins took from its internal libraries, so a
+ * plugin needs less beside the SDK. A new `@bonsai/plugin-sdk/time` carries `Temporal` (the
+ * host's own instance, like `z`), `canonicalZone`, `isValidZone` and `sameZone`, and the time
+ * door's types. `kay-app` adds
+ * the `JsonSchema` and `JsonValue` schemas, `PluginAgentDefinitionPermissionRule`,
+ * `KAY_APP_DATA_SNAPSHOT_MAX_BYTES`, and the URI types `UriHelp`, `RawResource`, `UriPayload`,
+ * `UriListParams`, `UriListResult`, `UriSearchParams` and `UriSearchResult`. `kay-agent` adds
+ * `compileUriClaim`, `kay-agent/testing` adds `createTestClock`, and `transcript` adds the turn walk
+ * (`turnSegments`), the run records and the work-block and work-headline helpers. Additive: a
+ * plugin compiled against 0.13.5 never imports them. A plugin that imports one declares `^0.13.6`,
+ * so an older host refuses a directory or repository plugin at load instead of the import failing.
+ *
+ * 0.13.7 adds four subpaths. `@bonsai/plugin-sdk/vendored-mcp` re-exports
+ * `@bonsai/vendored-mcp-integration` (`createVendoredMcpUriModule` and its descriptor types; not
+ * the MCP read-port types). `transcript-review` and `agent-conversation` re-export the session
+ * folds Bonsai's own Sessions and Hindsight plugins share. `app-data` carries the app-data size
+ * caps on an entry with no other import, for code a `kay.ui` page also loads. The protocol it
+ * ships also carries three new capability-claim slugs (`mcp.host-server`, `prompt.resident`,
+ * `skills.declared-source`). Additive: a plugin compiled against 0.13.6 never imports the new
+ * subpaths, and its manifest parses unchanged. A plugin that imports one declares `^0.13.7`, so
+ * an older host refuses a directory or repository plugin at load instead of the import failing.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.13.5";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.13.7";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2600,7 +2668,7 @@ export declare interface KayPluginCompatibilityNote<TCode extends string> {
     readonly message: string;
 }
 
-export declare type KayPluginCompatibilityRefusalCode = "unsupported-protocol" | "sdk-range-unsatisfied" | "sdk-range-unsupported" | "host-sdk-version-invalid";
+export declare type KayPluginCompatibilityRefusalCode = (typeof KAY_PLUGIN_COMPATIBILITY_REFUSAL_CODES)[number];
 
 /**
  * What the check found. `refusal` absent means the plugin may load; advisories
@@ -2626,6 +2694,11 @@ export declare type KayPluginDirectoryVerdict = {
 } | {
     readonly outcome: "refused";
     readonly refusal: PluginLoadDiagnostic;
+    /**
+     * The id the manifest declares, as written, when the refusal came after the manifest was
+     * read; it is not validated, so it may not be a well-formed plugin id.
+     */
+    readonly pluginId?: string;
     /** Notes raised before the refusal; the author still meets them once it is fixed. */
     readonly warnings: readonly PluginLoadDiagnostic[];
 } | {
@@ -3878,7 +3951,7 @@ export declare function parseResolvedPluginContractV1(value: unknown): ResolvedP
 export declare function parseSemver(value: string): ParsedSemver | undefined;
 
 /** Every capability slug {@link PluginCapabilityClaimV1} can express, for exhaustive table checks. */
-export declare const PLUGIN_CAPABILITY_SLUGS: readonly ["sessions.run", "network.connect", "web-session.request", "web-session.download", "process.spawn", "corpus.read", "signals.read", "skills.read", "tools.describe", "workspace.command", "sessions.create", "sessions.update", "models.complete", "jev.use", "automations.write", "automations.run", "workflows.define", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "account.assert", "account.update", "agents.permissions", "tool-interception.register", "interaction.surface", "config.declare-section", "auth.own-service", "auth.shared-identity", "cli.bind", "whiteboard.discover", "whiteboard.read", "whiteboard.create", "whiteboard.update", "whiteboard.remove"];
+export declare const PLUGIN_CAPABILITY_SLUGS: readonly ["sessions.run", "network.connect", "web-session.request", "web-session.download", "process.spawn", "corpus.read", "signals.read", "skills.read", "tools.describe", "workspace.command", "sessions.create", "sessions.update", "models.complete", "jev.use", "automations.write", "automations.run", "workflows.define", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "account.assert", "account.update", "agents.permissions", "tool-interception.register", "interaction.surface", "config.declare-section", "auth.own-service", "auth.shared-identity", "cli.bind", "mcp.host-server", "prompt.resident", "skills.declared-source", "whiteboard.discover", "whiteboard.read", "whiteboard.create", "whiteboard.update", "whiteboard.remove"];
 
 /** Diagnostic messages carry plugin-controlled text (parse errors, module errors); bound it so a
  *  hostile or accidental multi-megabyte error can never blow up a log line or a render surface. */
@@ -4255,17 +4328,20 @@ export declare type PluginAuthService = z.infer<typeof PluginAuthService>;
  * `target` names that scope, and carries ONE value beyond the three plugin targets
  * (`PluginTargetName`): `"plugin"`, for a claim held by the plugin as a whole rather than by one
  * of its targets. Composition decides those — owning a shared auth service, consuming another
- * plugin's identity, binding a CLI credential, declaring a config section — before any target
- * code is loaded, so there is no target to charge them to. They are still exactly claims: one
+ * plugin's identity, binding a CLI credential, declaring a config section, hosting an MCP server,
+ * a resident prompt section, a plugin-declared skill source — before any target code is loaded, so
+ * there is no target to charge them to. They are still exactly claims: one
  * exact envelope, one grant row, one consent.
  *
  * `process.spawn` additionally carries `argvClass`: the declared CLASS of argument vector the
  * plugin will spawn with. It is an opaque exact string here — this module never interprets it —
  * and the broker packet that consumes it owns what a class permits.
  *
- * `agents.permissions` is the one variant whose envelope is not flat: it carries the permission
+ * Two variants carry an envelope that is not flat. `agents.permissions` carries the permission
  * rules themselves, in declaration order, because a human approving it must read the rules they
- * are approving. Its equality is still exact — see {@link sameClaim}.
+ * are approving. `skills.declared-source` carries one of two source shapes
+ * ({@link DeclaredSkillSourceEnvelope}), because a git source and an installer differ in what
+ * pins them. Equality for both is still exact — see {@link sameClaim}.
  */
 export declare const PluginCapabilityClaimV1: z.ZodDiscriminatedUnion<[z.ZodObject<{
     target: z.ZodLiteral<"kay.app">;
@@ -4451,6 +4527,30 @@ export declare const PluginCapabilityClaimV1: z.ZodDiscriminatedUnion<[z.ZodObje
     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";
@@ -4663,6 +4763,30 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
         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";
@@ -4870,6 +4994,30 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
             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";
@@ -5140,6 +5288,30 @@ export 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";