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

package/THIRD-PARTY-INVENTORY.json

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

package/dist/canonical-transcript.d.ts

@@ -1598,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;
@@ -6833,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;
@@ -6891,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/disclosure.d.ts

@@ -2380,8 +2380,18 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.34.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.36.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -9868,12 +9878,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

@@ -2434,8 +2434,18 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.34.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.36.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4756,14 +4766,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";
@@ -5284,30 +5294,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";
@@ -5366,12 +5376,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>>;
@@ -5379,12 +5389,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>>;
@@ -5566,9 +5576,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;
@@ -5642,7 +5652,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">;
@@ -5702,17 +5725,18 @@ 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";
+                "markdown.document-view": "markdown.document-view";
                 "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";
@@ -10939,12 +10963,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

@@ -2709,8 +2709,18 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.34.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.36.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -11190,12 +11200,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-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

@@ -795,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";
     }>>;
@@ -1501,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;
@@ -2664,8 +2671,18 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.34.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.36.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4986,6 +5003,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
@@ -7198,6 +7227,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. */
@@ -15949,12 +15985,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-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/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.34.0",
+  "version": "0.36.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",