@yaklabs-ai/plugin-protocol 0.42.0 → 0.42.1

package/README.md

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

package/THIRD-PARTY-INVENTORY.json

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

package/dist/index.d.ts

@@ -48,6 +48,12 @@ export declare type AgentRuntimeSessionCreatorKind = (typeof AGENT_RUNTIME_SESSI
 
 export declare const AgentToolContribution: z.ZodObject<{
     parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+    executionMode: z.ZodOptional<z.ZodEnum<{
+        sequential: "sequential";
+        parallel: "parallel";
+    }>>;
+    promptSnippet: z.ZodOptional<z.ZodString>;
+    promptGuidelines: z.ZodOptional<z.ZodArray<z.ZodString>>;
     authService: z.ZodOptional<z.ZodString>;
     authScheme: z.ZodOptional<z.ZodString>;
     permission: z.ZodOptional<z.ZodObject<{
@@ -58,6 +64,8 @@ export declare const AgentToolContribution: z.ZodObject<{
             execute: "execute";
         }>;
         ruleKey: z.ZodOptional<z.ZodString>;
+        scheme: z.ZodOptional<z.ZodString>;
+        resourcePrefix: z.ZodOptional<z.ZodString>;
         resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     localId: z.ZodString;
@@ -2041,10 +2049,18 @@ declare const canonicalContributionSchemas: {
             execute: "execute";
         }>;
         ruleKey: z.ZodOptional<z.ZodString>;
+        scheme: z.ZodOptional<z.ZodString>;
+        resourcePrefix: z.ZodOptional<z.ZodString>;
         resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>;
     AgentToolContribution: z.ZodObject<{
         parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+        executionMode: z.ZodOptional<z.ZodEnum<{
+            sequential: "sequential";
+            parallel: "parallel";
+        }>>;
+        promptSnippet: z.ZodOptional<z.ZodString>;
+        promptGuidelines: z.ZodOptional<z.ZodArray<z.ZodString>>;
         authService: z.ZodOptional<z.ZodString>;
         authScheme: z.ZodOptional<z.ZodString>;
         permission: z.ZodOptional<z.ZodObject<{
@@ -2055,6 +2071,8 @@ declare const canonicalContributionSchemas: {
                 execute: "execute";
             }>;
             ruleKey: z.ZodOptional<z.ZodString>;
+            scheme: z.ZodOptional<z.ZodString>;
+            resourcePrefix: z.ZodOptional<z.ZodString>;
             resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
         localId: z.ZodString;
@@ -4259,8 +4277,11 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.42.0 hands background work the shared ResolvedCredential in auth.credential. Workflow
  * accounts carry auth resolution outcomes, and Poller callbacks receive only the credential.
  * Older SDK ranges are refused because their background success shape is no longer served.
+ *
+ * 0.42.1 adds current-session tool lifetimes and invocation-bound artifact reads/new outputs,
+ * plus described-tool execution, guidance and permission resource metadata.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.42.0";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.42.1";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4286,6 +4307,12 @@ export declare const KayAgentTargetManifest: z.ZodObject<{
     contributes: z.ZodOptional<z.ZodObject<{
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+            executionMode: z.ZodOptional<z.ZodEnum<{
+                sequential: "sequential";
+                parallel: "parallel";
+            }>>;
+            promptSnippet: z.ZodOptional<z.ZodString>;
+            promptGuidelines: z.ZodOptional<z.ZodArray<z.ZodString>>;
             authService: z.ZodOptional<z.ZodString>;
             authScheme: z.ZodOptional<z.ZodString>;
             permission: z.ZodOptional<z.ZodObject<{
@@ -4296,6 +4323,8 @@ export declare const KayAgentTargetManifest: z.ZodObject<{
                     execute: "execute";
                 }>;
                 ruleKey: z.ZodOptional<z.ZodString>;
+                scheme: z.ZodOptional<z.ZodString>;
+                resourcePrefix: z.ZodOptional<z.ZodString>;
                 resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>>;
             localId: z.ZodString;
@@ -5067,6 +5096,12 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                 contributes: z.ZodOptional<z.ZodObject<{
                     tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+                        executionMode: z.ZodOptional<z.ZodEnum<{
+                            sequential: "sequential";
+                            parallel: "parallel";
+                        }>>;
+                        promptSnippet: z.ZodOptional<z.ZodString>;
+                        promptGuidelines: z.ZodOptional<z.ZodArray<z.ZodString>>;
                         authService: z.ZodOptional<z.ZodString>;
                         authScheme: z.ZodOptional<z.ZodString>;
                         permission: z.ZodOptional<z.ZodObject<{
@@ -5077,6 +5112,8 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                                 execute: "execute";
                             }>;
                             ruleKey: z.ZodOptional<z.ZodString>;
+                            scheme: z.ZodOptional<z.ZodString>;
+                            resourcePrefix: z.ZodOptional<z.ZodString>;
                             resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
                         }, z.core.$strict>>;
                         localId: z.ZodString;
@@ -7317,7 +7354,7 @@ export declare function parseSemver(value: string): ParsedSemver | undefined;
 export declare function parseWhere(source: string, keyTypes?: WhereKeyTypes): WhereParseResult;
 
 /** 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", "sessions.read", "signals.read", "memory.read", "memory.write", "skills.read", "skills.write", "skills.share", "plugins.set-enabled", "sessions.annotate", "sessions.compact", "soul.write", "tools.describe", "workspace.command", "sessions.create", "sessions.update", "models.complete", "systemOne.use", "automations.write", "automations.run", "workflows.define", "workflows.signals", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "knowledge-source.register", "artifacts.read", "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", "model-selection.register", "system-prompt.register"];
+export declare const PLUGIN_CAPABILITY_SLUGS: readonly ["sessions.run", "network.connect", "web-session.request", "web-session.download", "process.spawn", "sessions.read", "signals.read", "memory.read", "memory.write", "skills.read", "skills.write", "skills.share", "plugins.set-enabled", "sessions.annotate", "sessions.compact", "soul.write", "tools.describe", "workspace.command", "sessions.create", "sessions.update", "models.complete", "systemOne.use", "automations.write", "automations.run", "workflows.define", "workflows.signals", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "knowledge-source.register", "artifacts.read", "session-artifacts.read", "session-artifacts.create", "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", "model-selection.register", "system-prompt.register"];
 
 /** 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. */
@@ -7963,6 +8000,18 @@ export declare const PluginCapabilityClaimInputV1: z.ZodCustom<{
     envelope: {
         source: string;
     };
+} | {
+    target: "kay.agent";
+    slug: "session-artifacts.read";
+    envelope: {
+        kind: "output" | "upload";
+    };
+} | {
+    target: "kay.agent";
+    slug: "session-artifacts.create";
+    envelope: {
+        kind: "output";
+    };
 } | {
     target: "kay.app";
     slug: "artifacts.read";
@@ -8212,6 +8261,18 @@ export declare const PluginCapabilityClaimInputV1: z.ZodCustom<{
     envelope: {
         source: string;
     };
+} | {
+    target: "kay.agent";
+    slug: "session-artifacts.read";
+    envelope: {
+        kind: "output" | "upload";
+    };
+} | {
+    target: "kay.agent";
+    slug: "session-artifacts.create";
+    envelope: {
+        kind: "output";
+    };
 } | {
     target: "kay.app";
     slug: "artifacts.read";
@@ -8457,6 +8518,21 @@ export declare const PluginCapabilityClaimV1: z.ZodDiscriminatedUnion<[z.ZodObje
     envelope: z.ZodObject<{
         source: z.ZodString;
     }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    target: z.ZodLiteral<"kay.agent">;
+    slug: z.ZodLiteral<"session-artifacts.read">;
+    envelope: z.ZodObject<{
+        kind: z.ZodEnum<{
+            output: "output";
+            upload: "upload";
+        }>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    target: z.ZodLiteral<"kay.agent">;
+    slug: z.ZodLiteral<"session-artifacts.create">;
+    envelope: z.ZodObject<{
+        kind: z.ZodLiteral<"output">;
+    }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     target: z.ZodLiteral<"kay.app">;
     slug: z.ZodLiteral<"artifacts.read">;
@@ -8745,6 +8821,21 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
         envelope: z.ZodObject<{
             source: z.ZodString;
         }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.agent">;
+        slug: z.ZodLiteral<"session-artifacts.read">;
+        envelope: z.ZodObject<{
+            kind: z.ZodEnum<{
+                output: "output";
+                upload: "upload";
+            }>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.agent">;
+        slug: z.ZodLiteral<"session-artifacts.create">;
+        envelope: z.ZodObject<{
+            kind: z.ZodLiteral<"output">;
+        }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"artifacts.read">;
@@ -9032,6 +9123,21 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
             envelope: z.ZodObject<{
                 source: z.ZodString;
             }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            target: z.ZodLiteral<"kay.agent">;
+            slug: z.ZodLiteral<"session-artifacts.read">;
+            envelope: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    output: "output";
+                    upload: "upload";
+                }>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            target: z.ZodLiteral<"kay.agent">;
+            slug: z.ZodLiteral<"session-artifacts.create">;
+            envelope: z.ZodObject<{
+                kind: z.ZodLiteral<"output">;
+            }, z.core.$strict>;
         }, z.core.$strict>, z.ZodObject<{
             target: z.ZodLiteral<"kay.app">;
             slug: z.ZodLiteral<"artifacts.read">;
@@ -9353,6 +9459,21 @@ export declare const PluginCapabilityRefusalV1: z.ZodObject<{
         envelope: z.ZodObject<{
             source: z.ZodString;
         }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.agent">;
+        slug: z.ZodLiteral<"session-artifacts.read">;
+        envelope: z.ZodObject<{
+            kind: z.ZodEnum<{
+                output: "output";
+                upload: "upload";
+            }>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.agent">;
+        slug: z.ZodLiteral<"session-artifacts.create">;
+        envelope: z.ZodObject<{
+            kind: z.ZodLiteral<"output">;
+        }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"artifacts.read">;
@@ -10997,6 +11118,12 @@ export declare const ResolvedKayAgentTool: z.ZodObject<{
     displayName: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+    executionMode: z.ZodOptional<z.ZodEnum<{
+        sequential: "sequential";
+        parallel: "parallel";
+    }>>;
+    promptSnippet: z.ZodOptional<z.ZodString>;
+    promptGuidelines: z.ZodOptional<z.ZodArray<z.ZodString>>;
     requiresAuth: z.ZodOptional<z.ZodObject<{
         serviceId: z.ZodString;
         schemeId: z.ZodOptional<z.ZodString>;
@@ -11009,6 +11136,8 @@ export declare const ResolvedKayAgentTool: z.ZodObject<{
             execute: "execute";
         }>;
         ruleKey: z.ZodOptional<z.ZodString>;
+        scheme: z.ZodOptional<z.ZodString>;
+        resourcePrefix: z.ZodOptional<z.ZodString>;
         resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     localId: z.ZodString;
@@ -12434,6 +12563,12 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
         displayName: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+        executionMode: z.ZodOptional<z.ZodEnum<{
+            sequential: "sequential";
+            parallel: "parallel";
+        }>>;
+        promptSnippet: z.ZodOptional<z.ZodString>;
+        promptGuidelines: z.ZodOptional<z.ZodArray<z.ZodString>>;
         requiresAuth: z.ZodOptional<z.ZodObject<{
             serviceId: z.ZodString;
             schemeId: z.ZodOptional<z.ZodString>;
@@ -12446,6 +12581,8 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
                 execute: "execute";
             }>;
             ruleKey: z.ZodOptional<z.ZodString>;
+            scheme: z.ZodOptional<z.ZodString>;
+            resourcePrefix: z.ZodOptional<z.ZodString>;
             resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
         localId: z.ZodString;
@@ -14282,6 +14419,8 @@ export declare const ToolPermission: z.ZodObject<{
         execute: "execute";
     }>;
     ruleKey: z.ZodOptional<z.ZodString>;
+    scheme: z.ZodOptional<z.ZodString>;
+    resourcePrefix: z.ZodOptional<z.ZodString>;
     resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 

package/dist/index.js

@@ -254,7 +254,7 @@ var JsonSchema = z4.record(z4.string(), JsonValue);
 var KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES = 1024 * 1024;
 var KAY_PLUGIN_PROTOCOL_VERSION = "kay.plugin.v1";
 var KAY_PLUGIN_PROTOCOL_PACKAGE_NAME = "@bonsai/plugin-protocol";
-var KAY_PLUGIN_SDK_VERSION = "0.42.0";
+var KAY_PLUGIN_SDK_VERSION = "0.42.1";
 var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
@@ -1750,6 +1750,8 @@ var PLUGIN_CAPABILITY_SLUGS = [
   "app-data.register",
   "knowledge-source.register",
   "artifacts.read",
+  "session-artifacts.read",
+  "session-artifacts.create",
   "account.assert",
   "account.update",
   "agents.permissions",
@@ -2032,6 +2034,16 @@ function createAuthoritySchemas(canonical) {
       /** The declared `contributes.dataSources` localId. */
       envelope: z10.strictObject({ source: NonEmptyString3 })
     }),
+    z10.strictObject({
+      target: z10.literal("kay.agent"),
+      slug: z10.literal("session-artifacts.read"),
+      envelope: z10.strictObject({ kind: z10.enum(["upload", "output"]) })
+    }),
+    z10.strictObject({
+      target: z10.literal("kay.agent"),
+      slug: z10.literal("session-artifacts.create"),
+      envelope: z10.strictObject({ kind: z10.literal("output") })
+    }),
     z10.strictObject({
       target: z10.literal("kay.app"),
       slug: z10.literal("artifacts.read"),
@@ -2261,8 +2273,10 @@ function sameClaim(a, b) {
       return b.slug === "interaction.surface" && a.envelope.surface === b.envelope.surface;
     case "dynamic-context.register":
       return b.slug === "dynamic-context.register" && a.envelope.contributor === b.envelope.contributor;
+    case "session-artifacts.read":
+    case "session-artifacts.create":
     case "artifacts.read":
-      return b.slug === "artifacts.read" && a.envelope.kind === b.envelope.kind;
+      return b.slug === a.slug && a.envelope.kind === b.envelope.kind;
     case "knowledge-source.register":
       return b.slug === "knowledge-source.register" && a.envelope.source === b.envelope.source;
     case "app-data.register":
@@ -2352,8 +2366,10 @@ function envelopePairs(a, b) {
       return b.slug === "interaction.surface" ? [[a.envelope.surface, b.envelope.surface]] : [];
     case "dynamic-context.register":
       return b.slug === "dynamic-context.register" ? [[a.envelope.contributor, b.envelope.contributor]] : [];
+    case "session-artifacts.read":
+    case "session-artifacts.create":
     case "artifacts.read":
-      return b.slug === "artifacts.read" ? [[a.envelope.kind, b.envelope.kind]] : [];
+      return b.slug === a.slug ? [[a.envelope.kind, b.envelope.kind]] : [];
     case "knowledge-source.register":
       return b.slug === "knowledge-source.register" ? [[a.envelope.source, b.envelope.source]] : [];
     case "app-data.register":
@@ -3227,12 +3243,17 @@ function createContributionsSchemas(canonical) {
   const ToolPermission2 = z12.strictObject({
     kind: z12.enum(["read", "mutate", "destructive", "execute"]),
     ruleKey: NonEmptyString3.optional(),
+    scheme: NonEmptyString3.optional(),
+    resourcePrefix: z12.string().max(256).optional(),
     // Arguments whose string values name the resources a call touches.
     resourceArgs: z12.array(NonEmptyString3).min(1).optional()
   });
   const AgentToolContribution2 = z12.strictObject({
     ...ToolContribution2.shape,
     parameters: JsonSchema.optional(),
+    executionMode: z12.enum(["sequential", "parallel"]).optional(),
+    promptSnippet: NonEmptyString3.optional(),
+    promptGuidelines: z12.array(NonEmptyString3).optional(),
     // A local ref names an auth service declared in this manifest; a dotted ref names another
     // plugin's service, as `UriModuleContribution.authService` does.
     authService: AuthServiceReference2.optional(),
@@ -5804,6 +5825,9 @@ function createResolvedContractSchemas(canonical) {
     displayName: NonEmptyString3.optional(),
     description: NonEmptyString3.optional(),
     parameters: JsonSchema.optional(),
+    executionMode: z14.enum(["sequential", "parallel"]).optional(),
+    promptSnippet: NonEmptyString3.optional(),
+    promptGuidelines: z14.array(NonEmptyString3).optional(),
     requiresAuth: z14.strictObject({
       serviceId: GlobalContributionId2,
       schemeId: GlobalContributionId2.optional()
@@ -6456,6 +6480,9 @@ function resolveKayPluginContractV1(manifest) {
     ...tool.displayName === void 0 ? {} : { displayName: tool.displayName },
     ...tool.description === void 0 ? {} : { description: tool.description },
     ...tool.parameters === void 0 ? {} : { parameters: tool.parameters },
+    ...tool.executionMode === void 0 ? {} : { executionMode: tool.executionMode },
+    ...tool.promptSnippet === void 0 ? {} : { promptSnippet: tool.promptSnippet },
+    ...tool.promptGuidelines === void 0 ? {} : { promptGuidelines: tool.promptGuidelines },
     ...tool.authService === void 0 ? {} : {
       requiresAuth: {
         serviceId: isQualifiedAuthServiceRef(tool.authService) ? tool.authService : resolveGlobalContributionId(namespace, tool.authService),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-protocol",
-  "version": "0.42.0",
+  "version": "0.42.1",
   "description": "The Kay plugin manifest schema (`kay.plugin.v1`) — parse and validate a kay-plugin.json.",
   "author": "YakLabs",
   "type": "module",