@yaklabs-ai/plugin-sdk 0.13.1 → 0.13.2

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.1"
+    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.2"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -3230,6 +3230,12 @@ declare interface UriHelp {
     readonly templates?: readonly UriTemplate[];
     readonly examples?: readonly UriExample[];
     readonly notes?: readonly string[];
+    /**
+     * Set when this help, for the address it was asked about, carries text a third party wrote and
+     * the module relays as it received it (an MCP server's own tool names and descriptions), rather
+     * than text the module's author wrote. Absent: the module's own text.
+     */
+    readonly thirdPartyContent?: true;
 }
 
 declare interface UriHintTriggers {

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

@@ -3128,6 +3128,12 @@ declare interface UriHelp {
     readonly templates?: readonly UriTemplate[];
     readonly examples?: readonly UriExample[];
     readonly notes?: readonly string[];
+    /**
+     * Set when this help, for the address it was asked about, carries text a third party wrote and
+     * the module relays as it received it (an MCP server's own tool names and descriptions), rather
+     * than text the module's author wrote. Absent: the module's own text.
+     */
+    readonly thirdPartyContent?: true;
 }
 
 declare interface UriHintTriggers {

package/dist/kay-agent.d.ts

@@ -2811,6 +2811,7 @@ declare const KayPluginManifestV1: z.ZodObject<{
         minKayVersion: z.ZodOptional<z.ZodString>;
         sdk: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
+    ownedByBonsai: z.ZodOptional<z.ZodBoolean>;
     dependencies: z.ZodOptional<z.ZodObject<{
         plugins: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
@@ -3422,6 +3423,10 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"skills.read">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"tools.describe">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"workspace.command">;
@@ -4939,6 +4944,12 @@ declare interface UriHelp {
     readonly templates?: readonly UriTemplate[];
     readonly examples?: readonly UriExample[];
     readonly notes?: readonly string[];
+    /**
+     * Set when this help, for the address it was asked about, carries text a third party wrote and
+     * the module relays as it received it (an MCP server's own tool names and descriptions), rather
+     * than text the module's author wrote. Absent: the module's own text.
+     */
+    readonly thirdPartyContent?: true;
 }
 
 declare interface UriHintTriggers {

package/dist/kay-app.d.ts

@@ -431,6 +431,12 @@ export declare function createFallbackOnlyWithJev(): WithJev;
  */
 export declare function createUnavailableSkills(message: string): KayAppSkills;
 
+/**
+ * The `app.tools` a host that cannot describe tools binds: every call answers `not-available`, so
+ * a plugin's code path never depends on host composition.
+ */
+export declare function createUnavailableTools(): KayAppTools;
+
 declare interface CustomEntry extends EntryBase {
     type: "custom";
     customType: string;
@@ -2863,6 +2869,14 @@ export declare interface KayAppPluginApi {
      * present, like {@link signals}.
      */
     readonly skills: KayAppSkills;
+    /**
+     * What a live session's tools and addresses say to the agent, where each comes from, and whether
+     * each is one of Bonsai's own. Each call is checked against `tools.describe`; a refused grant or
+     * a session that is not live resolves to `{ status: "unavailable" }`, never a rejection, while
+     * the plugin is enabled. After it is disabled, a kept handle's methods throw synchronously.
+     * Always present, like {@link skills}.
+     */
+    readonly tools: KayAppTools;
     /** The app-wide endpoint bus (register handlers a consuming surface invokes). */
     readonly endpoints: KayAppEndpoints;
     /** Publish one event declared by this plugin's `kay.app` manifest target. */
@@ -4202,6 +4216,21 @@ export declare type KayAppToolDefinition<TParams extends ToolParametersWire = To
     execute(toolCallId: string, params: ToolExecutionAwareParams<TParams>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: KayAppToolContext): Promise<AgentToolResult<TDetails>>;
 };
 
+export declare interface KayAppToolDescription {
+    readonly ref: KayAppToolRef;
+    /** `false`: no such tool is registered, or no module owns that address, in this session. */
+    readonly found: boolean;
+    /**
+     * For a tool, its own registered description. For an address, its help rendered as `help <uri>`
+     * renders it for the agent; for `mcp://<server>`, that is the server's tool list in the server's
+     * own words.
+     */
+    readonly description?: string;
+    readonly origin?: KayAppToolOrigin;
+    /** Whether this is one of Bonsai's own tools or addresses. `false` when not found. */
+    readonly ownedByBonsai: boolean;
+}
+
 /**
  * The fine-grained, app-wide per-tool event stream (every session's tool executions). Carries the
  * redaction caveat: raw tool args/results are OFF in packaged builds, so a handler must treat
@@ -4214,6 +4243,20 @@ export declare interface KayAppToolEvents {
     subscribe(handler: (event: unknown) => void): () => void;
 }
 
+/** Where a described tool or address comes from. */
+export declare type KayAppToolOrigin = 
+/** The agent kernel's own (`bash`, `read`, `help`, `skill://`). */
+    {
+    readonly kind: "core";
+}
+/** Bonsai's host, outside any plugin (`task_status`, `config://`). */
+| {
+    readonly kind: "host";
+} | {
+    readonly kind: "plugin";
+    readonly pluginId: string;
+};
+
 /**
  * `app.permissions` — the plugin-facing seam through which a `kay.app` target advertises the
  * permission rows for tools it gates DYNAMICALLY, so they show in Bonsai's permission ledger with
@@ -4264,6 +4307,52 @@ export declare interface KayAppToolPermissionSource {
     readonly list: () => readonly KayAppToolPermissionDeclaration[] | Promise<readonly KayAppToolPermissionDeclaration[]>;
 }
 
+/**
+ * The plugin-facing `kay.app` tools contract: for the tools and addresses a live session can use,
+ * the text the agent sees for each, where each comes from, and whether each is one of Bonsai's own.
+ *
+ * Every call is checked against the `tools.describe` claim at the call, so a grant or revocation
+ * takes effect on the next one. Like `app.skills`, the member is ALWAYS present and no call rejects
+ * while the plugin is enabled: a refused grant or a session that is not live resolves to
+ * `{ status: "unavailable" }`. After the plugin is disabled, a kept handle's methods throw
+ * synchronously.
+ *
+ * `ownedByBonsai` is a fact declared where each surface is defined (a bundled plugin's manifest, or
+ * the host's own registration), never a list kept by the host. What a plugin does with it is the
+ * plugin's call.
+ */
+/** A tool or an address to describe. */
+export declare type KayAppToolRef = 
+/** A registered tool by name, e.g. `bash`, `read`, `mcp`, `submit_final`. */
+    {
+    readonly kind: "tool";
+    readonly name: string;
+}
+/** A URI address whose `help` is wanted, e.g. `gmail://` or `mcp://linear`. */
+| {
+    readonly kind: "address";
+    readonly uri: string;
+};
+
+/** `app.tools`: what a live session's tools and addresses say, each call checked against `tools.describe`. */
+export declare interface KayAppTools {
+    describe(sessionId: string, refs: readonly KayAppToolRef[]): Promise<KayAppToolsDescribeResult>;
+}
+
+/**
+ * `not-granted`: the user has not granted `tools.describe`. `no-session`: the session is not live
+ * on this host (only live sessions are described). `not-available`: this host cannot describe
+ * tools.
+ */
+export declare type KayAppToolsDescribeResult = {
+    readonly status: "ok";
+    /** One per ref, in the order of the refs. */
+    readonly tools: readonly KayAppToolDescription[];
+} | {
+    readonly status: "unavailable";
+    readonly reason: "not-granted" | "no-session" | "not-available";
+};
+
 /** An eligible settled turn — the generic door's root event. */
 export declare interface KayAppTurnSettledSessionEvent extends KayAppSessionEventBase {
     readonly type: "turn-settled";
@@ -6427,6 +6516,12 @@ declare interface UriHelp {
     readonly templates?: readonly UriTemplate[];
     readonly examples?: readonly UriExample[];
     readonly notes?: readonly string[];
+    /**
+     * Set when this help, for the address it was asked about, carries text a third party wrote and
+     * the module relays as it received it (an MCP server's own tool names and descriptions), rather
+     * than text the module's author wrote. Absent: the module's own text.
+     */
+    readonly thirdPartyContent?: true;
 }
 
 declare interface UriHintTriggers {

package/dist/kay-app.js

@@ -503,6 +503,13 @@ function createUnavailableSkills(message) {
   };
 }
 
+// packages/plugin-sdk/dist/kay-app/tools.js
+function createUnavailableTools() {
+  return {
+    describe: async () => ({ status: "unavailable", reason: "not-available" })
+  };
+}
+
 // packages/plugin-sdk/dist/kay-app/transcript-text.js
 function transcriptMessageTexts(entries) {
   return entries.flatMap((entry) => {
@@ -572,6 +579,7 @@ export {
   createFallbackOnlySignals,
   createFallbackOnlyWithJev,
   createUnavailableSkills,
+  createUnavailableTools,
   invalidObservation,
   isRetryable,
   parseLineSelector,

package/package.json

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