@yaklabs-ai/plugin-sdk 0.41.0 → 0.42.0

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.41.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.42.0"
   }
 }
 ```
@@ -62,7 +62,7 @@ Every tool the entrypoint registers is declared in the manifest too:
   "description": "Greets people by name.",
   "version": "0.1.0",
   "namespace": "widgets",
-  "compatibility": { "sdk": "^0.41.0" },
+  "compatibility": { "sdk": "^0.42.0" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -2417,8 +2417,12 @@ 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.41.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

package/dist/kay-agent-testing.d.ts

@@ -2471,8 +2471,12 @@ 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.41.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5796,6 +5800,7 @@ 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";

package/dist/kay-agent.d.ts

@@ -2746,8 +2746,12 @@ 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.41.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

package/dist/kay-app.d.ts

@@ -2722,8 +2722,12 @@ 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.41.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3932,7 +3936,7 @@ export declare interface KayAppAutomationUriChangeCondition {
 
 /** Exact-account credential resolution for a plugin's durable background jobs. */
 export declare interface KayAppBackgroundAuth {
-    resolveCredential(request: KayAppBackgroundCredentialRequest): Promise<KayAppBackgroundCredentialResult>;
+    resolveCredential(request: KayAppBackgroundCredentialRequest): Promise<KayAppCredentialResolution>;
 }
 
 /** A credential request for durable background work bound to one known account. */
@@ -3948,21 +3952,6 @@ export declare interface KayAppBackgroundCredentialRequest {
     readonly jobId: string;
 }
 
-/** The non-secret outcome of a durable background credential lookup. */
-export declare type KayAppBackgroundCredentialResult = {
-    readonly status: "resolved";
-    readonly accessToken: string;
-    readonly accountId: string;
-    readonly scopes: readonly string[];
-} | {
-    readonly status: "missing";
-    readonly reason: string;
-} | {
-    readonly status: "requires-auth";
-    readonly reason: string;
-    readonly requiredScopes?: readonly string[];
-};
-
 /**
  * The `kay.app` system-prompt contract (`app.systemPrompt`): text a plugin adds to every chat's
  * system prompt, rendered by the daemon from a few facts about the chat and reused across chats.
@@ -4114,6 +4103,19 @@ export declare class KayAppCredentialRejectedError extends Error {
     readonly name = "KayAppCredentialRejectedError";
 }
 
+/** A credential for this call, or an account failure with no secret material. Never persist it. */
+export declare type KayAppCredentialResolution = {
+    readonly status: "resolved";
+    readonly credential: ResolvedCredential;
+} | {
+    readonly status: "missing";
+    readonly reason: string;
+} | {
+    readonly status: "requires-auth";
+    readonly reason: string;
+    readonly requiredScopes?: readonly string[];
+};
+
 export declare interface KayAppData {
     /**
      * Register the live definition behind one declared source. At most one registration per source
@@ -4359,18 +4361,17 @@ export declare interface KayAppDynamicContextSearchOptions {
     } | undefined;
 }
 
-/**
- * The app-wide endpoint bus. A plugin registers named handlers a consuming surface can invoke; the
- * host routes invocations (e.g. Bonsai Desktop forwards the renderer's frame-gated call to the daemon,
- * where the endpoint is single-homed). The corpus is NEVER reachable here - only what the plugin
- * explicitly exposes. Both `payload` and the handler's return ride strict JSON on the wire.
- */
+/** Per-invocation authority prepared from the endpoint's manifest declaration. */
+export declare interface KayAppEndpointContext {
+    readonly credentials: readonly KayAppResolvedCredential[];
+    readonly signal: AbortSignal;
+    /** Record only a scheme from this call's credentials after its provider operation succeeds. */
+    reportWorked(schemeId: string): void;
+}
+
+/** The app-wide endpoint bus; payloads and returned values must be JSON. */
 export declare interface KayAppEndpoints {
-    /**
-     * Register a handler under `name`. Names are app-wide (open bus); a duplicate name is rejected by
-     * the host registry.
-     */
-    register(name: string, handler: (payload: unknown) => unknown | Promise<unknown>): void;
+    register(name: string, handler: (payload: unknown, context: KayAppEndpointContext) => unknown | Promise<unknown>): void;
 }
 
 /**
@@ -5407,9 +5408,7 @@ export declare interface KayAppPollerOptions<Cursor extends JsonValue> {
     readonly poll: (input: {
         readonly account: KayAppAccountSummary;
         readonly cursor: Cursor | undefined;
-        readonly credential: Extract<KayAppBackgroundCredentialResult, {
-            readonly status: "resolved";
-        }>;
+        readonly credential: ResolvedCredential;
         readonly runId: string;
     }) => Promise<KayAppPollResult<Cursor>>;
 }
@@ -5564,50 +5563,7 @@ export declare interface KayAppResolveCredentialRequest {
     readonly purpose: string;
 }
 
-/**
- * ---
- * responsibility: The plugin-facing credential surface of the `kay.app` target SDK. A daemon-hosted
- *   plugin lists account metadata or resolves credentials for an owned or consumed auth service
- *   under explicit grants. Credential material is read where the work happens.
- * owns:
- *   - {@link KayAppAuth}, {@link KayAppResolvedCredential}.
- * does_not_own:
- *   - Acquisition, storage, refresh, or revocation. Those are the credential authority's, reached
- *     through the host. A plugin can only ask for material it is granted, for a purpose it declared.
- * ---
- *
- * ## Deny-by-default
- *
- * `KayAppPluginApi.auth` is **present only for plugins the host grants** (`auth.operations`
- * containing `"list"` or `"resolve"` in `permissions.byTarget["kay.app"]`, against an owned or consumed
- * service) and `undefined` otherwise - an ungranted plugin cannot even reference the capability.
- * This mirrors `KayAppPluginApi.sessions`, and it is the rule for every capability behind a grant:
- * never hand a plugin an object whose grant is decorative.
- *
- * ## Secrets do not leave this object
- *
- * A resolved credential is live secret material. Never log it, never echo it into an error message,
- * never put it in an event payload, never return it from an endpoint handler, and never accept it
- * as a URI or config value. Read it, use it in the outbound request, drop it.
- */
-/**
- * Live credential material for one account of one auth scheme.
- *
- * Shaped to match the kernel's `ResolvedCredential` so a plugin that already reads
- * `ctx.auth.credential` in a URI verb reads the same thing here.
- */
-export declare interface KayAppResolvedCredential {
-    /** Bearer for OAuth schemes, the api key for api-key schemes. Host-resolved and refreshed. */
-    readonly accessToken: string;
-    readonly accountId: string;
-    readonly schemeId: string;
-    readonly scopes?: readonly string[];
-    /**
-     * Every value of a multi-field api-key credential, keyed by the scheme's declared field id
-     * (`accessToken` mirrors the primary field). Absent for single-secret schemes.
-     */
-    readonly fields?: Readonly<Record<string, string>>;
-}
+export declare type KayAppResolvedCredential = ResolvedCredential;
 
 /** Hard limits on the routes a `tier` or `model` selection may use. */
 export declare interface KayAppRouteConstraints {
@@ -8145,7 +8101,7 @@ export declare interface KayAppWhiteboardTypes {
  */
 export declare interface KayAppWorkflowAccount {
     readonly account: KayAppAccountSummary;
-    readonly credential: KayAppBackgroundCredentialResult;
+    readonly auth: KayAppCredentialResolution;
 }
 
 /**
@@ -10314,7 +10270,7 @@ export declare function requireWriteContent(payload: UriPayload | Uint8Array | u
  * verb (`ctx.auth.credential`), a tool (`ctx.credential`) or a search provider (`ctx.credential`).
  * Plain data, so it crosses a process boundary with the call; plugin code never asks for one.
  */
-declare interface ResolvedCredential {
+export declare interface ResolvedCredential {
     /** Bearer for OAuth schemes, apiKey for api-key schemes. Host-resolved and refreshed. */
     readonly accessToken: string;
     readonly accountId: string;
@@ -16963,6 +16919,9 @@ declare const WithElementList_0: (input: string, result?: unknown[]) => [unknown
 
 declare function WithElementListMapping(input: [unknown, unknown, unknown] | []): unknown;
 
+/** Try the call's credentials in order; only credential rejection advances to the next. */
+export declare function withEndpointCredential<T>(context: KayAppEndpointContext, use: (credential: KayAppResolvedCredential) => Promise<T>): Promise<T>;
+
 declare function WithMapping(input: [unknown, unknown] | []): unknown;
 
 declare const WithNull: (input: string) => [unknown, string] | [];

package/dist/kay-app.js

@@ -599,11 +599,6 @@ function payload(name, schema, options = {}) {
   };
 }
 
-// packages/plugin-sdk/dist/kay-app/account.js
-function isRetryable(result) {
-  return result.status === "not-ready";
-}
-
 // packages/plugin-sdk/dist/kay-app/auth.js
 var KayAppCredentialRejectedError = class extends Error {
   name = "KayAppCredentialRejectedError";
@@ -626,6 +621,32 @@ async function withCredential(auth, request, use) {
   throw rejection ?? new Error(`No credential is resolvable for '${request.serviceId}'.`);
 }
 
+// packages/plugin-sdk/dist/kay-app/endpoints.js
+async function withEndpointCredential(context, use) {
+  let rejection;
+  for (const credential of context.credentials) {
+    context.signal.throwIfAborted();
+    try {
+      const result = await use(credential);
+      try {
+        context.reportWorked(credential.schemeId);
+      } catch {
+      }
+      return result;
+    } catch (error) {
+      if (!(error instanceof KayAppCredentialRejectedError))
+        throw error;
+      rejection = error;
+    }
+  }
+  throw rejection ?? new Error("No credential is resolvable for this endpoint.");
+}
+
+// packages/plugin-sdk/dist/kay-app/account.js
+function isRetryable(result) {
+  return result.status === "not-ready";
+}
+
 // packages/plugin-sdk/dist/kay-app/automations.js
 var KAY_APP_AUTOMATION_CONDITION_KINDS = [
   "time",
@@ -715,7 +736,7 @@ function definePoller(app, localId, options) {
     let skipped = 0;
     let failed = 0;
     let refused = 0;
-    for (const { account, credential } of accounts) {
+    for (const { account, auth } of accounts) {
       const saved = previous.find((entry) => entry.schemeId === account.schemeId && entry.accountId === account.accountId);
       const name = `${account.schemeId}/${account.accountId}`;
       const keepSaved = (summary) => {
@@ -723,9 +744,9 @@ function definePoller(app, localId, options) {
           next.push(saved);
         details.push(`${name}: ${summary}`);
       };
-      if (credential.status !== "resolved") {
+      if (auth.status !== "resolved") {
         skipped++;
-        keepSaved(credential.status === "requires-auth" ? "Sign-in or required scope missing" : "Credential missing");
+        keepSaved(auth.status === "requires-auth" ? "Sign-in or required scope missing" : "Credential missing");
         continue;
       }
       let result;
@@ -733,7 +754,7 @@ function definePoller(app, localId, options) {
         result = await options.poll({
           account,
           cursor: structuredClone(saved?.cursor),
-          credential,
+          credential: auth.credential,
           runId
         });
       } catch {
@@ -964,5 +985,6 @@ export {
   transcriptMessageText,
   transcriptMessageTexts,
   transcriptRoleLabel,
-  withCredential
+  withCredential,
+  withEndpointCredential
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",