@yaklabs-ai/plugin-sdk 0.40.0 → 0.41.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.41.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.41.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.41.0",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/disclosure.d.ts

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

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

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

package/dist/kay-agent.d.ts

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

package/dist/kay-app.d.ts

@@ -2719,8 +2719,11 @@ 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).
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.40.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.41.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4615,6 +4618,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 +5105,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. */
@@ -16731,6 +16750,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;
 

package/package.json

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