@yaklabs-ai/plugin-protocol 0.41.0 → 0.42.1

package/README.md

@@ -11,7 +11,7 @@ flow.
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.41.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.41.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;
@@ -2515,6 +2533,12 @@ declare const canonicalContributionSchemas: {
         displayName: z.ZodOptional<z.ZodString>;
         requestSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
         responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+        auth: z.ZodOptional<z.ZodObject<{
+            service: z.ZodString;
+            schemes: z.ZodArray<z.ZodString>;
+            purpose: z.ZodString;
+        }, z.core.$strict>>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     WorkflowContribution: z.ZodObject<{
         localId: z.ZodString;
@@ -2807,6 +2831,7 @@ declare const canonicalContributionSchemas: {
         "artifacts.read": "artifacts.read";
         "artifacts.preview": "artifacts.preview";
         "markdown.document-view": "markdown.document-view";
+        "references.open": "references.open";
         "billing.read": "billing.read";
         "automations.read": "automations.read";
         "automations.run": "automations.run";
@@ -2823,6 +2848,7 @@ declare const canonicalContributionSchemas: {
             "artifacts.read": "artifacts.read";
             "artifacts.preview": "artifacts.preview";
             "markdown.document-view": "markdown.document-view";
+            "references.open": "references.open";
             "billing.read": "billing.read";
             "automations.read": "automations.read";
             "automations.run": "automations.run";
@@ -2893,6 +2919,7 @@ declare const canonicalContributionSchemas: {
                 "artifacts.read": "artifacts.read";
                 "artifacts.preview": "artifacts.preview";
                 "markdown.document-view": "markdown.document-view";
+                "references.open": "references.open";
                 "billing.read": "billing.read";
                 "automations.read": "automations.read";
                 "automations.run": "automations.run";
@@ -2927,6 +2954,7 @@ declare const canonicalContributionSchemas: {
                 "artifacts.read": "artifacts.read";
                 "artifacts.preview": "artifacts.preview";
                 "markdown.document-view": "markdown.document-view";
+                "references.open": "references.open";
                 "billing.read": "billing.read";
                 "automations.read": "automations.read";
                 "automations.run": "automations.run";
@@ -3363,6 +3391,12 @@ export declare const EndpointContribution: z.ZodObject<{
     displayName: z.ZodOptional<z.ZodString>;
     requestSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
     responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+    auth: z.ZodOptional<z.ZodObject<{
+        service: z.ZodString;
+        schemes: z.ZodArray<z.ZodString>;
+        purpose: z.ZodString;
+    }, z.core.$strict>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 
 export declare type EndpointContribution = z.infer<typeof EndpointContribution>;
@@ -4239,8 +4273,15 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.41.0 adds app.mcp.callTool for background calls to a plugin's own manifest-declared MCP
  * servers, using Bonsai's managed connection without a session or working directory (#16172).
+ *
+ * 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.41.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"];
 
@@ -4266,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<{
@@ -4276,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;
@@ -4580,6 +4629,12 @@ export declare const KayAppTargetManifest: z.ZodObject<{
             displayName: z.ZodOptional<z.ZodString>;
             requestSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
             responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+            auth: z.ZodOptional<z.ZodObject<{
+                service: z.ZodString;
+                schemes: z.ZodArray<z.ZodString>;
+                purpose: z.ZodString;
+            }, z.core.$strict>>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>>;
         uriModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
             description: z.ZodExactOptional<z.ZodString>;
@@ -5041,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<{
@@ -5051,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;
@@ -5352,6 +5415,12 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                         displayName: z.ZodOptional<z.ZodString>;
                         requestSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
                         responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+                        auth: z.ZodOptional<z.ZodObject<{
+                            service: z.ZodString;
+                            schemes: z.ZodArray<z.ZodString>;
+                            purpose: z.ZodString;
+                        }, z.core.$strict>>;
+                        timeoutMs: z.ZodOptional<z.ZodNumber>;
                     }, z.core.$strict>>>;
                     uriModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         description: z.ZodExactOptional<z.ZodString>;
@@ -5840,6 +5909,7 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                                 "artifacts.read": "artifacts.read";
                                 "artifacts.preview": "artifacts.preview";
                                 "markdown.document-view": "markdown.document-view";
+                                "references.open": "references.open";
                                 "billing.read": "billing.read";
                                 "automations.read": "automations.read";
                                 "automations.run": "automations.run";
@@ -5874,6 +5944,7 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                                 "artifacts.read": "artifacts.read";
                                 "artifacts.preview": "artifacts.preview";
                                 "markdown.document-view": "markdown.document-view";
+                                "references.open": "references.open";
                                 "billing.read": "billing.read";
                                 "automations.read": "automations.read";
                                 "automations.run": "automations.run";
@@ -6742,6 +6813,7 @@ export declare const KayUiAppHostCapability: z.ZodEnum<{
     "artifacts.read": "artifacts.read";
     "artifacts.preview": "artifacts.preview";
     "markdown.document-view": "markdown.document-view";
+    "references.open": "references.open";
     "billing.read": "billing.read";
     "automations.read": "automations.read";
     "automations.run": "automations.run";
@@ -6994,6 +7066,7 @@ export declare const KayUiTargetManifest: z.ZodObject<{
                     "artifacts.read": "artifacts.read";
                     "artifacts.preview": "artifacts.preview";
                     "markdown.document-view": "markdown.document-view";
+                    "references.open": "references.open";
                     "billing.read": "billing.read";
                     "automations.read": "automations.read";
                     "automations.run": "automations.run";
@@ -7028,6 +7101,7 @@ export declare const KayUiTargetManifest: z.ZodObject<{
                     "artifacts.read": "artifacts.read";
                     "artifacts.preview": "artifacts.preview";
                     "markdown.document-view": "markdown.document-view";
+                    "references.open": "references.open";
                     "billing.read": "billing.read";
                     "automations.read": "automations.read";
                     "automations.run": "automations.run";
@@ -7280,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. */
@@ -7926,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";
@@ -8175,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";
@@ -8420,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">;
@@ -8708,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">;
@@ -8995,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">;
@@ -9316,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">;
@@ -10960,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>;
@@ -10972,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;
@@ -11362,6 +11528,7 @@ export declare const ResolvedKayUiApp: z.ZodObject<{
             "artifacts.read": "artifacts.read";
             "artifacts.preview": "artifacts.preview";
             "markdown.document-view": "markdown.document-view";
+            "references.open": "references.open";
             "billing.read": "billing.read";
             "automations.read": "automations.read";
             "automations.run": "automations.run";
@@ -12396,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>;
@@ -12408,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;
@@ -12697,6 +12872,7 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
                 "artifacts.read": "artifacts.read";
                 "artifacts.preview": "artifacts.preview";
                 "markdown.document-view": "markdown.document-view";
+                "references.open": "references.open";
                 "billing.read": "billing.read";
                 "automations.read": "automations.read";
                 "automations.run": "automations.run";
@@ -14243,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>;
 
@@ -14333,6 +14511,7 @@ export declare const UiAppCapabilities: z.ZodObject<{
         "artifacts.read": "artifacts.read";
         "artifacts.preview": "artifacts.preview";
         "markdown.document-view": "markdown.document-view";
+        "references.open": "references.open";
         "billing.read": "billing.read";
         "automations.read": "automations.read";
         "automations.run": "automations.run";
@@ -14370,6 +14549,7 @@ export declare const UiAppContribution: z.ZodObject<{
             "artifacts.read": "artifacts.read";
             "artifacts.preview": "artifacts.preview";
             "markdown.document-view": "markdown.document-view";
+            "references.open": "references.open";
             "billing.read": "billing.read";
             "automations.read": "automations.read";
             "automations.run": "automations.run";
@@ -14404,6 +14584,7 @@ export declare const UiAppContribution: z.ZodObject<{
             "artifacts.read": "artifacts.read";
             "artifacts.preview": "artifacts.preview";
             "markdown.document-view": "markdown.document-view";
+            "references.open": "references.open";
             "billing.read": "billing.read";
             "automations.read": "automations.read";
             "automations.run": "automations.run";

package/dist/index.js

@@ -254,25 +254,8 @@ 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.41.0";
-var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
-  "0.26.3",
-  "0.27.1",
-  "0.28.0",
-  "0.29.0",
-  "0.30.0",
-  "0.31.0",
-  "0.32.0",
-  "0.33.0",
-  "0.34.0",
-  "0.35.0",
-  "0.36.0",
-  "0.37.0",
-  "0.37.1",
-  "0.38.0",
-  "0.39.0",
-  "0.40.0"
-];
+var KAY_PLUGIN_SDK_VERSION = "0.42.1";
+var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
   "kay.app",
@@ -1767,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",
@@ -2049,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"),
@@ -2278,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":
@@ -2369,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":
@@ -3244,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(),
@@ -3631,7 +3635,13 @@ function createContributionsSchemas(canonical) {
     localId: LocalContributionId2,
     displayName: OptionalDisplayName,
     requestSchema: JsonSchema.optional(),
-    responseSchema: JsonSchema.optional()
+    responseSchema: JsonSchema.optional(),
+    auth: z12.strictObject({
+      service: AuthServiceReference2,
+      schemes: z12.array(AuthSchemeReference2).min(1),
+      purpose: NonEmptyString3
+    }).optional(),
+    timeoutMs: z12.number().int().positive().optional()
   });
   const WorkflowContribution2 = z12.strictObject({
     localId: LocalContributionId2,
@@ -3954,6 +3964,9 @@ function createContributionsSchemas(canonical) {
     // Draws Bonsai's markdown document view in the app's page (`BonsaiMarkdownDocumentView`).
     // It reads and saves nothing: the app supplies the text and keeps the edits.
     "markdown.document-view",
+    // Draws links the host resolves and opens (`BonsaiReferencePill`, `BonsaiReferenceRow`,
+    // `BonsaiReferenceMarkdown`). A person's click on one can open a session or another plugin's page.
+    "references.open",
     // Server-rated organization billing, distinct from local/provider cost.
     "billing.read",
     "automations.read",
@@ -5113,6 +5126,53 @@ function createManifestSchemas(canonical) {
         });
       }
     }
+    for (const [index, endpoint] of (manifest.targets?.kay?.app?.contributes?.endpoints ?? []).entries()) {
+      const { auth } = endpoint;
+      if (auth === void 0)
+        continue;
+      const path = [
+        "targets",
+        "kay",
+        "app",
+        "contributes",
+        "endpoints",
+        index,
+        "auth"
+      ];
+      const qualified = isQualifiedAuthServiceRef(auth.service);
+      const service = manifest.auth?.services?.find((candidate) => candidate.localId === auth.service);
+      if (!qualified && service === void 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: [...path, "service"],
+          message: `endpoint ${endpoint.localId} references unknown auth service ${auth.service}`
+        });
+      }
+      for (const [schemeIndex, scheme] of auth.schemes.entries()) {
+        if (qualified ? namespaceOfQualifiedRef(scheme) !== namespaceOfQualifiedRef(auth.service) : authSchemeIdsByService.get(auth.service)?.has(scheme) !== true) {
+          ctx.addIssue({
+            code: "custom",
+            path: [...path, "schemes", schemeIndex],
+            message: `endpoint ${endpoint.localId} names auth scheme ${scheme}, which is not a scheme of its auth service`
+          });
+        }
+      }
+      if (service !== void 0 && !service.purposes.includes(auth.purpose)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [...path, "purpose"],
+          message: `endpoint ${endpoint.localId} references undeclared auth purpose ${auth.purpose}`
+        });
+      }
+      const granted = manifest.permissions?.byTarget["kay.app"]?.auth?.some((grant) => grant.service === auth.service && grant.operations.includes("resolve") && (grant.purposes === void 0 || grant.purposes.includes(auth.purpose)) && auth.schemes.every((scheme) => grant.schemes === void 0 || grant.schemes.some((grantedScheme) => grantedScheme === scheme || !qualified && `${manifest.namespace ?? manifest.id}.${grantedScheme}` === scheme || !qualified && grantedScheme === `${manifest.namespace ?? manifest.id}.${scheme}`)));
+      if (granted !== true) {
+        ctx.addIssue({
+          code: "custom",
+          path,
+          message: `endpoint ${endpoint.localId} needs a kay.app auth resolve grant admitting its schemes and purpose`
+        });
+      }
+    }
     const syntheticContributionIds = collectSyntheticContributionIds(manifest);
     for (const contribution of collectDeclaredContributionIds(manifest)) {
       if (syntheticContributionIds.has(contribution.localId)) {
@@ -5765,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()
@@ -6417,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.41.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",