@yaklabs-ai/plugin-sdk 0.33.0 → 0.35.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.33.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.35.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.33.0" },
+  "compatibility": { "sdk": "^0.35.0" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.33.0",
+  "version": "0.35.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;
 }
 
@@ -1596,11 +1598,18 @@ declare type FailureJsonValue = null | boolean | number | string | readonly Fail
     readonly [key: string]: FailureJsonValue;
 };
 
-declare interface FailureOccurrence<C = FailureJsonValue> {
+/**
+ * One failure, as every lane records it. `Code` and `Domain` default to
+ * `string`; a lane that declares its codes (an `as const` list beside its
+ * cause schema) passes them, so minting a record with an undeclared code
+ * fails typecheck. Reading is unchanged: `failureSchema` keeps both as
+ * strings, so a saved record with an unknown code still reads.
+ */
+declare interface FailureOccurrence<C = FailureJsonValue, Code extends string = string, Domain extends string = string> {
     readonly ref: FailureRef;
     readonly sourceRef: FailureRef;
-    readonly domain: string;
-    readonly code: string;
+    readonly domain: Domain;
+    readonly code: Code;
     readonly context: {
         readonly component: string;
         readonly operation: string;
@@ -6831,6 +6840,17 @@ declare interface Tool<TParameters extends TSchema = TSchema> {
     constrainedSampling?: false | ConstrainedSamplingConfig;
 }
 
+/**
+ * The closed vocabulary of tool call failure codes. The engine and the tools
+ * mint only these; a returned failure with a code outside it is not a
+ * 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", "tool.blocked.by_mode", "tool.blocked.protected_path", "tool.blocked.approval_not_shown", "tool.blocked.unverified", "tool.blocked.edits_not_applied"];
+
+/** The `domain` of a tool call failure occurrence; it selects this lane's cause contract. */
+declare const TOOL_CALL_FAILURE_DOMAIN: "tool-call";
+
 declare interface ToolCall {
     type: "toolCall";
     id: string;
@@ -6889,13 +6909,15 @@ declare const toolCallFailureCauseSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 
+declare type ToolCallFailureCode = (typeof TOOL_CALL_FAILURE_CODES)[number];
+
 /**
  * The failure occurrence a failed tool result carries under
  * `details.toolCallFailure`: the classification's code at the occurrence
  * level and the rest as its cause, with its own ref and the call it came out
  * of as its operation.
  */
-declare type ToolCallFailureOccurrence = FailureOccurrence<ToolCallFailureCause>;
+declare type ToolCallFailureOccurrence = FailureOccurrence<ToolCallFailureCause, ToolCallFailureCode, typeof TOOL_CALL_FAILURE_DOMAIN>;
 
 /**
  * The minimal shape this leaf reads from a session entry: a `timestamp` and the

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;
@@ -2371,8 +2376,17 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.35.0 lets a rail entry declare a count badge as data (#15900). `badge` on a `railEntries` entry
+ * names one of the plugin's `rows` data sources, an optional `where` and a plural `label`.
+ * `app.skills` gains `listPendingSuggestions` and `subscribeSuggestions` under `skills.read`. A plugin
+ * that declares a badge declares ^0.35.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.33.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.35.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -7625,7 +7639,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;
@@ -2425,8 +2430,17 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.35.0 lets a rail entry declare a count badge as data (#15900). `badge` on a `railEntries` entry
+ * names one of the plugin's `rows` data sources, an optional `where` and a plural `label`.
+ * `app.skills` gains `listPendingSuggestions` and `subscribeSuggestions` under `skills.read`. A plugin
+ * that declares a badge declares ^0.35.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.33.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.35.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4747,14 +4761,14 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             "kay.ui": "kay.ui";
         }>;
         kind: z.ZodEnum<{
+            endpoint: "endpoint";
             tool: "tool";
             resource: "resource";
-            endpoint: "endpoint";
             storage: "storage";
-            command: "command";
             uriModule: "uriModule";
             authService: "authService";
             app: "app";
+            command: "command";
             configSection: "configSection";
             skill: "skill";
             converter: "converter";
@@ -5275,30 +5289,30 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             description: z.ZodString;
             operations: z.ZodExactOptional<z.ZodArray<z.ZodEnum<{
                 search: "search";
-                delete: "delete";
                 list: "list";
                 read: "read";
                 write: "write";
                 help: "help";
                 edit: "edit";
+                delete: "delete";
             }>>>;
             operationDocs: z.ZodExactOptional<z.ZodRecord<z.ZodEnum<{
                 search: "search";
-                delete: "delete";
                 list: "list";
                 read: "read";
                 write: "write";
                 help: "help";
                 edit: "edit";
+                delete: "delete";
             }> & z.core.$partial, z.ZodString>>;
             operationDefaults: z.ZodExactOptional<z.ZodRecord<z.ZodEnum<{
                 search: "search";
-                delete: "delete";
                 list: "list";
                 read: "read";
                 write: "write";
                 help: "help";
                 edit: "edit";
+                delete: "delete";
             }> & z.core.$partial, z.ZodEnum<{
                 never: "never";
                 allow: "allow";
@@ -5357,12 +5371,12 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 action: z.ZodString;
                 operations: z.ZodExactOptional<z.ZodArray<z.ZodEnum<{
                     search: "search";
-                    delete: "delete";
                     list: "list";
                     read: "read";
                     write: "write";
                     help: "help";
                     edit: "edit";
+                    delete: "delete";
                 }>>>;
                 routes: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
                 query: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -5370,12 +5384,12 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 public: z.ZodLiteral<true>;
                 operations: z.ZodExactOptional<z.ZodArray<z.ZodEnum<{
                     search: "search";
-                    delete: "delete";
                     list: "list";
                     read: "read";
                     write: "write";
                     help: "help";
                     edit: "edit";
+                    delete: "delete";
                 }>>>;
                 routes: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
                 query: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -5557,9 +5571,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         localId: z.ZodString;
         globalId: z.ZodString;
         scope: z.ZodEnum<{
-            session: "session";
             runtime: "runtime";
             account: "account";
+            session: "session";
         }>;
         snapshot: z.ZodObject<{
             version: z.ZodNumber;
@@ -5693,17 +5707,17 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 globalId: z.ZodString;
             }, z.core.$strict>>>;
             host: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                "navigation.open-session": "navigation.open-session";
                 "sessions.create": "sessions.create";
-                "memory.read": "memory.read";
-                "skills.read": "skills.read";
-                "automations.run": "automations.run";
                 "artifacts.read": "artifacts.read";
-                "navigation.open-session": "navigation.open-session";
                 "artifacts.preview": "artifacts.preview";
                 "cost.read": "cost.read";
                 "billing.read": "billing.read";
+                "skills.read": "skills.read";
+                "memory.read": "memory.read";
                 "self-improvement.read": "self-improvement.read";
                 "automations.read": "automations.read";
+                "automations.run": "automations.run";
                 "shared-artifacts.read": "shared-artifacts.read";
                 "workspace.place-pane": "workspace.place-pane";
                 "workspace.pane-header": "workspace.pane-header";
@@ -8696,7 +8710,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;
@@ -2700,8 +2705,17 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.35.0 lets a rail entry declare a count badge as data (#15900). `badge` on a `railEntries` entry
+ * names one of the plugin's `rows` data sources, an optional `where` and a plural `label`.
+ * `app.skills` gains `listPendingSuggestions` and `subscribeSuggestions` under `skills.read`. A plugin
+ * that declares a badge declares ^0.35.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.33.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.35.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -8836,7 +8850,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-session-summary.d.ts

@@ -453,9 +453,9 @@ declare const CorpusResourceInvocationQuery: z.ZodObject<{
     }, z.core.$strict>>;
     limit: z.ZodOptional<z.ZodNumber>;
     rootCreatedByKind: z.ZodOptional<z.ZodEnum<{
+        agent: "agent";
         plugin: "plugin";
         human: "human";
-        agent: "agent";
         trigger: "trigger";
         daemon: "daemon";
     }>>;
@@ -841,11 +841,18 @@ declare type FailureJsonValue = null | boolean | number | string | readonly Fail
     readonly [key: string]: FailureJsonValue;
 };
 
-declare interface FailureOccurrence<C = FailureJsonValue> {
+/**
+ * One failure, as every lane records it. `Code` and `Domain` default to
+ * `string`; a lane that declares its codes (an `as const` list beside its
+ * cause schema) passes them, so minting a record with an undeclared code
+ * fails typecheck. Reading is unchanged: `failureSchema` keeps both as
+ * strings, so a saved record with an unknown code still reads.
+ */
+declare interface FailureOccurrence<C = FailureJsonValue, Code extends string = string, Domain extends string = string> {
     readonly ref: FailureRef;
     readonly sourceRef: FailureRef;
-    readonly domain: string;
-    readonly code: string;
+    readonly domain: Domain;
+    readonly code: Code;
     readonly context: {
         readonly component: string;
         readonly operation: string;

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;
@@ -790,9 +795,9 @@ export declare const CorpusResourceInvocationQuery: z.ZodObject<{
     }, z.core.$strict>>;
     limit: z.ZodOptional<z.ZodNumber>;
     rootCreatedByKind: z.ZodOptional<z.ZodEnum<{
+        agent: "agent";
         plugin: "plugin";
         human: "human";
-        agent: "agent";
         trigger: "trigger";
         daemon: "daemon";
     }>>;
@@ -1496,11 +1501,18 @@ declare type FailureJsonValue = null | boolean | number | string | readonly Fail
     readonly [key: string]: FailureJsonValue;
 };
 
-declare interface FailureOccurrence<C = FailureJsonValue> {
+/**
+ * One failure, as every lane records it. `Code` and `Domain` default to
+ * `string`; a lane that declares its codes (an `as const` list beside its
+ * cause schema) passes them, so minting a record with an undeclared code
+ * fails typecheck. Reading is unchanged: `failureSchema` keeps both as
+ * strings, so a saved record with an unknown code still reads.
+ */
+declare interface FailureOccurrence<C = FailureJsonValue, Code extends string = string, Domain extends string = string> {
     readonly ref: FailureRef;
     readonly sourceRef: FailureRef;
-    readonly domain: string;
-    readonly code: string;
+    readonly domain: Domain;
+    readonly code: Code;
     readonly context: {
         readonly component: string;
         readonly operation: string;
@@ -2655,8 +2667,17 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.35.0 lets a rail entry declare a count badge as data (#15900). `badge` on a `railEntries` entry
+ * names one of the plugin's `rows` data sources, an optional `where` and a plural `label`.
+ * `app.skills` gains `listPendingSuggestions` and `subscribeSuggestions` under `skills.read`. A plugin
+ * that declares a badge declares ^0.35.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.33.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.35.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4977,6 +4998,18 @@ export declare interface KayAppPaths {
     readonly logsRoot?: string;
 }
 
+/** One suggested change waiting for a person's review. Ids repeat across skills, so all three identify it. */
+export declare interface KayAppPendingSkillSuggestion {
+    readonly sourceId: string;
+    readonly skillName: string;
+    readonly suggestionId: string;
+}
+
+export declare type KayAppPendingSkillSuggestionsResult = {
+    readonly status: "ok";
+    readonly suggestions: readonly KayAppPendingSkillSuggestion[];
+} | KayAppSkillsUnavailable;
+
 export declare interface KayAppPermissions {
     /**
      * Register a live source of permission rows under a plugin-local id (register during
@@ -7189,6 +7222,13 @@ export declare interface KayAppSkills {
     list(): Promise<KayAppSkillsListResult>;
     /** One skill's identity, current version, and suggestions. */
     read(skill: KayAppSkillRef): Promise<KayAppSkillReadResult>;
+    /** Every suggested change, across all skills, still waiting for a person's review. */
+    listPendingSuggestions(): Promise<KayAppPendingSkillSuggestionsResult>;
+    /**
+     * Calls `listener` when {@link KayAppSkills.listPendingSuggestions} may answer differently, at most
+     * once per burst of writes. Returns an unsubscribe.
+     */
+    subscribeSuggestions(listener: () => void): () => void;
     /** One skill's revisions, newest first, each with its version and how it came about. */
     history(skill: KayAppSkillRef, options?: KayAppSkillHistoryOptions): Promise<KayAppSkillHistoryResult>;
     /** How the skill's local copy differs from its source. */
@@ -13565,7 +13605,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/dist/kay-app.js

@@ -735,6 +735,8 @@ function createUnavailableSkills(message) {
     },
     list: async () => unavailable,
     read: async () => unavailable,
+    listPendingSuggestions: async () => unavailable,
+    subscribeSuggestions: () => () => void 0,
     history: async () => unavailable,
     diff: async () => unavailable,
     revision: async () => unavailable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.33.0",
+  "version": "0.35.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