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

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -2385,8 +2385,18 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.36.0 lets a plugin declare its pages and which page an address opens (#15897, #15898). `pages`
+ * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.35.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.37.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -9873,12 +9883,13 @@ declare interface UriPatternInit {
      */
     readonly hostname?: string;
     /**
-     * Slash-delimited path pattern. A final capture may use `:name*` to consume
-     * the remaining path segments, preserving `/` in the captured value. Unless the pattern itself
-     * ends in `/`, an input path ending in one `/` matches as if the slash were absent, so
-     * `threads/t1/` is `threads/t1` (captures and official spelling included) and a lone `/` after a
-     * host is the empty path; a doubled `//` is never dropped, nor the root path of an address with
-     * no host (`bfs:///`).
+     * Slash-delimited path pattern, starting with `/`. `""` matches only an address with no path. A
+     * final capture may use `:name*` to consume the remaining path segments, preserving `/` in the
+     * captured value. A capture may end in a literal extension: `:name.md` matches `billing.md` and
+     * captures `billing`. Unless the pattern itself ends in `/`, an input path ending in one `/`
+     * matches as if the slash were absent, so `threads/t1/` is `threads/t1` (captures and official
+     * spelling included) and a lone `/` after a host is the empty path; a doubled `//` is never
+     * dropped, nor the root path of an address with no host (`bfs:///`).
      */
     readonly pathname?: string;
     /** `&`-delimited query pattern; `""` matches only an address with no query. */

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

@@ -2439,8 +2439,18 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.36.0 lets a plugin declare its pages and which page an address opens (#15897, #15898). `pages`
+ * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.35.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.37.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5647,7 +5657,20 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
     referencePresentations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         localId: z.ZodString;
         globalId: z.ZodString;
-        uriModule: z.ZodString;
+        uriModule: z.ZodOptional<z.ZodString>;
+        schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        addresses: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            pattern: z.ZodObject<{
+                protocol: z.ZodString;
+                hostname: z.ZodString;
+                pathname: z.ZodOptional<z.ZodString>;
+                search: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            objectId: z.ZodOptional<z.ZodString>;
+            open: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodLiteral<"none">;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>;
         resourceKind: z.ZodString;
         open: z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"working-document">;
@@ -5711,6 +5734,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 "sessions.create": "sessions.create";
                 "artifacts.read": "artifacts.read";
                 "artifacts.preview": "artifacts.preview";
+                "markdown.document-view": "markdown.document-view";
                 "cost.read": "cost.read";
                 "billing.read": "billing.read";
                 "skills.read": "skills.read";
@@ -10944,12 +10968,13 @@ declare interface UriPatternInit {
      */
     readonly hostname?: string;
     /**
-     * Slash-delimited path pattern. A final capture may use `:name*` to consume
-     * the remaining path segments, preserving `/` in the captured value. Unless the pattern itself
-     * ends in `/`, an input path ending in one `/` matches as if the slash were absent, so
-     * `threads/t1/` is `threads/t1` (captures and official spelling included) and a lone `/` after a
-     * host is the empty path; a doubled `//` is never dropped, nor the root path of an address with
-     * no host (`bfs:///`).
+     * Slash-delimited path pattern, starting with `/`. `""` matches only an address with no path. A
+     * final capture may use `:name*` to consume the remaining path segments, preserving `/` in the
+     * captured value. A capture may end in a literal extension: `:name.md` matches `billing.md` and
+     * captures `billing`. Unless the pattern itself ends in `/`, an input path ending in one `/`
+     * matches as if the slash were absent, so `threads/t1/` is `threads/t1` (captures and official
+     * spelling included) and a lone `/` after a host is the empty path; a doubled `//` is never
+     * dropped, nor the root path of an address with no host (`bfs:///`).
      */
     readonly pathname?: string;
     /** `&`-delimited query pattern; `""` matches only an address with no query. */

package/dist/kay-agent.d.ts

@@ -2714,8 +2714,18 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.36.0 lets a plugin declare its pages and which page an address opens (#15897, #15898). `pages`
+ * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.35.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.37.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -11195,12 +11205,13 @@ declare interface UriPatternInit {
      */
     readonly hostname?: string;
     /**
-     * Slash-delimited path pattern. A final capture may use `:name*` to consume
-     * the remaining path segments, preserving `/` in the captured value. Unless the pattern itself
-     * ends in `/`, an input path ending in one `/` matches as if the slash were absent, so
-     * `threads/t1/` is `threads/t1` (captures and official spelling included) and a lone `/` after a
-     * host is the empty path; a doubled `//` is never dropped, nor the root path of an address with
-     * no host (`bfs:///`).
+     * Slash-delimited path pattern, starting with `/`. `""` matches only an address with no path. A
+     * final capture may use `:name*` to consume the remaining path segments, preserving `/` in the
+     * captured value. A capture may end in a literal extension: `:name.md` matches `billing.md` and
+     * captures `billing`. Unless the pattern itself ends in `/`, an input path ending in one `/`
+     * matches as if the slash were absent, so `threads/t1/` is `threads/t1` (captures and official
+     * spelling included) and a lone `/` after a host is the empty path; a doubled `//` is never
+     * dropped, nor the root path of an address with no host (`bfs:///`).
      */
     readonly pathname?: string;
     /** `&`-delimited query pattern; `""` matches only an address with no query. */

package/dist/kay-agent.js

@@ -2,7 +2,7 @@
 var SCHEME_RE = /^([a-z][a-z0-9+.-]*):\/\//i;
 var CAPTURE_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var REST_CAPTURE_RE = /^:([A-Za-z_][A-Za-z0-9_]*)\*$/;
-var CONSTRAINED_CAPTURE_RE = /^([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/;
+var CONSTRAINED_CAPTURE_RE = /^([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?(\.[A-Za-z0-9]+)?$/;
 var MAX_CAPTURE_CONSTRAINT_LENGTH = 64;
 function compileUriClaim(claim) {
   if (claim.kind === "scheme") {
@@ -144,8 +144,10 @@ function compileParts(value, separator, options = {}) {
       const constraint = match[2];
       if (constraint !== void 0)
         assertSupportedConstraint(constraint);
+      const suffix = match[3];
       return {
         capture,
+        ...suffix !== void 0 ? { suffix } : {},
         ...constraint !== void 0 ? { constraint: new RegExp(`^(?:${constraint})$`) } : {}
       };
     }
@@ -165,8 +167,11 @@ function matchRoute(pattern, input) {
   if (pattern.hostname !== void 0 && !matchParts(pattern.hostname, input.hostname, isLoneCapture(pattern.hostname) ? void 0 : ".", captures, true)) {
     return void 0;
   }
-  if (pattern.pathname !== void 0 && !matchParts(pattern.pathname, pattern.pathnameEndsInSlash === true ? input.pathname : withoutTrailingSlash(input), "/", captures)) {
-    return void 0;
+  if (pattern.pathname !== void 0) {
+    const pathname = pattern.pathnameEndsInSlash === true ? input.pathname : withoutTrailingSlash(input);
+    if (pattern.pathname.length === 0 ? pathname !== "" : !matchParts(pattern.pathname, pathname, "/", captures)) {
+      return void 0;
+    }
   }
   if (pattern.search !== void 0 && (pattern.search.length === 0 ? input.search !== "" : !matchParts(pattern.search, input.search, "&", captures))) {
     return void 0;
@@ -200,7 +205,11 @@ function matchParts(pattern, value, separator, captures, foldLiterals = false) {
       return false;
     const actual = parts[partIndex];
     if (expected.capture !== void 0) {
-      const decoded = safeDecode(actual);
+      const { suffix } = expected;
+      if (suffix !== void 0 && (!actual.endsWith(suffix) || actual.length === suffix.length)) {
+        return false;
+      }
+      const decoded = safeDecode(suffix === void 0 ? actual : actual.slice(0, -suffix.length));
       if (expected.constraint !== void 0 && !expected.constraint.test(decoded)) {
         return false;
       }

package/dist/kay-app.d.ts

@@ -2676,8 +2676,18 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.36.0 lets a plugin declare its pages and which page an address opens (#15897, #15898). `pages`
+ * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.35.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.37.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -15980,12 +15990,13 @@ declare interface UriPatternInit {
      */
     readonly hostname?: string;
     /**
-     * Slash-delimited path pattern. A final capture may use `:name*` to consume
-     * the remaining path segments, preserving `/` in the captured value. Unless the pattern itself
-     * ends in `/`, an input path ending in one `/` matches as if the slash were absent, so
-     * `threads/t1/` is `threads/t1` (captures and official spelling included) and a lone `/` after a
-     * host is the empty path; a doubled `//` is never dropped, nor the root path of an address with
-     * no host (`bfs:///`).
+     * Slash-delimited path pattern, starting with `/`. `""` matches only an address with no path. A
+     * final capture may use `:name*` to consume the remaining path segments, preserving `/` in the
+     * captured value. A capture may end in a literal extension: `:name.md` matches `billing.md` and
+     * captures `billing`. Unless the pattern itself ends in `/`, an input path ending in one `/`
+     * matches as if the slash were absent, so `threads/t1/` is `threads/t1` (captures and official
+     * spelling included) and a lone `/` after a host is the empty path; a doubled `//` is never
+     * dropped, nor the root path of an address with no host (`bfs:///`).
      */
     readonly pathname?: string;
     /** `&`-delimited query pattern; `""` matches only an address with no query. */

package/dist/vendored-mcp.d.ts

@@ -823,12 +823,13 @@ declare interface UriPatternInit {
      */
     readonly hostname?: string;
     /**
-     * Slash-delimited path pattern. A final capture may use `:name*` to consume
-     * the remaining path segments, preserving `/` in the captured value. Unless the pattern itself
-     * ends in `/`, an input path ending in one `/` matches as if the slash were absent, so
-     * `threads/t1/` is `threads/t1` (captures and official spelling included) and a lone `/` after a
-     * host is the empty path; a doubled `//` is never dropped, nor the root path of an address with
-     * no host (`bfs:///`).
+     * Slash-delimited path pattern, starting with `/`. `""` matches only an address with no path. A
+     * final capture may use `:name*` to consume the remaining path segments, preserving `/` in the
+     * captured value. A capture may end in a literal extension: `:name.md` matches `billing.md` and
+     * captures `billing`. Unless the pattern itself ends in `/`, an input path ending in one `/`
+     * matches as if the slash were absent, so `threads/t1/` is `threads/t1` (captures and official
+     * spelling included) and a lone `/` after a host is the empty path; a doubled `//` is never
+     * dropped, nor the root path of an address with no host (`bfs:///`).
      */
     readonly pathname?: string;
     /** `&`-delimited query pattern; `""` matches only an address with no query. */

package/dist/vendored-mcp.js

@@ -73,7 +73,7 @@ function copyClaim(claim) {
 var SCHEME_RE = /^([a-z][a-z0-9+.-]*):\/\//i;
 var CAPTURE_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var REST_CAPTURE_RE = /^:([A-Za-z_][A-Za-z0-9_]*)\*$/;
-var CONSTRAINED_CAPTURE_RE = /^([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/;
+var CONSTRAINED_CAPTURE_RE = /^([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?(\.[A-Za-z0-9]+)?$/;
 var MAX_CAPTURE_CONSTRAINT_LENGTH = 64;
 function compileUriClaim(claim) {
   if (claim.kind === "scheme") {
@@ -215,8 +215,10 @@ function compileParts(value, separator, options = {}) {
       const constraint = match[2];
       if (constraint !== void 0)
         assertSupportedConstraint(constraint);
+      const suffix = match[3];
       return {
         capture,
+        ...suffix !== void 0 ? { suffix } : {},
         ...constraint !== void 0 ? { constraint: new RegExp(`^(?:${constraint})$`) } : {}
       };
     }
@@ -236,8 +238,11 @@ function matchRoute(pattern, input) {
   if (pattern.hostname !== void 0 && !matchParts(pattern.hostname, input.hostname, isLoneCapture(pattern.hostname) ? void 0 : ".", captures, true)) {
     return void 0;
   }
-  if (pattern.pathname !== void 0 && !matchParts(pattern.pathname, pattern.pathnameEndsInSlash === true ? input.pathname : withoutTrailingSlash(input), "/", captures)) {
-    return void 0;
+  if (pattern.pathname !== void 0) {
+    const pathname = pattern.pathnameEndsInSlash === true ? input.pathname : withoutTrailingSlash(input);
+    if (pattern.pathname.length === 0 ? pathname !== "" : !matchParts(pattern.pathname, pathname, "/", captures)) {
+      return void 0;
+    }
   }
   if (pattern.search !== void 0 && (pattern.search.length === 0 ? input.search !== "" : !matchParts(pattern.search, input.search, "&", captures))) {
     return void 0;
@@ -271,7 +276,11 @@ function matchParts(pattern, value, separator, captures, foldLiterals = false) {
       return false;
     const actual = parts[partIndex];
     if (expected.capture !== void 0) {
-      const decoded = safeDecode(actual);
+      const { suffix } = expected;
+      if (suffix !== void 0 && (!actual.endsWith(suffix) || actual.length === suffix.length)) {
+        return false;
+      }
+      const decoded = safeDecode(suffix === void 0 ? actual : actual.slice(0, -suffix.length));
       if (expected.constraint !== void 0 && !expected.constraint.test(decoded)) {
         return false;
       }

package/package.json

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

@@ -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