@yaklabs-ai/plugin-protocol 0.31.0 → 0.33.0

package/README.md

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

package/THIRD-PARTY-INVENTORY.json

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

package/dist/index.d.ts

@@ -106,6 +106,13 @@ export declare const AppDataSourceContribution: z.ZodObject<{
             schema: z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
         }, z.core.$strict>;
     }, z.core.$strict>>;
+    store: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        shape: z.ZodLiteral<"rows">;
+        rowsField: z.ZodString;
+        key: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        shape: z.ZodLiteral<"value">;
+    }, z.core.$strict>], "shape">>;
 }, z.core.$strict>;
 
 export declare type AppDataSourceContribution = z.infer<typeof AppDataSourceContribution>;
@@ -2365,6 +2372,13 @@ declare const canonicalContributionSchemas: {
                 schema: z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
             }, z.core.$strict>;
         }, z.core.$strict>>;
+        store: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            shape: z.ZodLiteral<"rows">;
+            rowsField: z.ZodString;
+            key: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            shape: z.ZodLiteral<"value">;
+        }, z.core.$strict>], "shape">>;
     }, z.core.$strict>;
     WhiteboardTypeStorage: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"json">;
@@ -2566,7 +2580,13 @@ declare const canonicalContributionSchemas: {
         localId: z.ZodString;
         title: z.ZodString;
         icon: z.ZodOptional<z.ZodString>;
-        placement: z.ZodOptional<z.ZodString>;
+        button: z.ZodOptional<z.ZodEnum<{
+            tabStrip: "tabStrip";
+        }>>;
+        menu: z.ZodOptional<z.ZodEnum<{
+            help: "help";
+        }>>;
+        where: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     UiSlotContribution: z.ZodObject<{
         localId: z.ZodString;
@@ -2680,8 +2700,6 @@ declare const canonicalContributionSchemas: {
         "artifacts.preview": "artifacts.preview";
         "cost.read": "cost.read";
         "billing.read": "billing.read";
-        "context.read": "context.read";
-        "usage.read": "usage.read";
         "self-improvement.read": "self-improvement.read";
         "automations.read": "automations.read";
         "shared-artifacts.read": "shared-artifacts.read";
@@ -2701,8 +2719,6 @@ declare const canonicalContributionSchemas: {
             "artifacts.preview": "artifacts.preview";
             "cost.read": "cost.read";
             "billing.read": "billing.read";
-            "context.read": "context.read";
-            "usage.read": "usage.read";
             "self-improvement.read": "self-improvement.read";
             "automations.read": "automations.read";
             "shared-artifacts.read": "shared-artifacts.read";
@@ -2752,8 +2768,6 @@ declare const canonicalContributionSchemas: {
                 "artifacts.preview": "artifacts.preview";
                 "cost.read": "cost.read";
                 "billing.read": "billing.read";
-                "context.read": "context.read";
-                "usage.read": "usage.read";
                 "self-improvement.read": "self-improvement.read";
                 "automations.read": "automations.read";
                 "shared-artifacts.read": "shared-artifacts.read";
@@ -2790,8 +2804,6 @@ declare const canonicalContributionSchemas: {
                 "artifacts.preview": "artifacts.preview";
                 "cost.read": "cost.read";
                 "billing.read": "billing.read";
-                "context.read": "context.read";
-                "usage.read": "usage.read";
                 "self-improvement.read": "self-improvement.read";
                 "automations.read": "automations.read";
                 "shared-artifacts.read": "shared-artifacts.read";
@@ -2985,6 +2997,41 @@ export declare const CommandHandler: z.ZodDiscriminatedUnion<[z.ZodObject<{
 
 export declare type CommandHandler = z.infer<typeof CommandHandler>;
 
+export declare type CommandWhere = {
+    readonly kind: "literal";
+    readonly value: boolean;
+} | {
+    readonly kind: "key";
+    readonly key: CommandWhereKey;
+} | {
+    readonly kind: "equals";
+    readonly key: CommandWhereKey;
+    readonly value: boolean | string;
+    readonly negated: boolean;
+} | {
+    readonly kind: "not";
+    readonly operand: CommandWhere;
+} | {
+    readonly kind: "and" | "or";
+    readonly left: CommandWhere;
+    readonly right: CommandWhere;
+};
+
+export declare type CommandWhereKey = keyof typeof WHERE_KEY_TYPES;
+
+export declare type CommandWhereParseResult = {
+    readonly ok: true;
+    readonly where: CommandWhere;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+
+/** The values a `where` reads. A key left out isn't known yet, for example while it loads. */
+export declare type CommandWhereValues = {
+    readonly [K in CommandWhereKey]?: (typeof WHERE_KEY_TYPES)[K] extends "boolean" ? boolean : string;
+};
+
 /**
  * Total order over claims, for deterministic projection and diffs. Compares the same fields
  * {@link sameClaim} compares, in a fixed order, so two claims that compare equal here are the same
@@ -3114,6 +3161,25 @@ export declare const CorpusResourceKind: z.ZodEnum<{
 
 export declare type CorpusResourceKind = z.infer<typeof CorpusResourceKind>;
 
+/**
+ * Every plugin's declarations of one kind, each with the plugin that made it. Main and the window
+ * each hold the plugins' `kay.ui` facts, and both read them through here. `contributes` crosses the
+ * daemon, the protocol and main unread, so this is where it gets its type back.
+ */
+export declare function declarationsOfKind<TPlugin extends {
+    readonly contributes: Readonly<Record<string, unknown>>;
+}, K extends keyof UiContributes>(plugins: readonly TPlugin[], kind: K): readonly {
+    readonly plugin: TPlugin;
+    readonly declaration: NonNullable<UiContributes[K]>[number];
+}[];
+
+/**
+ * A declared command's full id. Neither part can contain `/`, so two plugins can't produce the same
+ * one, and none can name an app command such as `session.interrupt`, which a plugin called `session`
+ * could otherwise put a button on without implementing it.
+ */
+export declare function declaredCommandId(pluginId: string, localId: string): string;
+
 /**
  * The `compatibility` block as the check reads it. Structural rather than the parsed
  * `PluginCompatibilityManifest`, so a host can judge the block of a manifest whose other fields
@@ -3213,6 +3279,13 @@ export declare const EntityResolverContribution: z.ZodObject<{
 
 export declare type EntityResolverContribution = z.infer<typeof EntityResolverContribution>;
 
+/**
+ * Whether a `where` holds. When the answer depends on a value not known yet the result is false,
+ * so a button stays hidden while a value loads rather than flashing on: `true || app.channel == 'x'`
+ * holds whatever the channel is, and `!(app.channel == 'x')` waits for it.
+ */
+export declare function evaluateCommandWhere(where: CommandWhere, values: CommandWhereValues): boolean;
+
 export declare const EventGrantRequest: z.ZodObject<{
     event: z.ZodString;
     operations: z.ZodArray<z.ZodEnum<{
@@ -3991,8 +4064,17 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * `contributes` names each entry's title, page, shortcut and icon file. It replaces `activityRail` on a
  * UI app, which is stripped from a manifest that still carries it, so that manifest loses only the
  * rail button. A plugin that declares a rail entry declares ^0.31.0.
+ *
+ * 0.32.0 lets an app-data source declare its window store as data (#15891). `store` under
+ * `contributes.dataSources` replaces a `kay.ui` data materializer, and a change too big for a live
+ * update becomes a re-read of the snapshot. A plugin that declares a store declares ^0.32.0.
+ *
+ * 0.33.0 lets a plugin declare a window command with its button and menu item (#15903). `commands`
+ * under `kay.ui` `contributes` names each command's title, icon file, `button`, `menu` and `where`,
+ * and `api.implementCommand(localId, handler)` supplies what it does. `placement` is gone and `icon`
+ * is now a file path: nothing ever read either. A plugin that declares a command declares ^0.33.0.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.31.0";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.33.0";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4491,6 +4573,13 @@ export declare const KayAppTargetManifest: z.ZodObject<{
                     schema: z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
                 }, z.core.$strict>;
             }, z.core.$strict>>;
+            store: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                shape: z.ZodLiteral<"rows">;
+                rowsField: z.ZodString;
+                key: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                shape: z.ZodLiteral<"value">;
+            }, z.core.$strict>], "shape">>;
         }, z.core.$strict>>>;
         whiteboardTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
             localId: z.ZodString;
@@ -5255,6 +5344,13 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                                 schema: z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
                             }, z.core.$strict>;
                         }, z.core.$strict>>;
+                        store: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                            shape: z.ZodLiteral<"rows">;
+                            rowsField: z.ZodString;
+                            key: z.ZodArray<z.ZodString>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            shape: z.ZodLiteral<"value">;
+                        }, z.core.$strict>], "shape">>;
                     }, z.core.$strict>>>;
                     whiteboardTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
@@ -5442,7 +5538,13 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                         localId: z.ZodString;
                         title: z.ZodString;
                         icon: z.ZodOptional<z.ZodString>;
-                        placement: z.ZodOptional<z.ZodString>;
+                        button: z.ZodOptional<z.ZodEnum<{
+                            tabStrip: "tabStrip";
+                        }>>;
+                        menu: z.ZodOptional<z.ZodEnum<{
+                            help: "help";
+                        }>>;
+                        where: z.ZodOptional<z.ZodString>;
                     }, z.core.$strict>>>;
                     slots: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
@@ -5530,8 +5632,6 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                                 "artifacts.preview": "artifacts.preview";
                                 "cost.read": "cost.read";
                                 "billing.read": "billing.read";
-                                "context.read": "context.read";
-                                "usage.read": "usage.read";
                                 "self-improvement.read": "self-improvement.read";
                                 "automations.read": "automations.read";
                                 "shared-artifacts.read": "shared-artifacts.read";
@@ -5568,8 +5668,6 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                                 "artifacts.preview": "artifacts.preview";
                                 "cost.read": "cost.read";
                                 "billing.read": "billing.read";
-                                "context.read": "context.read";
-                                "usage.read": "usage.read";
                                 "self-improvement.read": "self-improvement.read";
                                 "automations.read": "automations.read";
                                 "shared-artifacts.read": "shared-artifacts.read";
@@ -6417,8 +6515,6 @@ export declare const KayUiAppHostCapability: z.ZodEnum<{
     "artifacts.preview": "artifacts.preview";
     "cost.read": "cost.read";
     "billing.read": "billing.read";
-    "context.read": "context.read";
-    "usage.read": "usage.read";
     "self-improvement.read": "self-improvement.read";
     "automations.read": "automations.read";
     "shared-artifacts.read": "shared-artifacts.read";
@@ -6536,7 +6632,13 @@ export declare const KayUiTargetManifest: z.ZodObject<{
             localId: z.ZodString;
             title: z.ZodString;
             icon: z.ZodOptional<z.ZodString>;
-            placement: z.ZodOptional<z.ZodString>;
+            button: z.ZodOptional<z.ZodEnum<{
+                tabStrip: "tabStrip";
+            }>>;
+            menu: z.ZodOptional<z.ZodEnum<{
+                help: "help";
+            }>>;
+            where: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         slots: z.ZodOptional<z.ZodArray<z.ZodObject<{
             localId: z.ZodString;
@@ -6624,8 +6726,6 @@ export declare const KayUiTargetManifest: z.ZodObject<{
                     "artifacts.preview": "artifacts.preview";
                     "cost.read": "cost.read";
                     "billing.read": "billing.read";
-                    "context.read": "context.read";
-                    "usage.read": "usage.read";
                     "self-improvement.read": "self-improvement.read";
                     "automations.read": "automations.read";
                     "shared-artifacts.read": "shared-artifacts.read";
@@ -6662,8 +6762,6 @@ export declare const KayUiTargetManifest: z.ZodObject<{
                     "artifacts.preview": "artifacts.preview";
                     "cost.read": "cost.read";
                     "billing.read": "billing.read";
-                    "context.read": "context.read";
-                    "usage.read": "usage.read";
                     "self-improvement.read": "self-improvement.read";
                     "automations.read": "automations.read";
                     "shared-artifacts.read": "shared-artifacts.read";
@@ -6854,6 +6952,12 @@ export declare function parseArtifactProvenanceCaptureContext(input: unknown): A
 /** Returns an owned value snapshot; callers must not attach live session references. */
 export declare function parseArtifactProvenanceEnvelope(input: unknown): ArtifactProvenanceEnvelopeV1;
 
+/**
+ * Parses a declared command's `where`: `||`, `&&`, `!`, parentheses, `==`, `!=`, strings, `true`,
+ * `false` and dotted keys, for example `account.signedIn || app.channel != 'production'`.
+ */
+export declare function parseCommandWhere(source: string): CommandWhereParseResult;
+
 /** A `MAJOR.MINOR.PATCH` version broken into its comparable parts. */
 export declare interface ParsedSemver {
     readonly major: number;
@@ -10639,6 +10743,13 @@ export declare const ResolvedKayAppDataSource: z.ZodObject<{
             schema: z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
         }, z.core.$strict>;
     }, z.core.$strict>>;
+    store: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        shape: z.ZodLiteral<"rows">;
+        rowsField: z.ZodString;
+        key: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        shape: z.ZodLiteral<"value">;
+    }, z.core.$strict>], "shape">>;
 }, z.core.$strict>;
 
 export declare type ResolvedKayAppDataSource = z.infer<typeof ResolvedKayAppDataSource>;
@@ -10733,8 +10844,6 @@ export declare const ResolvedKayUiApp: z.ZodObject<{
             "artifacts.preview": "artifacts.preview";
             "cost.read": "cost.read";
             "billing.read": "billing.read";
-            "context.read": "context.read";
-            "usage.read": "usage.read";
             "self-improvement.read": "self-improvement.read";
             "automations.read": "automations.read";
             "shared-artifacts.read": "shared-artifacts.read";
@@ -11911,6 +12020,13 @@ export 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>>;
+        store: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            shape: z.ZodLiteral<"rows">;
+            rowsField: z.ZodString;
+            key: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            shape: z.ZodLiteral<"value">;
+        }, z.core.$strict>], "shape">>;
     }, z.core.$strict>>>;
     kayAppWhiteboardTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
         localId: z.ZodString;
@@ -12020,8 +12136,6 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
                 "artifacts.preview": "artifacts.preview";
                 "cost.read": "cost.read";
                 "billing.read": "billing.read";
-                "context.read": "context.read";
-                "usage.read": "usage.read";
                 "self-improvement.read": "self-improvement.read";
                 "automations.read": "automations.read";
                 "shared-artifacts.read": "shared-artifacts.read";
@@ -13606,8 +13720,6 @@ export declare const UiAppCapabilities: z.ZodObject<{
         "artifacts.preview": "artifacts.preview";
         "cost.read": "cost.read";
         "billing.read": "billing.read";
-        "context.read": "context.read";
-        "usage.read": "usage.read";
         "self-improvement.read": "self-improvement.read";
         "automations.read": "automations.read";
         "shared-artifacts.read": "shared-artifacts.read";
@@ -13647,8 +13759,6 @@ export declare const UiAppContribution: z.ZodObject<{
             "artifacts.preview": "artifacts.preview";
             "cost.read": "cost.read";
             "billing.read": "billing.read";
-            "context.read": "context.read";
-            "usage.read": "usage.read";
             "self-improvement.read": "self-improvement.read";
             "automations.read": "automations.read";
             "shared-artifacts.read": "shared-artifacts.read";
@@ -13685,8 +13795,6 @@ export declare const UiAppContribution: z.ZodObject<{
             "artifacts.preview": "artifacts.preview";
             "cost.read": "cost.read";
             "billing.read": "billing.read";
-            "context.read": "context.read";
-            "usage.read": "usage.read";
             "self-improvement.read": "self-improvement.read";
             "automations.read": "automations.read";
             "shared-artifacts.read": "shared-artifacts.read";
@@ -13703,11 +13811,19 @@ export declare const UiCommandContribution: z.ZodObject<{
     localId: z.ZodString;
     title: z.ZodString;
     icon: z.ZodOptional<z.ZodString>;
-    placement: z.ZodOptional<z.ZodString>;
+    button: z.ZodOptional<z.ZodEnum<{
+        tabStrip: "tabStrip";
+    }>>;
+    menu: z.ZodOptional<z.ZodEnum<{
+        help: "help";
+    }>>;
+    where: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 
 export declare type UiCommandContribution = z.infer<typeof UiCommandContribution>;
 
+declare type UiContributes = NonNullable<KayUiTargetManifest["contributes"]>;
+
 export declare const UiEventSubscriptionContribution: z.ZodObject<{
     localId: z.ZodString;
     event: z.ZodString;
@@ -14128,6 +14244,12 @@ export declare type WebSessionGrantRequest = z.infer<typeof WebSessionGrantReque
  */
 export declare function webSessionPathWithinPrefix(pathname: string, pathPrefix: string): boolean;
 
+/** What a `where` expression can read, and the type of each. */
+declare const WHERE_KEY_TYPES: {
+    readonly "account.signedIn": "boolean";
+    readonly "app.channel": "string";
+};
+
 /** Construct the exact claim row for one Whiteboard scope and operation. */
 export declare function whiteboardCapabilityClaim(operation: WhiteboardCapabilityOperation, scope: WhiteboardCapabilityScope, target?: "kay.agent"): WhiteboardCapabilityClaimV1;
 

package/dist/index.js

@@ -13,7 +13,15 @@ var KAY_APP_DATA_READ_RESULT_MAX_BYTES = 16 * 1024 * 1024;
 // 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 }]);
+  return [
+    ...(contributes?.railEntries ?? []).flatMap((entry) => entry.icon === void 0 ? [] : [{ label: `kay.ui rail entry '${entry.id}' icon`, path: entry.icon }]),
+    ...(contributes?.commands ?? []).flatMap((command) => command.icon === void 0 ? [] : [
+      {
+        label: `kay.ui command '${command.localId}' icon`,
+        path: command.icon
+      }
+    ])
+  ];
 }
 
 // packages/plugin-protocol/dist/approval-types.js
@@ -230,13 +238,15 @@ 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.31.0";
+var KAY_PLUGIN_SDK_VERSION = "0.33.0";
 var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.26.3",
   "0.27.1",
   "0.28.0",
   "0.29.0",
-  "0.30.0"
+  "0.30.0",
+  "0.31.0",
+  "0.32.0"
 ];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
@@ -2822,6 +2832,165 @@ 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"
+};
+var TOKEN = /\s*(?:(\|\||&&|==|!=|!|\(|\))|'([^']*)'|"([^"]*)"|([A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*))/y;
+function tokenize(source) {
+  const tokens = [];
+  TOKEN.lastIndex = 0;
+  while (source.slice(TOKEN.lastIndex).trim() !== "") {
+    const start = TOKEN.lastIndex;
+    const match = TOKEN.exec(source);
+    if (match === null) {
+      throw new Error(`unexpected text at '${source.slice(start).trim()}'`);
+    }
+    const [, operator, single, double, word] = match;
+    if (operator !== void 0)
+      tokens.push({ kind: "operator", text: operator });
+    else if (word !== void 0)
+      tokens.push({ kind: "word", text: word });
+    else
+      tokens.push({ kind: "string", text: single ?? double ?? "" });
+  }
+  return tokens;
+}
+function isKey(text) {
+  return Object.hasOwn(WHERE_KEY_TYPES, text);
+}
+function parseTokens(tokens) {
+  let position = 0;
+  const takeOperator = (text) => {
+    const token = tokens[position];
+    if (token?.kind !== "operator" || token.text !== text)
+      return false;
+    position += 1;
+    return true;
+  };
+  const parseOr = () => {
+    let left = parseAnd();
+    while (takeOperator("||"))
+      left = { kind: "or", left, right: parseAnd() };
+    return left;
+  };
+  const parseAnd = () => {
+    let left = parseNot();
+    while (takeOperator("&&"))
+      left = { kind: "and", left, right: parseNot() };
+    return left;
+  };
+  const parseNot = () => takeOperator("!") ? { kind: "not", operand: parseNot() } : parseAtom();
+  const parseAtom = () => {
+    if (takeOperator("(")) {
+      const inner = parseOr();
+      if (!takeOperator(")"))
+        throw new Error("missing ')'");
+      return inner;
+    }
+    const token = tokens[position];
+    if (token === void 0)
+      throw new Error("the expression ends too soon");
+    position += 1;
+    if (token.kind === "word" && token.text === "true") {
+      return { kind: "literal", value: true };
+    }
+    if (token.kind === "word" && token.text === "false") {
+      return { kind: "literal", value: false };
+    }
+    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(", ")}`);
+    }
+    return parseKeyAtom(token.text);
+  };
+  const parseKeyAtom = (key) => {
+    const negated = takeOperator("!=");
+    if (!negated && !takeOperator("==")) {
+      if (WHERE_KEY_TYPES[key] !== "boolean") {
+        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]}`);
+    }
+    return { kind: "equals", key, value, negated };
+  };
+  const parseLiteral = () => {
+    const token = tokens[position];
+    position += 1;
+    if (token?.kind === "string")
+      return token.text;
+    if (token?.kind === "word" && token.text === "true")
+      return true;
+    if (token?.kind === "word" && token.text === "false")
+      return false;
+    throw new Error("expected a string, true or false after == or !=");
+  };
+  const where = parseOr();
+  const extra = tokens[position];
+  if (extra !== void 0)
+    throw new Error(`unexpected '${extra.text}'`);
+  return where;
+}
+function parseCommandWhere(source) {
+  try {
+    return { ok: true, where: parseTokens(tokenize(source)) };
+  } catch (error) {
+    return { ok: false, message: error.message };
+  }
+}
+function resolve(where, values) {
+  switch (where.kind) {
+    case "literal":
+      return where.value;
+    case "key": {
+      const value = values[where.key];
+      return value === void 0 ? void 0 : value === true;
+    }
+    case "equals": {
+      const value = values[where.key];
+      if (value === void 0)
+        return void 0;
+      return value === where.value !== where.negated;
+    }
+    case "not": {
+      const operand = resolve(where.operand, values);
+      return operand === void 0 ? void 0 : !operand;
+    }
+    case "and": {
+      const left = resolve(where.left, values);
+      const right = resolve(where.right, values);
+      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);
+      if (left === true || right === true)
+        return true;
+      return left === void 0 || right === void 0 ? void 0 : false;
+    }
+  }
+}
+function evaluateCommandWhere(where, values) {
+  return resolve(where, values) === true;
+}
+
 // packages/plugin-protocol/dist/contributions.js
 var MCP_SERVER_LOCAL_HTTP_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1"]);
 var MCP_SIGN_IN_SCHEME_KIND = {
@@ -3095,6 +3264,14 @@ function createContributionsSchemas(canonical) {
     knownResources: true,
     describesOperations: true
   });
+  const AppDataSourceStore = z12.discriminatedUnion("shape", [
+    z12.strictObject({
+      shape: z12.literal("rows"),
+      rowsField: NonEmptyString3,
+      key: z12.array(NonEmptyString3).min(1)
+    }),
+    z12.strictObject({ shape: z12.literal("value") })
+  ]);
   const AppDataSourceContribution2 = z12.strictObject({
     localId: LocalContributionId2,
     scope: z12.enum(["runtime", "account", "session"]),
@@ -3115,7 +3292,8 @@ function createContributionsSchemas(canonical) {
         })
       ]).optional()
     }),
-    read: AppDataSourceRead.optional()
+    read: AppDataSourceRead.optional(),
+    store: AppDataSourceStore.optional()
   }).superRefine((source, ctx) => {
     if (source.read !== void 0 && source.scope !== "session") {
       ctx.addIssue({
@@ -3124,6 +3302,23 @@ function createContributionsSchemas(canonical) {
         message: "App-data read operations require session scope."
       });
     }
+    if (source.store === void 0)
+      return;
+    if (source.scope === "session") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["store"],
+        message: "A declared app-data store requires runtime or account scope."
+      });
+    }
+    const replaces = source.change.semantics?.kind === "snapshot-replacement";
+    if (replaces !== (source.store.shape === "value")) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["store"],
+        message: "A value store requires snapshot-replacement changes, and a rows store forbids them."
+      });
+    }
   });
   const WhiteboardTypeStorage2 = z12.discriminatedUnion("kind", [
     z12.strictObject({ kind: z12.literal("json") }),
@@ -3376,8 +3571,28 @@ function createContributionsSchemas(canonical) {
   const UiCommandContribution2 = z12.strictObject({
     localId: LocalContributionId2,
     title: NonEmptyString3,
-    icon: NonEmptyString3.optional(),
-    placement: NonEmptyString3.optional()
+    icon: PackageAssetPath2.optional(),
+    button: z12.enum(["tabStrip"]).optional(),
+    menu: z12.enum(["help"]).optional(),
+    where: NonEmptyString3.optional()
+  }).superRefine((command, ctx) => {
+    if (command.where === void 0)
+      return;
+    if (command.button === void 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["where"],
+        message: `command ${command.localId} declares where without a button: where only decides when a button shows`
+      });
+    }
+    const parsed = parseCommandWhere(command.where);
+    if (!parsed.ok) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["where"],
+        message: `command ${command.localId} has an invalid where: ${parsed.message}`
+      });
+    }
   });
   const UiSlotContribution2 = z12.strictObject({
     localId: LocalContributionId2,
@@ -3462,16 +3677,9 @@ function createContributionsSchemas(canonical) {
     "cost.read",
     // Server-rated organization billing, distinct from local/provider cost.
     "billing.read",
-    // Context, Skills, and Memory analytics reads (full snapshots via the capability broker).
-    "context.read",
+    // Skills and Memory analytics reads (full snapshots via the capability broker).
     "skills.read",
     "memory.read",
-    // The "session trees" lens: root-session USD/token roll-ups from the
-    // typed usage-query surface (telemetry-unification RFC Phase 3, PR 3
-    // contract `docs/telemetry-lane-pr3-contracts.md`, amendment A7). Follows
-    // the `cost.read`/`context.read`/`skills.read`/`memory.read` convention -
-    // names the data (`usage`), not the tab that happens to render it.
-    "usage.read",
     // The self-improvement lens: reads the telemetry lane's self-improvement rollup
     // (memory/skill/notebook activity). Follows the same "names the data" convention.
     "self-improvement.read",
@@ -4190,9 +4398,7 @@ function createManifestSchemas(canonical) {
      */
     description: NonEmptyString3,
     // Display icons resolved relative to the package root and traversal-guarded
-    // by `PackageAssetPath`. This is a *raster/asset* icon - distinct from the
-    // *symbolic* `UiCommandContribution.icon` (an icon-set name), see LEXICON
-    // `icon`. By default the host treats the SVG as a mark and frames it, inset
+    // by `PackageAssetPath`. By default the host treats the SVG as a mark and frames it, inset
     // on a white tile. An SVG whose artwork is already a complete tile (its own
     // background, edge to edge) says so with `data-icon-shape="tile"` on its
     // root `<svg>` element, and the host then draws it full-bleed in its tile
@@ -4291,6 +4497,7 @@ function createManifestSchemas(canonical) {
     }
     reportDuplicateLocalIds(ctx, ["targets", "kay", "app", "contributes", "notificationRules"], manifest.targets?.kay?.app?.contributes?.notificationRules, "notification rule");
     const declaredAppDataSources = new Set(manifest.targets?.kay?.app?.contributes?.dataSources?.map((source) => source.localId) ?? []);
+    const declaredAppDataStores = new Set(manifest.targets?.kay?.app?.contributes?.dataSources?.filter((source) => source.store !== void 0).map((source) => source.localId) ?? []);
     const materializedAppDataSources = /* @__PURE__ */ new Set();
     for (const [index, materializer] of (manifest.targets?.kay?.ui?.contributes?.dataMaterializers ?? []).entries()) {
       if (!declaredAppDataSources.has(materializer.source)) {
@@ -4323,15 +4530,30 @@ function createManifestSchemas(canonical) {
           message: `app-data source ${materializer.source} has more than one materializer`
         });
       }
+      if (declaredAppDataStores.has(materializer.source)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [
+            "targets",
+            "kay",
+            "ui",
+            "contributes",
+            "dataMaterializers",
+            index,
+            "source"
+          ],
+          message: `app-data source ${materializer.source} declares a store and a materializer`
+        });
+      }
       materializedAppDataSources.add(materializer.source);
     }
     for (const source of declaredAppDataSources) {
-      if (materializedAppDataSources.has(source))
+      if (materializedAppDataSources.has(source) || declaredAppDataStores.has(source))
         continue;
       ctx.addIssue({
         code: "custom",
         path: ["targets", "kay", "app", "contributes", "dataSources"],
-        message: `app-data source ${source} has no same-plugin UI materializer`
+        message: `app-data source ${source} has no declared store and no same-plugin UI materializer`
       });
     }
     reportDuplicateLocalIds(ctx, ["targets", "kay", "app", "contributes", "whiteboardTypes"], manifest.targets?.kay?.app?.contributes?.whiteboardTypes, "Whiteboard type");
@@ -4395,6 +4617,7 @@ function createManifestSchemas(canonical) {
         presentationByUriModule.set(presentation.uriModule, presentation.localId);
       }
     }
+    reportDuplicateLocalIds(ctx, ["targets", "kay", "ui", "contributes", "commands"], manifest.targets?.kay?.ui?.contributes?.commands, "ui command");
     reportDuplicateLocalIds(ctx, ["targets", "kay", "ui", "contributes", "referencePresentations"], manifest.targets?.kay?.ui?.contributes?.referencePresentations, "reference presentation");
     reportDuplicateLocalIds(ctx, ["targets", "kay", "app", "contributes", "eventDefinitions"], manifest.targets?.kay?.app?.contributes?.eventDefinitions, "plugin event definition");
     reportDuplicateLocalIds(ctx, ["targets", "kay", "app", "contributes", "contextContributors"], manifest.targets?.kay?.app?.contributes?.contextContributors, "context contributor");
@@ -5128,7 +5351,15 @@ function createResolvedContractSchemas(canonical) {
         })
       ]).optional()
     }),
-    read: AppDataSourceRead.optional()
+    read: AppDataSourceRead.optional(),
+    store: z14.discriminatedUnion("shape", [
+      z14.strictObject({
+        shape: z14.literal("rows"),
+        rowsField: z14.string().min(1),
+        key: z14.array(z14.string().min(1)).min(1)
+      }),
+      z14.strictObject({ shape: z14.literal("value") })
+    ]).optional()
   }).superRefine((source, ctx) => {
     if (source.read !== void 0 && source.scope !== "session") {
       ctx.addIssue({
@@ -5769,7 +6000,8 @@ function resolveKayPluginContractV1(manifest) {
     scope: source.scope,
     snapshot: source.snapshot,
     change: source.change,
-    ...source.read === void 0 ? {} : { read: source.read }
+    ...source.read === void 0 ? {} : { read: source.read },
+    ...source.store === void 0 ? {} : { store: source.store }
   }));
   const kayAppApprovalTypes = manifest.targets?.kay?.app?.contributes?.approvalTypes?.map(({ uriModule, ...type }) => {
     const authService = manifest.targets?.kay?.agent?.contributes?.uriModules?.find((candidate) => candidate.localId === uriModule)?.authService;
@@ -6875,9 +7107,12 @@ export {
   compareClaims,
   compareSemver,
   configSectionKeysForManifest,
+  declarationsOfKind,
+  declaredCommandId,
   declaredUiIconPaths,
   dedupeClaims,
   deriveDirectoryPluginToolName,
+  evaluateCommandWhere,
   finalizeArtifactProvenanceEnvelope,
   findSkillSuggestionCitations,
   hasClaim,
@@ -6899,6 +7134,7 @@ export {
   parseArtifactOutputUri,
   parseArtifactProvenanceCaptureContext,
   parseArtifactProvenanceEnvelope,
+  parseCommandWhere,
   parseKayPluginManifestV1,
   parseKayUiAppPackageV1,
   parseKayUiBundleIndexV1,

package/package.json

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