@yaklabs-ai/plugin-sdk 0.36.0 → 0.37.1

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.36.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.37.1"
   }
 }
 ```
@@ -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.36.0" },
+  "compatibility": { "sdk": "^0.37.1" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -2390,8 +2390,17 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * under `kay.ui` `contributes` names each page's title, icon file, companion status and opened
  * event. A reference presentation that opens a page gains `scheme` and `addresses`, and may leave
  * out `uriModule` when another layer serves the address. A plugin using these declares ^0.36.0.
+ *
+ * 0.37.0 lets a notification rule's toast declare a preview (#15904). `toastPreviews` under `kay.ui`
+ * `contributes` names the `rule`, the `body` that fills the preview, either a `contextOnly` app in
+ * the plugin or a body the host ships, and the `address` it is about. Additive. A plugin that
+ * declares a preview declares ^0.37.0.
+ *
+ * 0.37.1 adds the required, ungated `featureFlags.value(key)` reader to both backend targets.
+ * Unknown keys return false; the host supplies evaluated values before activation and updates them.
+ * Additive: existing plugins keep loading. A consumer declares ^0.37.1.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.36.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.37.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2679,6 +2688,7 @@ declare interface KayAgentPluginApi {
      * the same zone-of-record port the session stamp uses; see {@link KayAppTime.snapshot}.
      */
     readonly time: KayAppTime;
+    readonly featureFlags: PluginFeatureFlags;
     /**
      * File I/O in user folders, run by the host on its own worker threads under a deadline and
      * answered as a typed result. Always present and ungated: it takes absolute paths and checks no
@@ -4327,6 +4337,12 @@ declare const PluginEventPublishInput: z.ZodObject<{
 
 declare type PluginEventPublishInput = z.infer<typeof PluginEventPublishInput>;
 
+/** Evaluated Bonsai rollout values supplied by the host, without I/O or a grant. */
+declare interface PluginFeatureFlags {
+    /** Read the current boolean; unknown keys return false. */
+    readonly value: (key: string) => boolean;
+}
+
 declare const PluginId: z.ZodString;
 
 declare type PluginId = z.infer<typeof PluginId>;

package/dist/disclosure.js

@@ -886,6 +886,7 @@ function createKayAgentProbeCapabilityHandles() {
     // Dropped: a probe's activation is not the plugin running, so its lines are not the plugin's.
     log: createKayPluginLog(() => {
     }),
+    featureFlags: { value: () => false },
     // A probe has no user-time port, so it answers the zone as unknown - the same contract the
     // real capability keeps for a zone the host cannot read.
     time: {

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

@@ -1196,7 +1196,7 @@ declare function FactorMapping(input: [unknown, unknown, unknown, unknown, unkno
 export declare function fauxAuthContext(overrides?: Partial<ExtensionAuthContext>): ExtensionAuthContext;
 
 /** The capability handles a `KayAgentPluginApi` always carries - authority is decided per call. */
-export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "implementTool" | "systemOne" | "events" | "time" | "log" | "userFiles" | "familyFolder" | "vendoredMcp" | "endpoints" | "compiler">;
+export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "implementTool" | "systemOne" | "events" | "featureFlags" | "time" | "log" | "userFiles" | "familyFolder" | "vendoredMcp" | "endpoints" | "compiler">;
 
 export declare function fauxKayAgentCapabilities(): FauxKayAgentCapabilities;
 
@@ -2444,8 +2444,17 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * under `kay.ui` `contributes` names each page's title, icon file, companion status and opened
  * event. A reference presentation that opens a page gains `scheme` and `addresses`, and may leave
  * out `uriModule` when another layer serves the address. A plugin using these declares ^0.36.0.
+ *
+ * 0.37.0 lets a notification rule's toast declare a preview (#15904). `toastPreviews` under `kay.ui`
+ * `contributes` names the `rule`, the `body` that fills the preview, either a `contextOnly` app in
+ * the plugin or a body the host ships, and the `address` it is about. Additive. A plugin that
+ * declares a preview declares ^0.37.0.
+ *
+ * 0.37.1 adds the required, ungated `featureFlags.value(key)` reader to both backend targets.
+ * Unknown keys return false; the host supplies evaluated values before activation and updates them.
+ * Additive: existing plugins keep loading. A consumer declares ^0.37.1.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.36.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.37.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2730,6 +2739,7 @@ declare interface KayAgentPluginApi {
      * the same zone-of-record port the session stamp uses; see {@link KayAppTime.snapshot}.
      */
     readonly time: KayAppTime;
+    readonly featureFlags: PluginFeatureFlags;
     /**
      * File I/O in user folders, run by the host on its own worker threads under a deadline and
      * answered as a typed result. Always present and ungated: it takes absolute paths and checks no
@@ -4342,6 +4352,12 @@ declare const PluginEventPublishInput: z.ZodObject<{
 
 declare type PluginEventPublishInput = z.infer<typeof PluginEventPublishInput>;
 
+/** Evaluated Bonsai rollout values supplied by the host, without I/O or a grant. */
+declare interface PluginFeatureFlags {
+    /** Read the current boolean; unknown keys return false. */
+    readonly value: (key: string) => boolean;
+}
+
 declare const PluginId: z.ZodString;
 
 declare type PluginId = z.infer<typeof PluginId>;

package/dist/kay-agent-testing.js

@@ -295,6 +295,7 @@ function fauxKayAgentCapabilities() {
     // rejecting double would fail tests for a reason production never has. A test asserting what
     // its plugin publishes overrides this handle after the spread.
     events: { publish: () => void 0 },
+    featureFlags: { value: () => false },
     // A test double has no user-time port, so it answers the zone as unknown - the same contract
     // the real capability keeps for a zone the host cannot read. A test that exercises a plugin's
     // zone-of-record path overrides this handle after the spread.

package/dist/kay-agent.d.ts

@@ -2719,8 +2719,17 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * under `kay.ui` `contributes` names each page's title, icon file, companion status and opened
  * event. A reference presentation that opens a page gains `scheme` and `addresses`, and may leave
  * out `uriModule` when another layer serves the address. A plugin using these declares ^0.36.0.
+ *
+ * 0.37.0 lets a notification rule's toast declare a preview (#15904). `toastPreviews` under `kay.ui`
+ * `contributes` names the `rule`, the `body` that fills the preview, either a `contextOnly` app in
+ * the plugin or a body the host ships, and the `address` it is about. Additive. A plugin that
+ * declares a preview declares ^0.37.0.
+ *
+ * 0.37.1 adds the required, ungated `featureFlags.value(key)` reader to both backend targets.
+ * Unknown keys return false; the host supplies evaluated values before activation and updates them.
+ * Additive: existing plugins keep loading. A consumer declares ^0.37.1.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.36.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.37.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3037,6 +3046,7 @@ export declare interface KayAgentPluginApi {
      * the same zone-of-record port the session stamp uses; see {@link KayAppTime.snapshot}.
      */
     readonly time: KayAppTime;
+    readonly featureFlags: PluginFeatureFlags;
     /**
      * File I/O in user folders, run by the host on its own worker threads under a deadline and
      * answered as a typed result. Always present and ungated: it takes absolute paths and checks no
@@ -5358,6 +5368,12 @@ export declare const PluginEventPublishInput: z.ZodObject<{
 
 export declare type PluginEventPublishInput = z.infer<typeof PluginEventPublishInput>;
 
+/** Evaluated Bonsai rollout values supplied by the host, without I/O or a grant. */
+export declare interface PluginFeatureFlags {
+    /** Read the current boolean; unknown keys return false. */
+    readonly value: (key: string) => boolean;
+}
+
 declare const PluginId: z.ZodString;
 
 declare type PluginId = z.infer<typeof PluginId>;

package/dist/kay-app.d.ts

@@ -2681,8 +2681,17 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * under `kay.ui` `contributes` names each page's title, icon file, companion status and opened
  * event. A reference presentation that opens a page gains `scheme` and `addresses`, and may leave
  * out `uriModule` when another layer serves the address. A plugin using these declares ^0.36.0.
+ *
+ * 0.37.0 lets a notification rule's toast declare a preview (#15904). `toastPreviews` under `kay.ui`
+ * `contributes` names the `rule`, the `body` that fills the preview, either a `contextOnly` app in
+ * the plugin or a body the host ships, and the `address` it is about. Additive. A plugin that
+ * declares a preview declares ^0.37.0.
+ *
+ * 0.37.1 adds the required, ungated `featureFlags.value(key)` reader to both backend targets.
+ * Unknown keys return false; the host supplies evaluated values before activation and updates them.
+ * Additive: existing plugins keep loading. A consumer declares ^0.37.1.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.36.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.37.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5090,6 +5099,7 @@ export declare interface KayAppPluginApi {
      * `Intl` or `process.env.TZ`; see {@link KayAppTime.snapshot}.
      */
     readonly time: KayAppTime;
+    readonly featureFlags: PluginFeatureFlags;
     /**
      * A logger whose lines land in Bonsai's own log under this plugin's id. Always present and
      * ungated, like {@link time}: it writes under the plugin's own name, which a plugin's console
@@ -9757,6 +9767,12 @@ export declare const PluginEventPublishInput: z.ZodObject<{
 
 export declare type PluginEventPublishInput = z.infer<typeof PluginEventPublishInput>;
 
+/** Evaluated Bonsai rollout values supplied by the host, without I/O or a grant. */
+export declare interface PluginFeatureFlags {
+    /** Read the current boolean; unknown keys return false. */
+    readonly value: (key: string) => boolean;
+}
+
 declare const PluginId: z.ZodString;
 
 declare type PluginId = z.infer<typeof PluginId>;

package/package.json

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

@@ -131,7 +131,10 @@ activity-rail button when the manifest declares it: `railEntries` under `targets
 with `id`, `title` and `page`, and optionally `icon`, `shortcut`, `order` and `section`. That
 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.
+the app shows its own empty state. To give a notification rule's toast a "Show changes" preview, add
+a `toastPreviews` entry under `targets.kay.ui.contributes` with `rule` (the rule's `localId`), `body`
+(a `contextOnly` app) and `address` (for example `${navigateTarget}/@diff/${revision}`). The app reads
+the address with `useKayAppReference()`, and the toast's "Open history" opens the same address.
 
 **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