@yaklabs-ai/plugin-protocol 0.35.0 → 0.36.0

package/README.md

@@ -11,7 +11,7 @@ flow.
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.35.0"
+    "@bonsai/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.36.0"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

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

package/dist/index.d.ts

@@ -1683,11 +1683,13 @@ declare namespace authoringContributionSchemas {
         ReferencePresentationUriPattern,
         ReferencePresentationUrlClaim,
         ReferencePresentationTooltip,
+        ReferencePresentationAddress,
         ReferencePresentationContribution,
         RichViewContribution,
         KayUiAppHostCapability,
         UiAppCapabilities,
         UiRailEntryContribution,
+        UiPageContribution,
         UiAppContribution,
         ThemeContribution,
         CommandHandler,
@@ -2665,9 +2667,34 @@ declare const canonicalContributionSchemas: {
             search: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
     }, z.core.$strict>;
+    ReferencePresentationAddress: 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>;
     ReferencePresentationContribution: z.ZodObject<{
         localId: z.ZodString;
-        uriModule: z.ZodString;
+        uriModule: z.ZodOptional<z.ZodString>;
+        scheme: z.ZodOptional<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">;
@@ -2714,6 +2741,7 @@ declare const canonicalContributionSchemas: {
         "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";
@@ -2733,6 +2761,7 @@ declare const canonicalContributionSchemas: {
             "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";
@@ -2770,6 +2799,13 @@ declare const canonicalContributionSchemas: {
             body: z.ZodString;
         }, z.core.$strict>>;
     }, z.core.$strict>;
+    UiPageContribution: z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        companion: z.ZodOptional<z.ZodBoolean>;
+        openedEvent: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
     UiAppContribution: z.ZodObject<{
         localId: z.ZodString;
         displayName: z.ZodString;
@@ -2793,6 +2829,7 @@ declare const canonicalContributionSchemas: {
                 "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";
@@ -2829,6 +2866,7 @@ declare const canonicalContributionSchemas: {
                 "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";
@@ -3193,6 +3231,17 @@ export declare interface DeclaredKayPluginCompatibility {
     readonly sdk?: string | undefined;
 }
 
+/**
+ * Every plugin's reference presentations. The daemon delivers this one kind from the resolved
+ * contract rather than the manifest, so its rows carry `schemes`.
+ */
+export declare function declaredReferencePresentations<TPlugin extends {
+    readonly contributes: Readonly<Record<string, unknown>>;
+}>(plugins: readonly TPlugin[]): readonly {
+    readonly plugin: TPlugin;
+    readonly declaration: ResolvedReferencePresentation;
+}[];
+
 export declare const DeclaredSkillSourceEnvelope: z.ZodDiscriminatedUnion<[z.ZodObject<{
     channel: z.ZodLiteral<"git-clone">;
     locator: z.ZodString;
@@ -4087,8 +4136,13 @@ export 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.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.35.0";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.36.0";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5576,7 +5630,20 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                     }, z.core.$strict>>>;
                     referencePresentations: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
-                        uriModule: z.ZodString;
+                        uriModule: z.ZodOptional<z.ZodString>;
+                        scheme: z.ZodOptional<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">;
@@ -5641,6 +5708,7 @@ export declare const KayPluginManifestV1: 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";
@@ -5677,6 +5745,7 @@ export declare const KayPluginManifestV1: 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";
@@ -5715,6 +5784,13 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                             body: z.ZodString;
                         }, z.core.$strict>>;
                     }, z.core.$strict>>>;
+                    pages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        title: z.ZodOptional<z.ZodString>;
+                        icon: z.ZodOptional<z.ZodString>;
+                        companion: z.ZodOptional<z.ZodBoolean>;
+                        openedEvent: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>>;
                     themes: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
                         displayName: z.ZodString;
@@ -6535,6 +6611,7 @@ export declare const KayUiAppHostCapability: z.ZodEnum<{
     "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";
@@ -6681,7 +6758,20 @@ export declare const KayUiTargetManifest: z.ZodObject<{
         }, z.core.$strict>>>;
         referencePresentations: z.ZodOptional<z.ZodArray<z.ZodObject<{
             localId: z.ZodString;
-            uriModule: z.ZodString;
+            uriModule: z.ZodOptional<z.ZodString>;
+            scheme: z.ZodOptional<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">;
@@ -6746,6 +6836,7 @@ export declare const KayUiTargetManifest: 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";
@@ -6782,6 +6873,7 @@ export declare const KayUiTargetManifest: 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";
@@ -6820,6 +6912,13 @@ export declare const KayUiTargetManifest: z.ZodObject<{
                 body: z.ZodString;
             }, z.core.$strict>>;
         }, z.core.$strict>>>;
+        pages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+            icon: z.ZodOptional<z.ZodString>;
+            companion: z.ZodOptional<z.ZodBoolean>;
+            openedEvent: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
         themes: z.ZodOptional<z.ZodArray<z.ZodObject<{
             localId: z.ZodString;
             displayName: z.ZodString;
@@ -10213,9 +10312,37 @@ export declare const ReferenceOpenBehavior: z.ZodDiscriminatedUnion<[z.ZodObject
 
 export declare type ReferenceOpenBehavior = z.infer<typeof ReferenceOpenBehavior>;
 
+export declare const ReferencePresentationAddress: 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>;
+
+export declare type ReferencePresentationAddress = z.infer<typeof ReferencePresentationAddress>;
+
 export declare const ReferencePresentationContribution: z.ZodObject<{
     localId: z.ZodString;
-    uriModule: z.ZodString;
+    uriModule: z.ZodOptional<z.ZodString>;
+    scheme: z.ZodOptional<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">;
@@ -10882,6 +11009,7 @@ export declare const ResolvedKayUiApp: 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";
@@ -12110,7 +12238,20 @@ export 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">;
@@ -12174,6 +12315,7 @@ export 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";
@@ -12576,7 +12718,20 @@ export declare type ResolvedPluginWebSession = z.infer<typeof ResolvedPluginWebS
 export declare const ResolvedReferencePresentation: 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">;
@@ -13761,6 +13916,7 @@ export declare const UiAppCapabilities: 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";
@@ -13800,6 +13956,7 @@ export declare const UiAppContribution: 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";
@@ -13836,6 +13993,7 @@ export declare const UiAppContribution: 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";
@@ -13877,6 +14035,16 @@ export declare const UiEventSubscriptionContribution: z.ZodObject<{
 
 export declare type UiEventSubscriptionContribution = z.infer<typeof UiEventSubscriptionContribution>;
 
+export declare const UiPageContribution: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    companion: z.ZodOptional<z.ZodBoolean>;
+    openedEvent: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+
+export declare type UiPageContribution = z.infer<typeof UiPageContribution>;
+
 export declare const UiRailEntryContribution: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;

package/dist/index.js

@@ -30,6 +30,7 @@ function declaredUiIconPaths(manifest) {
   const contributes = manifest.targets?.kay?.ui?.contributes;
   return [
     ...(contributes?.railEntries ?? []).flatMap((entry) => entry.icon === void 0 ? [] : [{ label: `kay.ui rail entry '${entry.id}' icon`, path: entry.icon }]),
+    ...(contributes?.pages ?? []).flatMap((page) => page.icon === void 0 ? [] : [{ label: `kay.ui page '${page.id}' icon`, path: page.icon }]),
     ...(contributes?.commands ?? []).flatMap((command) => command.icon === void 0 ? [] : [
       {
         label: `kay.ui command '${command.localId}' icon`,
@@ -253,7 +254,7 @@ var JsonSchema = z4.record(z4.string(), JsonValue);
 var KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES = 1024 * 1024;
 var KAY_PLUGIN_PROTOCOL_VERSION = "kay.plugin.v1";
 var KAY_PLUGIN_PROTOCOL_PACKAGE_NAME = "@bonsai/plugin-protocol";
-var KAY_PLUGIN_SDK_VERSION = "0.35.0";
+var KAY_PLUGIN_SDK_VERSION = "0.36.0";
 var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.26.3",
   "0.27.1",
@@ -263,7 +264,8 @@ var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.31.0",
   "0.32.0",
   "0.33.0",
-  "0.34.0"
+  "0.34.0",
+  "0.35.0"
 ];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
@@ -2736,6 +2738,7 @@ __export(contributions_exports, {
   PluginNotificationRuleContribution: () => PluginNotificationRuleContribution,
   PluginSkillSourceDeclaration: () => PluginSkillSourceDeclaration,
   ReferenceOpenBehavior: () => ReferenceOpenBehavior,
+  ReferencePresentationAddress: () => ReferencePresentationAddress,
   ReferencePresentationContribution: () => ReferencePresentationContribution,
   ReferencePresentationTooltip: () => ReferencePresentationTooltip,
   ReferencePresentationUriPattern: () => ReferencePresentationUriPattern,
@@ -2756,6 +2759,7 @@ __export(contributions_exports, {
   UiAppContribution: () => UiAppContribution,
   UiCommandContribution: () => UiCommandContribution,
   UiEventSubscriptionContribution: () => UiEventSubscriptionContribution,
+  UiPageContribution: () => UiPageContribution,
   UiRailEntryContribution: () => UiRailEntryContribution,
   UiSlotContribution: () => UiSlotContribution,
   UriModuleContribution: () => UriModuleContribution,
@@ -3012,6 +3016,9 @@ function declarationsOfKind(plugins, kind) {
     declaration
   })));
 }
+function declaredReferencePresentations(plugins) {
+  return plugins.flatMap((plugin) => (plugin.contributes["referencePresentations"] ?? []).map((declaration) => ({ plugin, declaration })));
+}
 function declaredCommandId(pluginId, localId) {
   return `${pluginId}/${localId}`;
 }
@@ -3647,9 +3654,9 @@ function createContributionsSchemas(canonical) {
     z12.strictObject({ kind: z12.literal("working-document") }),
     z12.strictObject({ kind: z12.literal("browser-pane") }),
     /**
-     * Open one of the presenting plugin's OWN registered pages (`registerPage`'s
-     * descriptor id) with the reference's canonical URI as the page's `objectId`.
-     * Needs no web address, so a plugin-only resource (`user-todo://items/3`) can pill.
+     * Open one of the pages this manifest declares in `pages`. The window answers this from the
+     * manifest, and the page gets the whole address as its `objectId` unless `addresses` says
+     * otherwise. Needs no web address, so a plugin-only resource (`user-todo://items/3`) can pill.
      */
     z12.strictObject({ kind: z12.literal("page"), pageId: NonEmptyString3 })
   ]);
@@ -3677,9 +3684,23 @@ function createContributionsSchemas(canonical) {
     app: LocalContributionId2,
     pattern: ReferencePresentationUriPattern2
   });
+  const ReferencePresentationAddress2 = z12.strictObject({
+    pattern: ReferencePresentationUriPattern2,
+    objectId: NonEmptyString3.optional(),
+    open: z12.strictObject({ kind: z12.literal("none") }).optional()
+  });
   const ReferencePresentationContribution2 = z12.strictObject({
     localId: LocalContributionId2,
-    uriModule: LocalContributionId2,
+    /** This manifest's URI module. Leave it out only for an address another layer serves. */
+    uriModule: LocalContributionId2.optional(),
+    /**
+     * The scheme this presentation opens, for an address with no module in this manifest. A
+     * module's own schemes are filled in for the window. Every address of the scheme with something
+     * after `://` opens the page, unless `addresses` narrows it.
+     */
+    scheme: UriScheme2.optional(),
+    /** Which of the addresses open the page, and on what. Read by the window. */
+    addresses: z12.array(ReferencePresentationAddress2).min(1).optional(),
     resourceKind: NonEmptyString3,
     open: ReferenceOpenBehavior2,
     /** MIME-specific resource kinds; absent keys use the base presentation. */
@@ -3696,6 +3717,38 @@ function createContributionsSchemas(canonical) {
         message: "URL claims require browser-pane opening."
       });
     }
+    if (value.uriModule === void 0 && value.scheme === void 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["uriModule"],
+        message: "A reference presentation names a uriModule or a scheme."
+      });
+    }
+    if ((value.scheme !== void 0 || value.addresses !== void 0) && value.open.kind !== "page") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["open"],
+        message: "scheme and addresses require page opening."
+      });
+    }
+    if (value.tooltip !== void 0 && value.open.kind === "page") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["tooltip"],
+        message: "A presentation that opens a page has no tooltip."
+      });
+    }
+    const protocols = [
+      ...value.scheme === void 0 ? [] : [value.scheme],
+      ...(value.addresses ?? []).map((row) => row.pattern.protocol)
+    ];
+    if (protocols.some((protocol) => /^https?:?$/iu.test(protocol))) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["addresses"],
+        message: "A web link never opens a page: use a plugin scheme."
+      });
+    }
   });
   const RichViewContribution2 = z12.strictObject({
     localId: LocalContributionId2,
@@ -3709,6 +3762,9 @@ function createContributionsSchemas(canonical) {
     "sessions.create",
     "artifacts.read",
     "artifacts.preview",
+    // Draws Bonsai's markdown document view in the app's page (`BonsaiMarkdownDocumentView`).
+    // It reads and saves nothing: the app supplies the text and keeps the edits.
+    "markdown.document-view",
     "cost.read",
     // Server-rated organization billing, distinct from local/provider cost.
     "billing.read",
@@ -3787,6 +3843,13 @@ function createContributionsSchemas(canonical) {
     badge: UiRailBadge.optional(),
     panel: z12.strictObject({ body: LocalContributionId2 }).optional()
   });
+  const UiPageContribution2 = z12.strictObject({
+    id: NonEmptyString3,
+    title: NonEmptyString3.optional(),
+    icon: PackageAssetPath2.optional(),
+    companion: z12.boolean().optional(),
+    openedEvent: NonEmptyString3.optional()
+  });
   const UiAppFields = z12.strictObject({
     localId: LocalContributionId2,
     displayName: NonEmptyString3,
@@ -3923,11 +3986,13 @@ function createContributionsSchemas(canonical) {
     ReferencePresentationUriPattern: ReferencePresentationUriPattern2,
     ReferencePresentationUrlClaim: ReferencePresentationUrlClaim2,
     ReferencePresentationTooltip: ReferencePresentationTooltip2,
+    ReferencePresentationAddress: ReferencePresentationAddress2,
     ReferencePresentationContribution: ReferencePresentationContribution2,
     RichViewContribution: RichViewContribution2,
     KayUiAppHostCapability: KayUiAppHostCapability2,
     UiAppCapabilities: UiAppCapabilities2,
     UiRailEntryContribution: UiRailEntryContribution2,
+    UiPageContribution: UiPageContribution2,
     UiAppContribution: UiAppContribution2,
     ThemeContribution: ThemeContribution2,
     CommandHandler: CommandHandler2,
@@ -3935,7 +4000,7 @@ function createContributionsSchemas(canonical) {
     PluginContributionKind: PluginContributionKind2
   };
 }
-var { ApprovalCardForm, ApprovalCardStoredForm, ApprovalTypeContribution, UriModuleFacts, ToolContribution, ToolPermission, AgentToolContribution, ConverterContribution, UriModuleContribution, AppUriModuleContribution, AppDataSourceContribution, WhiteboardTypeStorage, WhiteboardTypeContribution, AppDataMaterializerContribution, ArtifactUriModuleContribution, CliBindingContribution, GitHostContribution, ResourceContribution, SkillContribution, PluginSkillSourceDeclaration, SearchProviderContribution, InteractionDriverContribution, EntityResolverContribution, AgentRenderContribution, EndpointContribution, WorkflowContribution, McpServerUrl, McpServerAuthMode, McpServerContribution, McpServerContributions, AppEventSubscription, ContextContributorContribution, PluginEventDefinitionContribution, PluginNotificationRuleContribution, UiEventSubscriptionContribution, DeviceDelegationContribution, SessionReaderContribution, UiCommandContribution, UiSlotContribution, SettingsPanelContribution, ResultRendererContribution, ReferenceOpenBehavior, ReferencePresentationVariant, ReferencePresentationVariants, ReferencePresentationUriPattern, ReferencePresentationUrlClaim, ReferencePresentationTooltip, ReferencePresentationContribution, RichViewContribution, KayUiAppHostCapability, UiAppCapabilities, UiRailEntryContribution, UiAppContribution, ThemeContribution, CommandHandler, CommandContribution, PluginContributionKind } = createContributionsSchemas(false);
+var { ApprovalCardForm, ApprovalCardStoredForm, ApprovalTypeContribution, UriModuleFacts, ToolContribution, ToolPermission, AgentToolContribution, ConverterContribution, UriModuleContribution, AppUriModuleContribution, AppDataSourceContribution, WhiteboardTypeStorage, WhiteboardTypeContribution, AppDataMaterializerContribution, ArtifactUriModuleContribution, CliBindingContribution, GitHostContribution, ResourceContribution, SkillContribution, PluginSkillSourceDeclaration, SearchProviderContribution, InteractionDriverContribution, EntityResolverContribution, AgentRenderContribution, EndpointContribution, WorkflowContribution, McpServerUrl, McpServerAuthMode, McpServerContribution, McpServerContributions, AppEventSubscription, ContextContributorContribution, PluginEventDefinitionContribution, PluginNotificationRuleContribution, UiEventSubscriptionContribution, DeviceDelegationContribution, SessionReaderContribution, UiCommandContribution, UiSlotContribution, SettingsPanelContribution, ResultRendererContribution, ReferenceOpenBehavior, ReferencePresentationVariant, ReferencePresentationVariants, ReferencePresentationUriPattern, ReferencePresentationUrlClaim, ReferencePresentationTooltip, ReferencePresentationAddress, ReferencePresentationContribution, RichViewContribution, KayUiAppHostCapability, UiAppCapabilities, UiRailEntryContribution, UiPageContribution, UiAppContribution, ThemeContribution, CommandHandler, CommandContribution, PluginContributionKind } = createContributionsSchemas(false);
 var canonicalContributionSchemas = createContributionsSchemas(true);
 
 // packages/plugin-protocol/dist/icon-shape.js
@@ -4009,7 +4074,7 @@ var KAY_UI_NATIVE_EVENT_SUBSCRIPTIONS = [
 var KAY_UI_NATIVE_EVENT_ALLOWLIST = new Set(KAY_UI_NATIVE_EVENT_SUBSCRIPTIONS);
 var RETIRED_COMPATIBILITY_KEYS = ["policy"];
 function createManifestSchemas(canonical) {
-  const { AgentRenderContribution: AgentRenderContribution2, ApprovalTypeContribution: ApprovalTypeContribution2, WorkflowContribution: WorkflowContribution2, AppDataMaterializerContribution: AppDataMaterializerContribution2, AppDataSourceContribution: AppDataSourceContribution2, AppUriModuleContribution: AppUriModuleContribution2, AppEventSubscription: AppEventSubscription2, ArtifactUriModuleContribution: ArtifactUriModuleContribution2, CliBindingContribution: CliBindingContribution2, CommandContribution: CommandContribution2, ContextContributorContribution: ContextContributorContribution2, ConverterContribution: ConverterContribution2, SessionReaderContribution: SessionReaderContribution2, DeviceDelegationContribution: DeviceDelegationContribution2, EndpointContribution: EndpointContribution2, EntityResolverContribution: EntityResolverContribution2, GitHostContribution: GitHostContribution2, McpServerContributions: McpServerContributions2, PluginEventDefinitionContribution: PluginEventDefinitionContribution2, PluginNotificationRuleContribution: PluginNotificationRuleContribution2, ResourceContribution: ResourceContribution2, ReferencePresentationContribution: ReferencePresentationContribution2, ResultRendererContribution: ResultRendererContribution2, RichViewContribution: RichViewContribution2, PluginSkillSourceDeclaration: PluginSkillSourceDeclaration2, InteractionDriverContribution: InteractionDriverContribution2, SearchProviderContribution: SearchProviderContribution2, SkillContribution: SkillContribution2, SettingsPanelContribution: SettingsPanelContribution2, ThemeContribution: ThemeContribution2, AgentToolContribution: AgentToolContribution2, ToolContribution: ToolContribution2, UiCommandContribution: UiCommandContribution2, UiAppContribution: UiAppContribution2, UiRailEntryContribution: UiRailEntryContribution2, UiEventSubscriptionContribution: UiEventSubscriptionContribution2, UiSlotContribution: UiSlotContribution2, UriModuleContribution: UriModuleContribution2, WhiteboardTypeContribution: WhiteboardTypeContribution2 } = canonical ? canonicalContributionSchemas : contributions_exports;
+  const { AgentRenderContribution: AgentRenderContribution2, ApprovalTypeContribution: ApprovalTypeContribution2, WorkflowContribution: WorkflowContribution2, AppDataMaterializerContribution: AppDataMaterializerContribution2, AppDataSourceContribution: AppDataSourceContribution2, AppUriModuleContribution: AppUriModuleContribution2, AppEventSubscription: AppEventSubscription2, ArtifactUriModuleContribution: ArtifactUriModuleContribution2, CliBindingContribution: CliBindingContribution2, CommandContribution: CommandContribution2, ContextContributorContribution: ContextContributorContribution2, ConverterContribution: ConverterContribution2, SessionReaderContribution: SessionReaderContribution2, DeviceDelegationContribution: DeviceDelegationContribution2, EndpointContribution: EndpointContribution2, EntityResolverContribution: EntityResolverContribution2, GitHostContribution: GitHostContribution2, McpServerContributions: McpServerContributions2, PluginEventDefinitionContribution: PluginEventDefinitionContribution2, PluginNotificationRuleContribution: PluginNotificationRuleContribution2, ResourceContribution: ResourceContribution2, ReferencePresentationContribution: ReferencePresentationContribution2, ResultRendererContribution: ResultRendererContribution2, RichViewContribution: RichViewContribution2, PluginSkillSourceDeclaration: PluginSkillSourceDeclaration2, InteractionDriverContribution: InteractionDriverContribution2, SearchProviderContribution: SearchProviderContribution2, SkillContribution: SkillContribution2, SettingsPanelContribution: SettingsPanelContribution2, ThemeContribution: ThemeContribution2, AgentToolContribution: AgentToolContribution2, ToolContribution: ToolContribution2, UiCommandContribution: UiCommandContribution2, UiAppContribution: UiAppContribution2, UiRailEntryContribution: UiRailEntryContribution2, UiPageContribution: UiPageContribution2, UiEventSubscriptionContribution: UiEventSubscriptionContribution2, UiSlotContribution: UiSlotContribution2, UriModuleContribution: UriModuleContribution2, WhiteboardTypeContribution: WhiteboardTypeContribution2 } = canonical ? canonicalContributionSchemas : contributions_exports;
   const { HttpsUrl: HttpsUrl2, LocalContributionId: LocalContributionId2, NonEmptyString: NonEmptyString3, PackageAssetPath: PackageAssetPath2, PluginId: PluginId2, PluginNamespace: PluginNamespace2, RegistrableDomain: RegistrableDomain2, SignedInStatusCode: SignedInStatusCode2, TargetEntrypoint: TargetEntrypoint2 } = canonical ? canonicalCommonSchemas : common_exports;
   const { PluginPermissionManifest: PluginPermissionManifest2 } = canonical ? canonicalPermissionSchemas : permissions_exports;
   const KayAgentTargetManifest2 = z13.strictObject({
@@ -4132,6 +4197,7 @@ function createManifestSchemas(canonical) {
       views: z13.array(RichViewContribution2).optional(),
       apps: z13.array(UiAppContribution2).optional(),
       railEntries: z13.array(UiRailEntryContribution2).optional(),
+      pages: z13.array(UiPageContribution2).optional(),
       themes: z13.array(ThemeContribution2).optional(),
       eventSubscriptions: z13.array(UiEventSubscriptionContribution2).optional(),
       dataMaterializers: z13.array(AppDataMaterializerContribution2).optional()
@@ -4687,6 +4753,10 @@ function createManifestSchemas(canonical) {
       ...manifest.targets?.kay?.app?.contributes?.uriModules ?? []
     ].map((module) => module.localId));
     const presentationByUriModule = /* @__PURE__ */ new Map();
+    const declaredPageIds = /* @__PURE__ */ new Set([
+      ...(manifest.targets?.kay?.ui?.contributes?.pages ?? []).map((page) => page.id),
+      ...(manifest.targets?.kay?.ui?.contributes?.railEntries ?? []).map((entry) => entry.page)
+    ]);
     for (const [index, presentation] of (manifest.targets?.kay?.ui?.contributes?.referencePresentations ?? []).entries()) {
       const path = [
         "targets",
@@ -4696,7 +4766,7 @@ function createManifestSchemas(canonical) {
         "referencePresentations",
         index
       ];
-      if (!uriModuleIds.has(presentation.uriModule)) {
+      if (presentation.uriModule !== void 0 && !uriModuleIds.has(presentation.uriModule)) {
         ctx.addIssue({
           code: "custom",
           path: [...path, "uriModule"],
@@ -4710,6 +4780,15 @@ function createManifestSchemas(canonical) {
           message: `reference presentation ${presentation.localId} references unknown ui app ${presentation.tooltip.app}`
         });
       }
+      if (presentation.open.kind === "page" && !declaredPageIds.has(presentation.open.pageId)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [...path, "open", "pageId"],
+          message: `reference presentation ${presentation.localId} opens page ${presentation.open.pageId}, which this manifest declares in neither pages nor railEntries`
+        });
+      }
+      if (presentation.uriModule === void 0)
+        continue;
       const existing = presentationByUriModule.get(presentation.uriModule);
       if (existing !== void 0) {
         ctx.addIssue({
@@ -5400,7 +5479,7 @@ function boundPluginDiagnosticMessage(message) {
 import { z as z14 } from "zod";
 function createResolvedContractSchemas(canonical) {
   const { PluginEventLocalId: PluginEventLocalId2 } = canonical ? canonicalPluginEventSchemas : plugin_events_exports;
-  const { ApprovalTypeContribution: ApprovalTypeContribution2, KayUiAppHostCapability: KayUiAppHostCapability2, McpServerAuthMode: McpServerAuthMode2, McpServerUrl: McpServerUrl2, PluginContributionKind: PluginContributionKindSchema, ReferenceOpenBehavior: ReferenceOpenBehavior2, ReferencePresentationUriPattern: ReferencePresentationUriPattern2, ReferencePresentationUrlClaim: ReferencePresentationUrlClaim2, ReferencePresentationVariants: ReferencePresentationVariants2, UriModuleFacts: UriModuleFacts2, WhiteboardTypeStorage: WhiteboardTypeStorage2 } = canonical ? canonicalContributionSchemas : contributions_exports;
+  const { ApprovalTypeContribution: ApprovalTypeContribution2, KayUiAppHostCapability: KayUiAppHostCapability2, McpServerAuthMode: McpServerAuthMode2, McpServerUrl: McpServerUrl2, PluginContributionKind: PluginContributionKindSchema, ReferenceOpenBehavior: ReferenceOpenBehavior2, ReferencePresentationUriPattern: ReferencePresentationUriPattern2, ReferencePresentationAddress: ReferencePresentationAddress2, ReferencePresentationUrlClaim: ReferencePresentationUrlClaim2, ReferencePresentationVariants: ReferencePresentationVariants2, UriModuleFacts: UriModuleFacts2, WhiteboardTypeStorage: WhiteboardTypeStorage2 } = canonical ? canonicalContributionSchemas : contributions_exports;
   const { FileExtensionToken: FileExtensionToken2, GitBasicAuthUser: GitBasicAuthUser2, GitHostName: GitHostName2, GlobalContributionId: GlobalContributionId2, HttpsUrl: HttpsUrl2, LocalContributionId: LocalContributionId2, MimeTypeString: MimeTypeString2, NonEmptyString: NonEmptyString3, PackageAssetPath: PackageAssetPath2, PluginId: PluginId2, PluginNamespace: PluginNamespace2, PluginToolName: PluginToolName2, RegistrableDomain: RegistrableDomain2, SignedInStatusCode: SignedInStatusCode2, TargetEntrypoint: TargetEntrypoint2, UriScheme: UriScheme2 } = canonical ? canonicalCommonSchemas : common_exports;
   const { PluginExternalCliConnect: PluginExternalCliConnect2, PluginOAuthClientSupplier: PluginOAuthClientSupplier2 } = canonical ? canonicalManifestSchemas : manifest_exports;
   const { ResolvedPluginGrants: ResolvedPluginGrants2 } = canonical ? canonicalPermissionSchemas : permissions_exports;
@@ -5563,7 +5642,10 @@ function createResolvedContractSchemas(canonical) {
   const ResolvedReferencePresentation2 = z14.strictObject({
     localId: LocalContributionId2,
     globalId: GlobalContributionId2,
-    uriModule: GlobalContributionId2,
+    uriModule: GlobalContributionId2.optional(),
+    /** The schemes a page-opening presentation answers for: its `scheme`, or its module's. */
+    schemes: z14.array(UriScheme2).min(1).optional(),
+    addresses: z14.array(ReferencePresentationAddress2).min(1).optional(),
     resourceKind: NonEmptyString3,
     open: ReferenceOpenBehavior2,
     /** MIME-specific resource kinds; absent keys use the base presentation. */
@@ -6185,7 +6267,11 @@ function resolveKayPluginContractV1(manifest) {
   const referencePresentations = manifest.targets?.kay?.ui?.contributes?.referencePresentations?.map((presentation) => ({
     localId: presentation.localId,
     globalId: resolveGlobalContributionId(namespace, presentation.localId),
-    uriModule: resolveGlobalContributionId(namespace, presentation.uriModule),
+    ...presentation.uriModule === void 0 ? {} : {
+      uriModule: resolveGlobalContributionId(namespace, presentation.uriModule)
+    },
+    ...presentationSchemes(manifest, presentation),
+    ...presentation.addresses === void 0 ? {} : { addresses: presentation.addresses },
     resourceKind: presentation.resourceKind,
     open: presentation.open,
     ...presentation.tooltip === void 0 ? {} : {
@@ -6270,6 +6356,19 @@ function safeResolveKayPluginContractV1(manifest) {
     throw error;
   }
 }
+function presentationSchemes(manifest, presentation) {
+  if (presentation.scheme !== void 0) {
+    return { schemes: [presentation.scheme] };
+  }
+  if (presentation.open.kind !== "page")
+    return {};
+  const contributes = manifest.targets?.kay;
+  const module = [
+    ...contributes?.agent?.contributes?.uriModules ?? [],
+    ...contributes?.app?.contributes?.uriModules ?? []
+  ].find((candidate) => candidate.localId === presentation.uriModule);
+  return module === void 0 ? {} : { schemes: [...module.schemes] };
+}
 function uriModuleFacts({ localId: _localId, schemes: _schemes, displayName: _displayName, authService: _authService, authScheme: _authScheme, knownResources: _knownResources, describesOperations: _describesOperations, ...facts }) {
   return facts;
 }
@@ -7115,6 +7214,7 @@ export {
   RETIRED_PLUGIN_CAPABILITY_SLUGS,
   RETIRED_WEB_SESSION_ROW_KEYS,
   ReferenceOpenBehavior,
+  ReferencePresentationAddress,
   ReferencePresentationContribution,
   ReferencePresentationTooltip,
   ReferencePresentationUriPattern,
@@ -7182,6 +7282,7 @@ export {
   UiAppContribution,
   UiCommandContribution,
   UiEventSubscriptionContribution,
+  UiPageContribution,
   UiRailEntryContribution,
   UiSlotContribution,
   UriModuleContribution,
@@ -7214,6 +7315,7 @@ export {
   configSectionKeysForManifest,
   declarationsOfKind,
   declaredCommandId,
+  declaredReferencePresentations,
   declaredUiIconPaths,
   dedupeClaims,
   deriveDirectoryPluginToolName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-protocol",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "The Kay plugin manifest schema (`kay.plugin.v1`) — parse and validate a kay-plugin.json.",
   "author": "YakLabs",
   "type": "module",