@yaklabs-ai/plugin-protocol 0.41.0 → 0.42.0

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.0"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

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

package/dist/index.d.ts

@@ -2515,6 +2515,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 +2813,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 +2830,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 +2901,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 +2936,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 +3373,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 +4255,12 @@ 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.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.41.0";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.42.0";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4580,6 +4600,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>;
@@ -5352,6 +5378,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 +5872,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 +5907,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 +6776,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 +7029,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 +7064,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";
@@ -11362,6 +11399,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";
@@ -12697,6 +12735,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";
@@ -14333,6 +14372,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 +14410,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 +14445,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.0";
+var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
   "kay.app",
@@ -3631,7 +3614,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 +3943,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 +5105,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)) {

package/package.json

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