@yaklabs-ai/plugin-sdk 0.40.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.40.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.40.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.40.0",
+  "version": "0.42.0",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/disclosure.d.ts

@@ -2414,8 +2414,15 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * feed may now declare a `store`. It removes the `cost.read`, `skills.read`, `memory.read` and
  * `self-improvement.read` host capabilities, so a manifest still listing one no longer parses and
  * lists the feed instead. A plugin that lists feeds declares ^0.40.0.
+ *
+ * 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.40.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

@@ -2468,8 +2468,15 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * feed may now declare a `store`. It removes the `cost.read`, `skills.read`, `memory.read` and
  * `self-improvement.read` host capabilities, so a manifest still listing one no longer parses and
  * lists the feed instead. A plugin that lists feeds declares ^0.40.0.
+ *
+ * 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.40.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5793,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

@@ -2743,8 +2743,15 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * feed may now declare a `store`. It removes the `cost.read`, `skills.read`, `memory.read` and
  * `self-improvement.read` host capabilities, so a manifest still listing one no longer parses and
  * lists the feed instead. A plugin that lists feeds declares ^0.40.0.
+ *
+ * 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.40.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

@@ -2719,8 +2719,15 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * feed may now declare a `store`. It removes the `cost.read`, `skills.read`, `memory.read` and
  * `self-improvement.read` host capabilities, so a manifest still listing one no longer parses and
  * lists the feed instead. A plugin that lists feeds declares ^0.40.0.
+ *
+ * 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.40.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.42.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3929,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. */
@@ -3945,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.
@@ -4111,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
@@ -4356,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;
 }
 
 /**
@@ -4615,6 +4619,21 @@ export declare interface KayAppMarketplaceContributors {
     };
 }
 
+/** Calls tools on this plugin's manifest-declared MCP servers through Bonsai's managed connection. */
+export declare interface KayAppMcp {
+    /**
+     * Uses the current app-wide server set, without a session or working directory.
+     * Refuses undeclared or no-longer-hosted servers. Sign-in and tool failures return typed outcomes;
+     * credentials remain with the host. Like the agent-side vendored MCP API, calls can read or write
+     * and do not use the agent's per-tool approval path.
+     */
+    callTool(input: {
+        readonly server: string;
+        readonly tool: string;
+        readonly args: Readonly<Record<string, unknown>>;
+    }): Promise<VendoredMcpOutcome>;
+}
+
 /**
  * Notes through Memory's ordinary notebook operations, without a chat session. Each call checks
  * `memory.read` or `memory.write`; a missing notebook or refused grant rejects. Paths are note
@@ -5087,6 +5106,7 @@ export declare interface KayAppPhaseShiftSessionEvent extends KayAppSessionEvent
  * physical sandbox against ambient Node imports.
  */
 export declare interface KayAppPluginApi {
+    readonly mcp: KayAppMcp;
     /** This plugin's canonical id (already validated by the host registry). */
     readonly id: string;
     /** Register app-lifetime cleanup for plugin-owned processes, sockets, watchers, or timers. */
@@ -5388,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>>;
 }
@@ -5545,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 {
@@ -8126,7 +8101,7 @@ export declare interface KayAppWhiteboardTypes {
  */
 export declare interface KayAppWorkflowAccount {
     readonly account: KayAppAccountSummary;
-    readonly credential: KayAppBackgroundCredentialResult;
+    readonly auth: KayAppCredentialResolution;
 }
 
 /**
@@ -10295,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;
@@ -16731,6 +16706,52 @@ declare type UserShellCommandMessage = CustomMessage<UserShellCommandDetails> &
     readonly display: true;
 };
 
+/**
+ * ---
+ * responsibility: The one interface through which a vendored-MCP plugin's code calls a tool on its
+ *   own vendored MCP server, so every read-through plugin and the daemon that implements the port
+ *   agree on the same shape by construction.
+ * owns:
+ *   - {@link VendoredMcpPort} - what a plugin's URI module and tools call.
+ *   - {@link VendoredMcpOutcome} - the typed result a plugin decodes, including every failure it
+ *     must surface to the agent rather than swallow.
+ * does_not_own:
+ *   - The implementation. A plugin never dials MCP itself: it takes the port from
+ *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the daemon binds to the
+ *     plugin's own hosted server over its MCP host. Plugin source stays host-free, and a plugin
+ *     under test substitutes a fake port.
+ *   - Which tool names exist. `TTool` is the plugin's own union of the vendor tools it calls; the
+ *     port is generic so a typo in a tool name fails typecheck inside the plugin.
+ * ---
+ */
+/**
+ * Why a call failed, as the plugin must tell the agent. `needs-auth` carries the exact service to
+ * reconnect (`serviceId`) so a plugin can name it in its error instead of returning an empty
+ * result; today's plugins name their statically declared `requiresAuth` service instead, which is
+ * the same service for a single-service plugin. `unknown-server` and `unknown-tool` are wiring
+ * faults (a server Bonsai does not host for this plugin, or a tool name the server does not have)
+ * and stay loud for the same reason: an unreachable host must never decode as "no data".
+ */
+declare type VendoredMcpFailureReason = "needs-auth" | "unknown-server" | "unknown-tool" | "failed";
+
+declare type VendoredMcpOutcome = 
+/**
+* `value` is the tool's `structuredContent` when it sent one, else its text content parsed as
+* JSON, else that text as a string: a vendor tool that answers in prose (a transcript, a
+* markdown summary) is a result, not a failure. A route that needs a record rejects a string
+* itself, with its own message.
+*/
+    {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly reason: VendoredMcpFailureReason;
+    readonly message: string;
+    /** Exact reconnect target supplied by the MCP host for an auth failure. */
+    readonly serviceId?: string;
+};
+
 /** Creates a Void type. */
 declare function Void(options?: TSchemaOptions): TVoid;
 
@@ -16898,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.40.0",
+  "version": "0.42.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",