@yaklabs-ai/plugin-sdk 0.32.0 → 0.34.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.32.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.34.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.32.0" },
+  "compatibility": { "sdk": "^0.34.0" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

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

package/dist/canonical-transcript.d.ts

@@ -304,6 +304,8 @@ declare interface BackgroundTaskFailedEvent {
     readonly errorStack?: string;
     /** An agent task's run failure reason; see `BackgroundTaskCompletion.failureReason` in `@herd/plugin-primitives`. */
     readonly failureReason?: RunFailureReason;
+    /** The run failure record the task relays; see `BackgroundTaskCompletion.failureRef`. */
+    readonly failureRef?: FailureRef;
     readonly snapshot?: BackgroundTaskSnapshot;
 }
 

package/dist/canonical-transcript.js

@@ -681,7 +681,15 @@ var TOOL_CALL_FAILURE_CODES = [
   "uri.not_connected.sign_in_expired",
   "tool.blocked.by_user",
   "tool.blocked.by_rule",
-  "tool.blocked.by_bonsai"
+  "tool.blocked.by_bonsai",
+  // Situation codes that split the settings block (`by_rule` now means a
+  // Permissions rule only) and the Bonsai block further. Same reading rules
+  // as above.
+  "tool.blocked.by_mode",
+  "tool.blocked.protected_path",
+  "tool.blocked.approval_not_shown",
+  "tool.blocked.unverified",
+  "tool.blocked.edits_not_applied"
 ];
 var count = z5.number().int().nonnegative();
 var toolCallFailureDetailsSchema = z5.strictObject({

package/dist/disclosure.d.ts

@@ -337,6 +337,11 @@ declare interface BackgroundTaskCompletion {
     readonly errorStack?: string;
     /** Why a failed AGENT task's run failed, classified from what it threw; absent for other kinds. */
     readonly failureReason?: RunFailureReason;
+    /** The run failure record a failed agent task relays, when its run already recorded one. */
+    readonly failureRef?: {
+        readonly authority: string;
+        readonly id: string;
+    };
 }
 
 declare type BackgroundTaskInspector = () => Promise<string> | string;
@@ -2366,8 +2371,17 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.32.0 lets an app-data source declare its window store as data (#15891). `store` under
  * `contributes.dataSources` replaces a `kay.ui` data materializer, and a change too big for a live
  * update becomes a re-read of the snapshot. A plugin that declares a store declares ^0.32.0.
+ *
+ * 0.33.0 lets a plugin declare a window command with its button and menu item (#15903). `commands`
+ * under `kay.ui` `contributes` names each command's title, icon file, `button`, `menu` and `where`,
+ * and `api.implementCommand(localId, handler)` supplies what it does. `placement` is gone and `icon`
+ * is now a file path: nothing ever read either. A plugin that declares a command declares ^0.33.0.
+ *
+ * 0.34.0 lets a rail entry declare a sidebar (#15901). `panel.body` on a `railEntries` entry names
+ * what fills it, either a `contextOnly` app in the plugin or a body the host ships. Additive: a rail
+ * entry with no `panel` still opens its page alone. A plugin that declares a panel declares ^0.34.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.32.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.34.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -7620,7 +7634,7 @@ declare type TOmitInstantiate<Context extends TProperties, State extends TState,
  * classification (the engine records the rejection on an unexplained failure),
  * and a stored record with one reads as none.
  */
-declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change", "uri.not_connected.pick_account", "uri.not_connected.account_not_allowed", "uri.not_connected.sign_in_expired", "tool.blocked.by_user", "tool.blocked.by_rule", "tool.blocked.by_bonsai"];
+declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change", "uri.not_connected.pick_account", "uri.not_connected.account_not_allowed", "uri.not_connected.sign_in_expired", "tool.blocked.by_user", "tool.blocked.by_rule", "tool.blocked.by_bonsai", "tool.blocked.by_mode", "tool.blocked.protected_path", "tool.blocked.approval_not_shown", "tool.blocked.unverified", "tool.blocked.edits_not_applied"];
 
 /**
  * ---

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

@@ -312,6 +312,11 @@ declare interface BackgroundTaskCompletion {
     readonly errorStack?: string;
     /** Why a failed AGENT task's run failed, classified from what it threw; absent for other kinds. */
     readonly failureReason?: RunFailureReason;
+    /** The run failure record a failed agent task relays, when its run already recorded one. */
+    readonly failureRef?: {
+        readonly authority: string;
+        readonly id: string;
+    };
 }
 
 declare type BackgroundTaskInspector = () => Promise<string> | string;
@@ -2420,8 +2425,17 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.32.0 lets an app-data source declare its window store as data (#15891). `store` under
  * `contributes.dataSources` replaces a `kay.ui` data materializer, and a change too big for a live
  * update becomes a re-read of the snapshot. A plugin that declares a store declares ^0.32.0.
+ *
+ * 0.33.0 lets a plugin declare a window command with its button and menu item (#15903). `commands`
+ * under `kay.ui` `contributes` names each command's title, icon file, `button`, `menu` and `where`,
+ * and `api.implementCommand(localId, handler)` supplies what it does. `placement` is gone and `icon`
+ * is now a file path: nothing ever read either. A plugin that declares a command declares ^0.33.0.
+ *
+ * 0.34.0 lets a rail entry declare a sidebar (#15901). `panel.body` on a `railEntries` entry names
+ * what fills it, either a `contextOnly` app in the plugin or a body the host ships. Additive: a rail
+ * entry with no `panel` still opens its page alone. A plugin that declares a panel declares ^0.34.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.32.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.34.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5697,8 +5711,6 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 "artifacts.preview": "artifacts.preview";
                 "cost.read": "cost.read";
                 "billing.read": "billing.read";
-                "context.read": "context.read";
-                "usage.read": "usage.read";
                 "self-improvement.read": "self-improvement.read";
                 "automations.read": "automations.read";
                 "shared-artifacts.read": "shared-artifacts.read";
@@ -8693,7 +8705,7 @@ declare type TOmitInstantiate<Context extends TProperties, State extends TState,
  * classification (the engine records the rejection on an unexplained failure),
  * and a stored record with one reads as none.
  */
-declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change", "uri.not_connected.pick_account", "uri.not_connected.account_not_allowed", "uri.not_connected.sign_in_expired", "tool.blocked.by_user", "tool.blocked.by_rule", "tool.blocked.by_bonsai"];
+declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change", "uri.not_connected.pick_account", "uri.not_connected.account_not_allowed", "uri.not_connected.sign_in_expired", "tool.blocked.by_user", "tool.blocked.by_rule", "tool.blocked.by_bonsai", "tool.blocked.by_mode", "tool.blocked.protected_path", "tool.blocked.approval_not_shown", "tool.blocked.unverified", "tool.blocked.edits_not_applied"];
 
 /**
  * ---

package/dist/kay-agent.d.ts

@@ -405,6 +405,11 @@ declare interface BackgroundTaskCompletion {
     readonly errorStack?: string;
     /** Why a failed AGENT task's run failed, classified from what it threw; absent for other kinds. */
     readonly failureReason?: RunFailureReason;
+    /** The run failure record a failed agent task relays, when its run already recorded one. */
+    readonly failureRef?: {
+        readonly authority: string;
+        readonly id: string;
+    };
 }
 
 declare type BackgroundTaskInspector = () => Promise<string> | string;
@@ -2695,8 +2700,17 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.32.0 lets an app-data source declare its window store as data (#15891). `store` under
  * `contributes.dataSources` replaces a `kay.ui` data materializer, and a change too big for a live
  * update becomes a re-read of the snapshot. A plugin that declares a store declares ^0.32.0.
+ *
+ * 0.33.0 lets a plugin declare a window command with its button and menu item (#15903). `commands`
+ * under `kay.ui` `contributes` names each command's title, icon file, `button`, `menu` and `where`,
+ * and `api.implementCommand(localId, handler)` supplies what it does. `placement` is gone and `icon`
+ * is now a file path: nothing ever read either. A plugin that declares a command declares ^0.33.0.
+ *
+ * 0.34.0 lets a rail entry declare a sidebar (#15901). `panel.body` on a `railEntries` entry names
+ * what fills it, either a `contextOnly` app in the plugin or a body the host ships. Additive: a rail
+ * entry with no `panel` still opens its page alone. A plugin that declares a panel declares ^0.34.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.32.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.34.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -8831,7 +8845,7 @@ declare type TOmitInstantiate<Context extends TProperties, State extends TState,
  * classification (the engine records the rejection on an unexplained failure),
  * and a stored record with one reads as none.
  */
-declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change", "uri.not_connected.pick_account", "uri.not_connected.account_not_allowed", "uri.not_connected.sign_in_expired", "tool.blocked.by_user", "tool.blocked.by_rule", "tool.blocked.by_bonsai"];
+declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change", "uri.not_connected.pick_account", "uri.not_connected.account_not_allowed", "uri.not_connected.sign_in_expired", "tool.blocked.by_user", "tool.blocked.by_rule", "tool.blocked.by_bonsai", "tool.blocked.by_mode", "tool.blocked.protected_path", "tool.blocked.approval_not_shown", "tool.blocked.unverified", "tool.blocked.edits_not_applied"];
 
 /**
  * ---

package/dist/kay-app.d.ts

@@ -390,6 +390,11 @@ declare interface BackgroundTaskCompletion {
     readonly errorStack?: string;
     /** Why a failed AGENT task's run failed, classified from what it threw; absent for other kinds. */
     readonly failureReason?: RunFailureReason;
+    /** The run failure record a failed agent task relays, when its run already recorded one. */
+    readonly failureRef?: {
+        readonly authority: string;
+        readonly id: string;
+    };
 }
 
 declare type BackgroundTaskInspector = () => Promise<string> | string;
@@ -2650,8 +2655,17 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.32.0 lets an app-data source declare its window store as data (#15891). `store` under
  * `contributes.dataSources` replaces a `kay.ui` data materializer, and a change too big for a live
  * update becomes a re-read of the snapshot. A plugin that declares a store declares ^0.32.0.
+ *
+ * 0.33.0 lets a plugin declare a window command with its button and menu item (#15903). `commands`
+ * under `kay.ui` `contributes` names each command's title, icon file, `button`, `menu` and `where`,
+ * and `api.implementCommand(localId, handler)` supplies what it does. `placement` is gone and `icon`
+ * is now a file path: nothing ever read either. A plugin that declares a command declares ^0.33.0.
+ *
+ * 0.34.0 lets a rail entry declare a sidebar (#15901). `panel.body` on a `railEntries` entry names
+ * what fills it, either a `contextOnly` app in the plugin or a body the host ships. Additive: a rail
+ * entry with no `panel` still opens its page alone. A plugin that declares a panel declares ^0.34.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.32.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.34.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -13560,7 +13574,7 @@ declare interface Tool<TParameters extends TSchema = TSchema> {
  * classification (the engine records the rejection on an unexplained failure),
  * and a stored record with one reads as none.
  */
-declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change", "uri.not_connected.pick_account", "uri.not_connected.account_not_allowed", "uri.not_connected.sign_in_expired", "tool.blocked.by_user", "tool.blocked.by_rule", "tool.blocked.by_bonsai"];
+declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change", "uri.not_connected.pick_account", "uri.not_connected.account_not_allowed", "uri.not_connected.sign_in_expired", "tool.blocked.by_user", "tool.blocked.by_rule", "tool.blocked.by_bonsai", "tool.blocked.by_mode", "tool.blocked.protected_path", "tool.blocked.approval_not_shown", "tool.blocked.unverified", "tool.blocked.edits_not_applied"];
 
 /**
  * ---

package/package.json

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

package/skills/directory-plugin-authoring/SKILL.md

@@ -129,7 +129,9 @@ plugin UI contributes through `api.slots` (`registerPage`, `registerSidebarItem`
 `packages/kay-renderer/src/renderer/src/extension-loader/build-extension-api.ts`). A page gets its own
 activity-rail button when the manifest declares it: `railEntries` under `targets.kay.ui.contributes`,
 with `id`, `title` and `page`, and optionally `icon`, `shortcut`, `order` and `section`. That
-declaration works with no `ui.tsx` at all.
+declaration works with no `ui.tsx` at all. To give the entry a sidebar, add `panel: { body }` naming
+an app in the same manifest with `contextOnly: true`. The sidebar is always there once declared, so
+the app shows its own empty state.
 
 **Icons: declare one plugin icon, override only where you mean it.** Set the manifest `icon` (a
 package-relative SVG) and every surface the plugin contributes inherits it: reference pills, its