@yaklabs-ai/plugin-protocol 0.34.0 → 0.36.0

package/dist/index.js

@@ -9,12 +9,28 @@ var KAY_APP_DATA_SNAPSHOT_MAX_BYTES = 16 * 1024 * 1024;
 var KAY_APP_DATA_CHANGE_MAX_BYTES = 256 * 1024;
 var KAY_APP_DATA_READ_REQUEST_MAX_BYTES = 64 * 1024;
 var KAY_APP_DATA_READ_RESULT_MAX_BYTES = 16 * 1024 * 1024;
+function appDataSourceDeclaration(source) {
+  return {
+    sourceId: source.localId,
+    scope: source.scope,
+    snapshotVersion: source.snapshot.version,
+    changeVersion: source.change.version,
+    ...source.read === void 0 ? {} : {
+      read: {
+        requestVersion: source.read.request.version,
+        resultVersion: source.read.result.version
+      }
+    },
+    ...source.store === void 0 ? {} : { store: source.store }
+  };
+}
 
 // packages/plugin-protocol/dist/ui-icon-paths.js
 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`,
@@ -238,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.34.0";
+var KAY_PLUGIN_SDK_VERSION = "0.36.0";
 var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.26.3",
   "0.27.1",
@@ -247,7 +263,9 @@ var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.30.0",
   "0.31.0",
   "0.32.0",
-  "0.33.0"
+  "0.33.0",
+  "0.34.0",
+  "0.35.0"
 ];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
@@ -2720,6 +2738,7 @@ __export(contributions_exports, {
   PluginNotificationRuleContribution: () => PluginNotificationRuleContribution,
   PluginSkillSourceDeclaration: () => PluginSkillSourceDeclaration,
   ReferenceOpenBehavior: () => ReferenceOpenBehavior,
+  ReferencePresentationAddress: () => ReferencePresentationAddress,
   ReferencePresentationContribution: () => ReferencePresentationContribution,
   ReferencePresentationTooltip: () => ReferencePresentationTooltip,
   ReferencePresentationUriPattern: () => ReferencePresentationUriPattern,
@@ -2740,6 +2759,7 @@ __export(contributions_exports, {
   UiAppContribution: () => UiAppContribution,
   UiCommandContribution: () => UiCommandContribution,
   UiEventSubscriptionContribution: () => UiEventSubscriptionContribution,
+  UiPageContribution: () => UiPageContribution,
   UiRailEntryContribution: () => UiRailEntryContribution,
   UiSlotContribution: () => UiSlotContribution,
   UriModuleContribution: () => UriModuleContribution,
@@ -2833,20 +2853,7 @@ function createPluginEventsSchemas(canonical) {
 var { PluginEventLocalId, PluginEventUri, PluginEventTimestamp, PluginEventRelated, PluginEventPublishSource, PluginEventSource, PluginEventId, PluginEventPublishInput, PluginEventEnvelope } = createPluginEventsSchemas(false);
 var canonicalPluginEventSchemas = createPluginEventsSchemas(true);
 
-// packages/plugin-protocol/dist/declared-commands.js
-function declarationsOfKind(plugins, kind) {
-  return plugins.flatMap((plugin) => (plugin.contributes[kind] ?? []).map((declaration) => ({
-    plugin,
-    declaration
-  })));
-}
-function declaredCommandId(pluginId, localId) {
-  return `${pluginId}/${localId}`;
-}
-var WHERE_KEY_TYPES = {
-  "account.signedIn": "boolean",
-  "app.channel": "string"
-};
+// packages/plugin-protocol/dist/where-expression.js
 var TOKEN = /\s*(?:(\|\||&&|==|!=|!|\(|\))|'([^']*)'|"([^"]*)"|([A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*))/y;
 function tokenize(source) {
   const tokens = [];
@@ -2867,10 +2874,7 @@ function tokenize(source) {
   }
   return tokens;
 }
-function isKey(text) {
-  return Object.hasOwn(WHERE_KEY_TYPES, text);
-}
-function parseTokens(tokens) {
+function parseTokens(tokens, keyTypes) {
   let position = 0;
   const takeOperator = (text) => {
     const token = tokens[position];
@@ -2911,22 +2915,23 @@ function parseTokens(tokens) {
     }
     if (token.kind !== "word")
       throw new Error(`unexpected '${token.text}'`);
-    if (!isKey(token.text)) {
-      throw new Error(`unknown key '${token.text}'; the keys are ${Object.keys(WHERE_KEY_TYPES).join(", ")}`);
+    if (keyTypes !== void 0 && !Object.hasOwn(keyTypes, token.text)) {
+      throw new Error(`unknown key '${token.text}'; the keys are ${Object.keys(keyTypes).join(", ")}`);
     }
     return parseKeyAtom(token.text);
   };
   const parseKeyAtom = (key) => {
+    const keyType = keyTypes?.[key];
     const negated = takeOperator("!=");
     if (!negated && !takeOperator("==")) {
-      if (WHERE_KEY_TYPES[key] !== "boolean") {
+      if (keyType === "string") {
         throw new Error(`'${key}' must be compared, with == or !=`);
       }
       return { kind: "key", key };
     }
     const value = parseLiteral();
-    if (typeof value !== WHERE_KEY_TYPES[key]) {
-      throw new Error(`'${key}' compares to a ${WHERE_KEY_TYPES[key]}`);
+    if (keyType !== void 0 && typeof value !== keyType) {
+      throw new Error(`'${key}' compares to a ${keyType}`);
     }
     return { kind: "equals", key, value, negated };
   };
@@ -2947,49 +2952,85 @@ function parseTokens(tokens) {
     throw new Error(`unexpected '${extra.text}'`);
   return where;
 }
-function parseCommandWhere(source) {
+function parseWhere(source, keyTypes) {
   try {
-    return { ok: true, where: parseTokens(tokenize(source)) };
+    return { ok: true, where: parseTokens(tokenize(source), keyTypes) };
   } catch (error) {
     return { ok: false, message: error.message };
   }
 }
-function resolve(where, values) {
+function resolve(where, read) {
   switch (where.kind) {
     case "literal":
       return where.value;
     case "key": {
-      const value = values[where.key];
-      return value === void 0 ? void 0 : value === true;
+      const value = read(where.key);
+      return value === void 0 ? void 0 : Boolean(value);
     }
     case "equals": {
-      const value = values[where.key];
+      const value = read(where.key);
       if (value === void 0)
         return void 0;
       return value === where.value !== where.negated;
     }
     case "not": {
-      const operand = resolve(where.operand, values);
+      const operand = resolve(where.operand, read);
       return operand === void 0 ? void 0 : !operand;
     }
     case "and": {
-      const left = resolve(where.left, values);
-      const right = resolve(where.right, values);
+      const left = resolve(where.left, read);
+      const right = resolve(where.right, read);
       if (left === false || right === false)
         return false;
       return left === void 0 || right === void 0 ? void 0 : true;
     }
     case "or": {
-      const left = resolve(where.left, values);
-      const right = resolve(where.right, values);
+      const left = resolve(where.left, read);
+      const right = resolve(where.right, read);
       if (left === true || right === true)
         return true;
       return left === void 0 || right === void 0 ? void 0 : false;
     }
   }
 }
+function evaluateWhere(where, read) {
+  return resolve(where, read) === true;
+}
+function rowMatchesWhere(where, row) {
+  return evaluateWhere(where, (path) => {
+    let value = row;
+    for (const part of path.split(".")) {
+      if (typeof value !== "object" || value === null || !Object.hasOwn(value, part)) {
+        return null;
+      }
+      value = value[part];
+    }
+    return value ?? null;
+  });
+}
+
+// packages/plugin-protocol/dist/declared-commands.js
+function declarationsOfKind(plugins, kind) {
+  return plugins.flatMap((plugin) => (plugin.contributes[kind] ?? []).map((declaration) => ({
+    plugin,
+    declaration
+  })));
+}
+function declaredReferencePresentations(plugins) {
+  return plugins.flatMap((plugin) => (plugin.contributes["referencePresentations"] ?? []).map((declaration) => ({ plugin, declaration })));
+}
+function declaredCommandId(pluginId, localId) {
+  return `${pluginId}/${localId}`;
+}
+var WHERE_KEY_TYPES = {
+  "account.signedIn": "boolean",
+  "app.channel": "string"
+};
+function parseCommandWhere(source) {
+  return parseWhere(source, WHERE_KEY_TYPES);
+}
 function evaluateCommandWhere(where, values) {
-  return resolve(where, values) === true;
+  return evaluateWhere(where, (key) => values[key]);
 }
 
 // packages/plugin-protocol/dist/contributions.js
@@ -3613,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 })
   ]);
@@ -3643,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. */
@@ -3662,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,
@@ -3675,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",
@@ -3722,6 +3812,25 @@ function createContributionsSchemas(canonical) {
       }
     }
   });
+  const UiRailBadge = z12.strictObject({
+    source: LocalContributionId2,
+    where: NonEmptyString3.optional(),
+    label: z12.strictObject({
+      one: NonEmptyString3.optional(),
+      other: NonEmptyString3
+    })
+  }).superRefine((badge, ctx) => {
+    if (badge.where === void 0)
+      return;
+    const parsed = parseWhere(badge.where);
+    if (!parsed.ok) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["where"],
+        message: `rail badge has an invalid where: ${parsed.message}`
+      });
+    }
+  });
   const UiRailEntryContribution2 = z12.strictObject({
     id: LocalContributionId2,
     title: NonEmptyString3,
@@ -3731,8 +3840,16 @@ function createContributionsSchemas(canonical) {
     shortcut: NonEmptyString3.optional(),
     order: z12.number().finite().optional(),
     section: z12.enum(["primary", "plugins"]).optional(),
+    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,
@@ -3869,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,
@@ -3881,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
@@ -3955,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({
@@ -4078,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()
@@ -4549,6 +4669,34 @@ function createManifestSchemas(canonical) {
       }
       materializedAppDataSources.add(materializer.source);
     }
+    const declaredRowsStores = new Set(manifest.targets?.kay?.app?.contributes?.dataSources?.filter((source) => source.store?.shape === "rows").map((source) => source.localId) ?? []);
+    for (const [index, entry] of (manifest.targets?.kay?.ui?.contributes?.railEntries ?? []).entries()) {
+      if (entry.badge === void 0)
+        continue;
+      const path = [
+        "targets",
+        "kay",
+        "ui",
+        "contributes",
+        "railEntries",
+        index,
+        "badge"
+      ];
+      if (!declaredRowsStores.has(entry.badge.source)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [...path, "source"],
+          message: `rail entry ${entry.id} counts ${entry.badge.source}, which is not one of this plugin's data sources with a rows store`
+        });
+      }
+      if (manifest.targets?.kay?.ui?.entrypoint === void 0) {
+        ctx.addIssue({
+          code: "custom",
+          path,
+          message: `rail entry ${entry.id} declares a badge, so its plugin needs a kay.ui entrypoint: the window starts a plugin's data sources when it loads that code`
+        });
+      }
+    }
     for (const source of declaredAppDataSources) {
       if (materializedAppDataSources.has(source) || declaredAppDataStores.has(source))
         continue;
@@ -4605,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",
@@ -4614,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"],
@@ -4628,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({
@@ -5318,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;
@@ -5481,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. */
@@ -6103,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 ? {} : {
@@ -6188,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;
 }
@@ -7033,6 +7214,7 @@ export {
   RETIRED_PLUGIN_CAPABILITY_SLUGS,
   RETIRED_WEB_SESSION_ROW_KEYS,
   ReferenceOpenBehavior,
+  ReferencePresentationAddress,
   ReferencePresentationContribution,
   ReferencePresentationTooltip,
   ReferencePresentationUriPattern,
@@ -7100,6 +7282,7 @@ export {
   UiAppContribution,
   UiCommandContribution,
   UiEventSubscriptionContribution,
+  UiPageContribution,
   UiRailEntryContribution,
   UiSlotContribution,
   UriModuleContribution,
@@ -7121,6 +7304,7 @@ export {
   WhiteboardTypeStorage,
   WhiteboardValue,
   WorkflowContribution,
+  appDataSourceDeclaration,
   approvalKindSchema,
   boundPluginDiagnosticMessage,
   captureArtifactProvenance,
@@ -7131,10 +7315,12 @@ export {
   configSectionKeysForManifest,
   declarationsOfKind,
   declaredCommandId,
+  declaredReferencePresentations,
   declaredUiIconPaths,
   dedupeClaims,
   deriveDirectoryPluginToolName,
   evaluateCommandWhere,
+  evaluateWhere,
   finalizeArtifactProvenanceEnvelope,
   findSkillSuggestionCitations,
   hasClaim,
@@ -7162,6 +7348,7 @@ export {
   parseKayUiBundleIndexV1,
   parseResolvedPluginContractV1,
   parseSemver,
+  parseWhere,
   pluginIconShape,
   precedingPersonMessages,
   readKayPluginDeclaredCompatibility,
@@ -7174,6 +7361,7 @@ export {
   resolveSessionAncestry,
   retiredCompatibilityKeysIn,
   retiredPermissionAsksIn,
+  rowMatchesWhere,
   safeResolveKayPluginContractV1,
   sameClaim,
   satisfiesSemverRange,

package/package.json

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