@yaklabs-ai/plugin-sdk 0.52.1 → 0.53.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.52.1"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.53.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.52.1" },
+  "compatibility": { "sdk": "^0.53.0" },
   "targets": {
     "kay": {
       "agent": {
@@ -151,7 +151,7 @@ naming both versions, instead of loading it and finding no `activate`.
 | `@bonsai/plugin-sdk/system-one`         | The types and error class for `api.systemOne` / `app.systemOne`, from 0.13.8             |
 | `@bonsai/plugin-sdk/zod`                | `z` (the host's in the daemon), on an entry with no other import, from 0.13.9            |
 
-A plugin that imports these subpaths declares the current supported SDK range (`^0.52.1`).
+A plugin that imports these subpaths declares the current supported SDK range (`^0.53.0`).
 The rows record when each subpath appeared, not retained runtime compatibility. `vendored-mcp` builds the plugin's URI module (its link cards and help); hosting the
 vendor's MCP server itself is a separate host decision: Bonsai hosts it once a person approves
 the plugin's `mcp.host-server` grant for that server's name and URL. A server that needs an OAuth
@@ -159,7 +159,7 @@ sign-in names one of the plugin's auth services in `authService`; that service m
 one `delegated` scheme, which Bonsai uses to sign the person in to the server. Bonsai declares that
 scheme at runtime; the plugin's code must not declare it again. From 0.16.2 a plugin's code can also
 call the server's tools through `api.vendoredMcp.port(<server>)`, typed by this subpath's
-`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.52.1`).
+`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.53.0`).
 
 From 0.13.10 the manifest schema carries two facts Bonsai reads for its own plugins only; another
 plugin's are ignored, with a load diagnostic. An `external-cli` auth scheme's `cli` says how Bonsai
@@ -241,7 +241,7 @@ Provider schemas remain authoritative; declaring a dependency grants no authorit
 through `app.uri`, parse returned Markdown in the consuming plugin, and retain the read's
 revision (or `contentDigest` from `/uri`) for edits. The old `memory.read` and `memory.write`
 grants do not authorize the replacement scheme-and-verb calls. Contracts before 0.49.0 are
-refused; migrate and declare `^0.52.1`. The current host also serves the 0.49.0 resource contract.
+refused; migrate and declare `^0.53.0`. The current host also serves the 0.49.0 resource contract.
 
 ## What this package is, and is not, at runtime
 

package/THIRD-PARTY-INVENTORY.json

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

package/dist/artifact-provenance.d.ts

@@ -234,13 +234,13 @@ declare const ArtifactProvenanceCaptureContextSchema: z.ZodObject<{
     gaps: z.ZodArray<z.ZodObject<{
         code: z.ZodEnum<{
             unknown: "unknown";
+            truncated: "truncated";
             "capture-failed": "capture-failed";
             "legacy-derived": "legacy-derived";
             "ambiguous-predecessor": "ambiguous-predecessor";
             "unverified-index": "unverified-index";
             "missing-ancestor": "missing-ancestor";
             cycle: "cycle";
-            truncated: "truncated";
             "metadata-write-failed": "metadata-write-failed";
             "invalid-record": "invalid-record";
         }>;
@@ -584,13 +584,13 @@ export declare const ArtifactProvenanceEnvelopeV1: z.ZodPipe<z.ZodUnknown, z.Zod
     gaps: z.ZodArray<z.ZodObject<{
         code: z.ZodEnum<{
             unknown: "unknown";
+            truncated: "truncated";
             "capture-failed": "capture-failed";
             "legacy-derived": "legacy-derived";
             "ambiguous-predecessor": "ambiguous-predecessor";
             "unverified-index": "unverified-index";
             "missing-ancestor": "missing-ancestor";
             cycle: "cycle";
-            truncated: "truncated";
             "metadata-write-failed": "metadata-write-failed";
             "invalid-record": "invalid-record";
         }>;
@@ -604,13 +604,13 @@ export declare type ArtifactProvenanceEnvelopeV1 = z.infer<typeof ArtifactProven
 declare const ArtifactProvenanceGap: z.ZodObject<{
     code: z.ZodEnum<{
         unknown: "unknown";
+        truncated: "truncated";
         "capture-failed": "capture-failed";
         "legacy-derived": "legacy-derived";
         "ambiguous-predecessor": "ambiguous-predecessor";
         "unverified-index": "unverified-index";
         "missing-ancestor": "missing-ancestor";
         cycle: "cycle";
-        truncated: "truncated";
         "metadata-write-failed": "metadata-write-failed";
         "invalid-record": "invalid-record";
     }>;

package/dist/disclosure.d.ts

@@ -2462,8 +2462,12 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.52.0 adds plugin-owned operational facts through existing manifests and registrations.
  *
  * 0.52.1 adds owner-qualified page feed and endpoint references and their kay.ui claims.
+ *
+ * 0.53.0 adds declared working-content layouts, family-root authority, draft projection discovery
+ * and session-bound page references. Older customized Whiteboard copies must accept the plugin
+ * update before using these interfaces.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.52.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.53.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2509,9 +2513,9 @@ declare interface KayAgentEvents {
 /** This plugin's folder in the session family's shared Whiteboard. */
 declare interface KayAgentFamilyFolder {
     /**
-     * The folder's absolute path, created on first use. The plugin that owns the Whiteboard gets
-     * the whole family folder; every other plugin gets its own `plugins/<plugin-id>/` inside it.
-     * Undefined outside a session.
+     * Absolute path, created on first use; undefined outside a session. A declared and granted
+     * family-root owner receives the whole folder; other plugins receive `plugins/<plugin-id>/`.
+     * Root access checks the live `family-folder.root` grant on every call.
      */
     path(): Promise<string | undefined>;
 }
@@ -10498,8 +10502,8 @@ declare const WhiteboardEntryInfo: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -10520,8 +10524,8 @@ declare const WhiteboardEntryInspection: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -10572,6 +10576,9 @@ declare const WhiteboardTypeInfo: z.ZodObject<{
     displayName: z.ZodString;
     schemaVersion: z.ZodNumber;
     available: z.ZodBoolean;
+    reference: z.ZodOptional<z.ZodObject<{
+        uriTemplate: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;

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

@@ -2516,8 +2516,12 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.52.0 adds plugin-owned operational facts through existing manifests and registrations.
  *
  * 0.52.1 adds owner-qualified page feed and endpoint references and their kay.ui claims.
+ *
+ * 0.53.0 adds declared working-content layouts, family-root authority, draft projection discovery
+ * and session-bound page references. Older customized Whiteboard copies must accept the plugin
+ * update before using these interfaces.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.52.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.53.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2560,9 +2564,9 @@ declare interface KayAgentEvents {
 /** This plugin's folder in the session family's shared Whiteboard. */
 declare interface KayAgentFamilyFolder {
     /**
-     * The folder's absolute path, created on first use. The plugin that owns the Whiteboard gets
-     * the whole family folder; every other plugin gets its own `plugins/<plugin-id>/` inside it.
-     * Undefined outside a session.
+     * Absolute path, created on first use; undefined outside a session. A declared and granted
+     * family-root owner receives the whole folder; other plugins receive `plugins/<plugin-id>/`.
+     * Root access checks the live `family-folder.root` grant on every call.
      */
     path(): Promise<string | undefined>;
 }
@@ -5472,6 +5476,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>;
     }, z.core.$strict>>;
+    kayAgentFamilyFolder: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodLiteral<"root">;
+    }, z.core.$strict>>;
     kayAgentUriModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
         revisionBacked: z.ZodOptional<z.ZodLiteral<true>>;
         mailCalibrationSource: z.ZodOptional<z.ZodLiteral<true>>;
@@ -5935,6 +5942,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 schema: z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
             }, z.core.$strict>;
         }, z.core.$strict>>;
+        messageDraft: z.ZodOptional<z.ZodObject<{
+            schemes: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         store: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
             shape: z.ZodLiteral<"rows">;
             rowsField: z.ZodString;
@@ -5945,7 +5955,6 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
     }, z.core.$strict>>>;
     kayAppWhiteboardTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
         localId: z.ZodString;
-        globalId: z.ZodString;
         displayName: z.ZodString;
         schemaVersion: z.ZodNumber;
         storage: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -5957,6 +5966,12 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             bodyField: z.ZodString;
         }, z.core.$strict>], "kind">;
         valueSchema: z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
+        directory: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        reference: z.ZodOptional<z.ZodObject<{
+            uriTemplate: z.ZodString;
+        }, z.core.$strict>>;
+        handover: z.ZodOptional<z.ZodLiteral<true>>;
+        globalId: z.ZodString;
     }, z.core.$strict>>>;
     kayAppMcpServers: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -6013,6 +6028,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 search: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>;
             objectId: z.ZodOptional<z.ZodString>;
+            resourceKind: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
             open: z.ZodOptional<z.ZodObject<{
                 kind: z.ZodLiteral<"none">;
             }, z.core.$strict>>;
@@ -11847,8 +11864,8 @@ declare const WhiteboardEntryInfo: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -11869,8 +11886,8 @@ declare const WhiteboardEntryInspection: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -11921,6 +11938,9 @@ declare const WhiteboardTypeInfo: z.ZodObject<{
     displayName: z.ZodString;
     schemaVersion: z.ZodNumber;
     available: z.ZodBoolean;
+    reference: z.ZodOptional<z.ZodObject<{
+        uriTemplate: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;

package/dist/kay-agent.d.ts

@@ -2795,8 +2795,12 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.52.0 adds plugin-owned operational facts through existing manifests and registrations.
  *
  * 0.52.1 adds owner-qualified page feed and endpoint references and their kay.ui claims.
+ *
+ * 0.53.0 adds declared working-content layouts, family-root authority, draft projection discovery
+ * and session-bound page references. Older customized Whiteboard copies must accept the plugin
+ * update before using these interfaces.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.52.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.53.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2865,9 +2869,9 @@ export declare interface KayAgentEvents {
 /** This plugin's folder in the session family's shared Whiteboard. */
 export declare interface KayAgentFamilyFolder {
     /**
-     * The folder's absolute path, created on first use. The plugin that owns the Whiteboard gets
-     * the whole family folder; every other plugin gets its own `plugins/<plugin-id>/` inside it.
-     * Undefined outside a session.
+     * Absolute path, created on first use; undefined outside a session. A declared and granted
+     * family-root owner receives the whole folder; other plugins receive `plugins/<plugin-id>/`.
+     * Root access checks the live `family-folder.root` grant on every call.
      */
     path(): Promise<string | undefined>;
 }
@@ -5353,6 +5357,10 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
             command: z.ZodString;
             args: z.ZodArray<z.ZodString>;
         }, z.core.$strict>], "channel">;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.agent">;
+        slug: z.ZodLiteral<"family-folder.root">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodEnum<{
             "kay.agent": "kay.agent";
@@ -12084,8 +12092,8 @@ export declare const WhiteboardEntryInfo: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -12106,8 +12114,8 @@ export declare const WhiteboardEntryInspection: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -12158,6 +12166,9 @@ export declare const WhiteboardTypeInfo: z.ZodObject<{
     displayName: z.ZodString;
     schemaVersion: z.ZodNumber;
     available: z.ZodBoolean;
+    reference: z.ZodOptional<z.ZodObject<{
+        uriTemplate: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 export declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;

package/dist/kay-agent.js

@@ -192,6 +192,8 @@ function isLoneCapture(pattern) {
   return pattern.length === 1 && pattern[0].capture !== void 0 && pattern[0].rest !== true;
 }
 function matchParts(pattern, value, separator, captures, foldLiterals = false) {
+  if (pattern.length === 0)
+    return value === "";
   const parts = separator === void 0 ? [value] : value.split(separator);
   let partIndex = 0;
   for (let i = 0; i < pattern.length; i += 1) {

package/dist/kay-app.d.ts

@@ -2911,8 +2911,12 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.52.0 adds plugin-owned operational facts through existing manifests and registrations.
  *
  * 0.52.1 adds owner-qualified page feed and endpoint references and their kay.ui claims.
+ *
+ * 0.53.0 adds declared working-content layouts, family-root authority, draft projection discovery
+ * and session-bound page references. Older customized Whiteboard copies must accept the plugin
+ * update before using these interfaces.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.52.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.53.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -17301,8 +17305,8 @@ declare const WhiteboardEntryInfo: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -17323,8 +17327,8 @@ declare const WhiteboardEntryInspection: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -17375,6 +17379,9 @@ export declare const WhiteboardTypeInfo: z.ZodObject<{
     displayName: z.ZodString;
     schemaVersion: z.ZodNumber;
     available: z.ZodBoolean;
+    reference: z.ZodOptional<z.ZodObject<{
+        uriTemplate: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 export declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;

package/dist/vendored-mcp.js

@@ -263,6 +263,8 @@ function isLoneCapture(pattern) {
   return pattern.length === 1 && pattern[0].capture !== void 0 && pattern[0].rest !== true;
 }
 function matchParts(pattern, value, separator, captures, foldLiterals = false) {
+  if (pattern.length === 0)
+    return value === "";
   const parts = separator === void 0 ? [value] : value.split(separator);
   let partIndex = 0;
   for (let i = 0; i < pattern.length; i += 1) {

package/dist/whiteboard.d.ts

@@ -31,8 +31,8 @@ export declare const WhiteboardEntryInfo: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -53,8 +53,8 @@ export declare const WhiteboardEntryInspection: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        unavailable: "unavailable";
         available: "available";
+        unavailable: "unavailable";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -72,6 +72,9 @@ export declare const WhiteboardTypeInfo: z.ZodObject<{
     displayName: z.ZodString;
     schemaVersion: z.ZodNumber;
     available: z.ZodBoolean;
+    reference: z.ZodOptional<z.ZodObject<{
+        uriTemplate: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 export declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;

package/dist/whiteboard.js

@@ -122,6 +122,9 @@ var { NonEmptyString, PluginId, PluginNamespace, LocalContributionId, GlobalCont
 var canonicalCommonSchemas = createCommonSchemas(true);
 
 // packages/plugin-protocol/dist/whiteboard.js
+var WhiteboardEntryReference = z4.strictObject({
+  uriTemplate: z4.string().regex(/^[a-z][a-z0-9+.-]*:\/\/[^\s?#{}]+\/\{name\}$/u)
+});
 var WhiteboardValue = JsonValue;
 var WhiteboardEntryEnvelope = z4.strictObject({
   id: NonEmptyString,
@@ -160,7 +163,8 @@ var WhiteboardTypeInfo = z4.strictObject({
   typeId: GlobalContributionId,
   displayName: NonEmptyString,
   schemaVersion: z4.number().int().positive(),
-  available: z4.boolean()
+  available: z4.boolean(),
+  reference: WhiteboardEntryReference.optional()
 });
 export {
   JsonValue,

package/package.json

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