@yaklabs-ai/plugin-protocol 0.32.0 → 0.34.0

package/README.md

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

package/THIRD-PARTY-INVENTORY.json

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

package/dist/index.d.ts

@@ -2580,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;
@@ -2694,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";
@@ -2715,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";
@@ -2737,6 +2739,9 @@ declare const canonicalContributionSchemas: {
             primary: "primary";
             plugins: "plugins";
         }>>;
+        panel: z.ZodOptional<z.ZodObject<{
+            body: z.ZodString;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
     UiAppContribution: z.ZodObject<{
         localId: z.ZodString;
@@ -2766,8 +2771,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";
@@ -2804,8 +2807,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";
@@ -2999,6 +3000,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
@@ -3128,6 +3164,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
@@ -3227,6 +3282,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<{
@@ -4009,8 +4071,17 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.34.0 lets a rail entry declare a sidebar (#15901). `panel.body` on a `railEntries` entry names
+ * what fills it, either a `contextOnly` app in the plugin or a body the host ships. Additive: a rail
+ * entry with no `panel` still opens its page alone. A plugin that declares a panel declares ^0.34.0.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.32.0";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.34.0";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5474,7 +5545,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;
@@ -5562,8 +5639,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";
@@ -5600,8 +5675,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";
@@ -5623,6 +5696,9 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                             primary: "primary";
                             plugins: "plugins";
                         }>>;
+                        panel: z.ZodOptional<z.ZodObject<{
+                            body: z.ZodString;
+                        }, z.core.$strict>>;
                     }, z.core.$strict>>>;
                     themes: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
@@ -6449,8 +6525,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";
@@ -6568,7 +6642,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;
@@ -6656,8 +6736,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";
@@ -6694,8 +6772,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";
@@ -6717,6 +6793,9 @@ export declare const KayUiTargetManifest: z.ZodObject<{
                 primary: "primary";
                 plugins: "plugins";
             }>>;
+            panel: z.ZodOptional<z.ZodObject<{
+                body: z.ZodString;
+            }, z.core.$strict>>;
         }, z.core.$strict>>>;
         themes: z.ZodOptional<z.ZodArray<z.ZodObject<{
             localId: z.ZodString;
@@ -6886,6 +6965,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;
@@ -10772,8 +10857,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";
@@ -12066,8 +12149,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";
@@ -13652,8 +13733,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";
@@ -13693,8 +13772,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";
@@ -13731,8 +13808,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";
@@ -13749,11 +13824,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;
@@ -13773,6 +13856,9 @@ export declare const UiRailEntryContribution: z.ZodObject<{
         primary: "primary";
         plugins: "plugins";
     }>>;
+    panel: z.ZodOptional<z.ZodObject<{
+        body: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 export declare type UiRailEntryContribution = z.infer<typeof UiRailEntryContribution>;
@@ -14174,6 +14260,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,14 +238,16 @@ 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.32.0";
+var KAY_PLUGIN_SDK_VERSION = "0.34.0";
 var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.26.3",
   "0.27.1",
   "0.28.0",
   "0.29.0",
   "0.30.0",
-  "0.31.0"
+  "0.31.0",
+  "0.32.0",
+  "0.33.0"
 ];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
@@ -2823,6 +2833,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 = {
@@ -3403,8 +3572,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,
@@ -3489,16 +3678,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",
@@ -3548,7 +3730,8 @@ function createContributionsSchemas(canonical) {
     homeLocation: NonEmptyString3.optional(),
     shortcut: NonEmptyString3.optional(),
     order: z12.number().finite().optional(),
-    section: z12.enum(["primary", "plugins"]).optional()
+    section: z12.enum(["primary", "plugins"]).optional(),
+    panel: z12.strictObject({ body: LocalContributionId2 }).optional()
   });
   const UiAppFields = z12.strictObject({
     localId: LocalContributionId2,
@@ -4217,9 +4400,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
@@ -4397,6 +4578,26 @@ function createManifestSchemas(canonical) {
         });
       }
     }
+    for (const [index, entry] of (manifest.targets?.kay?.ui?.contributes?.railEntries ?? []).entries()) {
+      const body = entry.panel?.body;
+      const app = manifest.targets?.kay?.ui?.contributes?.apps?.find((candidate) => candidate.localId === body);
+      if (app !== void 0 && app.contextOnly !== true) {
+        ctx.addIssue({
+          code: "custom",
+          path: [
+            "targets",
+            "kay",
+            "ui",
+            "contributes",
+            "railEntries",
+            index,
+            "panel",
+            "body"
+          ],
+          message: `Rail entry ${entry.id} panel body ${app.localId} must be a contextOnly ui app`
+        });
+      }
+    }
     const subscribedUiEvents = new Set(manifest.targets?.kay?.ui?.contributes?.eventSubscriptions?.map((subscription) => subscription.event) ?? []);
     const invokedUiEndpoints = new Set(manifest.permissions?.byTarget["kay.ui"]?.endpoints?.filter((grant) => grant.operations.includes("invoke")).map((grant) => grant.endpoint) ?? []);
     const uriModuleIds = new Set([
@@ -4438,6 +4639,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");
@@ -6927,9 +7129,12 @@ export {
   compareClaims,
   compareSemver,
   configSectionKeysForManifest,
+  declarationsOfKind,
+  declaredCommandId,
   declaredUiIconPaths,
   dedupeClaims,
   deriveDirectoryPluginToolName,
+  evaluateCommandWhere,
   finalizeArtifactProvenanceEnvelope,
   findSkillSuggestionCitations,
   hasClaim,
@@ -6951,6 +7156,7 @@ export {
   parseArtifactOutputUri,
   parseArtifactProvenanceCaptureContext,
   parseArtifactProvenanceEnvelope,
+  parseCommandWhere,
   parseKayPluginManifestV1,
   parseKayUiAppPackageV1,
   parseKayUiBundleIndexV1,

package/package.json

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