@econ-v1/rpc 7.2.10 → 7.3.1

package/src/describe-client-error.js

@@ -12,19 +12,42 @@
  */
 const DOMAIN_COPY = {
   "access-code-invalid": { message: "That access code wasn't accepted.", showRetry: false },
+  approval_denied: { message: "That action wasn't approved.", showRetry: false },
   capability_not_declared: { message: "This app asked for something it isn't allowed to use.", showRetry: false },
   capability_unavailable: { message: "This app isn't running on your node.", showRetry: true },
   child_unavailable: { message: "This part of the app isn't available right now.", showRetry: false },
   "code-already-bound": { message: "That access code has already been used.", showRetry: false },
   conflict: { message: "Someone else changed this first.", showRetry: true },
+  forbidden: { message: "This app isn't allowed to do that.", showRetry: false },
+  invalid_payload: { message: "Some of those details weren't accepted.", showRetry: false },
   invalid_request: { message: "Your node couldn't understand that request.", showRetry: false },
   not_found: { message: "That isn't here any more.", showRetry: false },
+  scope_unavailable: { message: "There's nothing to look at there right now.", showRetry: true },
+  script_timeout: { message: "That script took too long and was stopped.", showRetry: false },
+  script_unavailable: { message: "Scripts can't run in this tab right now.", showRetry: true },
   stage_composition_not_enabled: { message: "This screen can't open other apps here.", showRetry: false },
+  timeout: { message: "That took too long. Please try again.", showRetry: true },
   unauthorized: { message: "This device isn't allowed to do that.", showRetry: false },
+  unknown_command: { message: "Your node doesn't support that action yet.", showRetry: false },
   unsupported_query: { message: "Your node doesn't support this yet.", showRetry: false },
   validation_failed: { message: "Some of those details weren't accepted.", showRetry: false },
 };
 
+/**
+ * A `forbidden` error names why in `details.reason`; each reason gets its own copy so the user
+ * learns what to do, not just that they were refused. An unrecognised reason falls back to the
+ * generic `forbidden` copy.
+ *
+ * @type {Readonly<Record<string, { readonly message: string, readonly showRetry: boolean }>>}
+ */
+const FORBIDDEN_REASON_COPY = {
+  grant_request_invalid: { message: "That permission request has expired. Ask again to continue.", showRetry: false },
+  not_exposed: { message: "That isn't available to apps.", showRetry: false },
+  not_granted: { message: "This app hasn't been given permission for that yet.", showRetry: false },
+  owner_only: { message: "Only the owner's paired device can do that.", showRetry: false },
+  reserved_key: { message: "That setting is managed by your node and can't be changed here.", showRetry: false },
+};
+
 /**
  * Maps any thrown value to what the UI should do with it.
  *
@@ -51,7 +74,11 @@ export function describeClientError(error) {
   }
 
   if (kind === "domain" && typeof code === "string") {
-    const copy = DOMAIN_COPY[code];
+    const details = /** @type {{ details?: unknown }} */ (error)?.details;
+    const reason = code === "forbidden" && typeof details === "object" && details !== null
+      ? /** @type {{ reason?: unknown }} */ (details).reason
+      : undefined;
+    const copy = (typeof reason === "string" ? FORBIDDEN_REASON_COPY[reason] : undefined) ?? DOMAIN_COPY[code];
     if (copy !== undefined) {
       return Object.freeze({ ...copy, surface: /** @type {const} */ ("inline") });
     }

package/src/grants-contract.js

@@ -0,0 +1,8 @@
+// @ts-check
+
+/**
+ * The one grant the shell can record today: page inspection (console, network, page structure
+ * and owner-approved scripts). The kernel's grant policy and the shell's consent dialog and
+ * settings page all name it through this constant so the id cannot drift between them.
+ */
+export const DEVTOOLS_GRANT = "devtools.inspect";

package/src/host-context-contract.js

@@ -0,0 +1,60 @@
+// @ts-check
+
+/**
+ * @typedef {{ type: string, id: string, label?: string }} HostContextRef
+ * @typedef {{ screen: string, entity?: HostContextRef, selection?: HostContextRef[], summary?: string, facts?: Record<string, string | number | boolean | null> }} HostContextView
+ */
+
+/** Serialized size limit of one `ctx.host.context.set` view (spec §4.5.2). */
+export const HOST_CONTEXT_MAX_BYTES = 4096;
+const VIEW_KEYS = new Set(["screen", "entity", "selection", "summary", "facts"]);
+const REF_KEYS = new Set(["type", "id", "label"]);
+
+/** UTF-8 length without `TextEncoder`, which this platform-free package cannot assume.
+ * @param {string} text */
+function utf8Length(text) {
+    let bytes = 0;
+    for (const char of text) {
+        const code = /** @type {number} */ (char.codePointAt(0));
+        bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+    }
+    return bytes;
+}
+/** @param {unknown} value @returns {value is HostContextRef} */
+function isRef(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+    const ref = /** @type {Record<string, unknown>} */ (value);
+    return Object.keys(ref).every((key) => REF_KEYS.has(key)) && typeof ref.type === "string" && typeof ref.id === "string"
+        && (ref.label === undefined || typeof ref.label === "string");
+}
+
+/**
+ * The one rule set for a stage-reported view. The shell checks it before reporting and the
+ * kernel checks it again on receipt, so neither trusts the other's copy. Returns a detached
+ * JSON copy on success (caller getters are read once) or the reason it was rejected.
+ * @param {unknown} value @returns {string | HostContextView}
+ */
+export function validateHostContextView(value) {
+    try {
+        const json = JSON.stringify(value);
+        if (utf8Length(json) > HOST_CONTEXT_MAX_BYTES) return `view exceeds ${HOST_CONTEXT_MAX_BYTES} bytes`;
+        value = JSON.parse(json);
+    } catch { return "view must be JSON"; }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return "view must be an object";
+    const view = /** @type {Record<string, unknown>} */ (value);
+    const unknown = Object.keys(view).find((key) => !VIEW_KEYS.has(key));
+    if (unknown !== undefined) return `view has unknown key ${unknown}`;
+    if (typeof view.screen !== "string" || view.screen.length === 0 || view.screen.length > 64) return "screen must be 1–64 chars";
+    if (view.summary !== undefined && (typeof view.summary !== "string" || view.summary.length > 280)) return "summary must be ≤ 280 chars";
+    if (view.entity !== undefined && !isRef(view.entity)) return "entity must be { type, id, label? } strings";
+    if (view.selection !== undefined) {
+        if (!Array.isArray(view.selection) || view.selection.length > 20) return "selection must have ≤ 20 items";
+        if (!view.selection.every(isRef)) return "selection items must be { type, id, label? } strings";
+    }
+    if (view.facts !== undefined) {
+        if (view.facts === null || typeof view.facts !== "object" || Array.isArray(view.facts)) return "facts must be an object";
+        const entries = Object.entries(view.facts);
+        if (entries.length > 32 || entries.some(([, v]) => v !== null && !["string", "number", "boolean"].includes(typeof v))) return "facts must have ≤ 32 primitive values";
+    }
+    return /** @type {HostContextView} */ (view);
+}

package/src/index.js

@@ -8,6 +8,9 @@
 /** @typedef {import("./client.js").PreparedStage} PreparedStage */
 /** @typedef {import("./client.js").StageRpcSession} StageRpcSession */
 /** @typedef {import("./client.js").Unsubscribe} Unsubscribe */
+/** @typedef {import("./client.js").EventSubscribeOptions} EventSubscribeOptions */
+/** @typedef {import("./client.js").EventSubscription} EventSubscription */
+/** @typedef {import("./client.js").SubscriptionState} SubscriptionState */
 /** @typedef {import("@econ-v1/domain").ClientError} ClientError */
 /** @typedef {import("@econ-v1/domain").DomainEvent} DomainEvent */
 /** @typedef {import("@econ-v1/domain").DomainErrorCode} DomainErrorCode */
@@ -201,9 +204,12 @@ export {
   serializeClientError,
 } from "./errors.js";
 export { DEFAULT_REQUEST_TIMEOUT_MS, KernelRpcTimeoutError, MessagePortKernelRpcClient } from "./message-port-client.js";
+export { SubscriptionStateCell } from "./subscription-state.js";
 export { NODE_APP_LIFECYCLE_COMMAND, NODE_APP_MEMORY_CAPTURE_COMMAND, NODE_APP_MEMORY_DETAIL_QUERY, NODE_APP_MEMORY_DOWNLOAD_COMMAND, NODE_APP_MEMORY_LIST_QUERY, NODE_APP_MEMORY_OVERVIEW_QUERY, NODE_APP_MEMORY_STATUS_COMMAND } from "./node-app-memory-contract.js";
 export { APPS_LIFECYCLE_PIN_COMMAND, APPS_LIFECYCLE_QUERY } from "./apps-lifecycle-contract.js";
 export { CLIENT_SERVICES_RETRY_COMMAND } from "./client-services-contract.js";
+export { DEVTOOLS_GRANT } from "./grants-contract.js";
+export { HOST_CONTEXT_MAX_BYTES, validateHostContextView } from "./host-context-contract.js";
 export { L402_ENFORCEMENT_QUERY, L402_ENFORCEMENT_ROW_ID, L402_ENFORCEMENT_SET_COMMAND } from "./l402-enforcement-contract.js";
 export { isRouteMode, MODEL_PICKER_CATALOG_QUERY, MODEL_PICKER_CATALOG_ROW_ID, MODEL_PICKER_RECENTS_LIMIT, MODEL_PICKER_RECENTS_SETTING, MODEL_PICKER_STAGE_ID, ROUTE_MODES, WEB_SEARCH_AUTO } from "./model-picker-contract.js";
 export {
@@ -276,3 +282,7 @@ export { CHILD_ACTIONS, CHILD_STATE_CODES, describeChildState, isTransientChildS
 /** @typedef {import("./child-state-contract.js").ChildAction} ChildAction */
 export { createNodeHealthQuery, NODE_HEALTH_QUERY } from "./node-health-query.js";
 export { createResponsivenessTracker, EMA_HOLD_MS } from "./node-responsiveness.js";
+/** @typedef {import("@econ-v1/ports").DevtoolsScriptContext} DevtoolsScriptContext */
+/** @typedef {import("@econ-v1/ports").DevtoolsScriptHostPort} DevtoolsScriptHostPort */
+/** @typedef {import("./host-context-contract.js").HostContextRef} HostContextRef */
+/** @typedef {import("./host-context-contract.js").HostContextView} HostContextView */

package/src/message-port-client.js

@@ -1,11 +1,13 @@
 // @ts-check
 import {
   DomainError,
+  SyncError,
   TransportError,
 } from "@econ-v1/domain";
 
 import { isJsonValue } from "./errors.js";
 import { EMA_REFERENCE_TIMEOUT_MS, slowBarMs } from "./node-responsiveness.js";
+import { SubscriptionStateCell } from "./subscription-state.js";
 import {
   deserializeRpcEvent,
   deserializeRpcResponse,
@@ -20,11 +22,18 @@ import {
 /** @typedef {import("./client.js").PreparedStage} PreparedStage */
 /** @typedef {import("./client.js").StageRpcSession} StageRpcSession */
 /** @typedef {import("./client.js").Unsubscribe} Unsubscribe */
+/** @typedef {import("./client.js").EventSubscribeOptions} EventSubscribeOptions */
+/** @typedef {import("./client.js").EventSubscription} EventSubscription */
+/** @typedef {import("./client.js").SubscriptionState} SubscriptionState */
 /** @typedef {import("./protocol.js").RpcRequest} RpcRequest */
 /** @typedef {RpcRequest extends infer TRequest ? TRequest extends RpcRequest ? Omit<TRequest, "id"> : never : never} RpcRequestWithoutId */
 /** @typedef {import("./transport.js").RpcTransport} RpcTransport */
 /** @typedef {{ readonly reject: (error: unknown) => void, readonly resolve: (value: JsonValue) => void, readonly sessionId: string | undefined, readonly slowBarId: ReturnType<typeof globalThis.setTimeout>, readonly startedAtMs: number, readonly timeoutId: ReturnType<typeof globalThis.setTimeout>, readonly timeoutMs: number }} PendingRequest */
-/** @typedef {{ readonly eventType: KernelEventType, readonly listeners: Set<(event: DomainEvent) => void>, readonly sessionId: string | undefined, readonly subscriptionId: string }} EventGroup */
+/**
+ * `cell` counts the group's own generations rather than the kernel's, because a new kernel
+ * (a leader-tab failover replays this subscription onto it) starts its count again.
+ * @typedef {{ readonly cell: SubscriptionStateCell, readonly eventType: KernelEventType, readonly listeners: Set<(event: DomainEvent) => void>, readonly pendingReady: Set<(error: TransportError) => void>, refusal?: unknown, readonly sessionId: string | undefined, readonly subscriptionId: string }} EventGroup
+ */
 /** @typedef {{ readonly errorListeners: Set<(error: { readonly message: string }) => void>, readonly listeners: Set<(diff: import("@econ-v1/domain").QueryDiff<JsonValue>) => void>, readonly name: QueryName, readonly params: JsonValue, retryTimer: ReturnType<typeof globalThis.setTimeout> | undefined, readonly sessionId: string | undefined, subscriptionId: string }} LiveQueryGroup */
 /** @typedef {{ markSlow(id: string): void, settle(id: string, elapsedMs: number, answered: boolean, timeoutMs: number): void }} RpcResponsivenessObserver */
 /** @typedef {{ readonly monotonicNow?: () => number, readonly now?: () => string, readonly observer?: RpcResponsivenessObserver, readonly requestTimeoutMs?: number }} MessagePortKernelRpcClientOptions */
@@ -169,6 +178,8 @@ export class MessagePortKernelRpcClient {
   /** @type {() => void} */
   #unsubscribeMessages;
   #closed = false;
+  /** @type {((name: string, payload: JsonValue) => Promise<JsonValue>) | undefined} */
+  #uiRequestHandler;
   #nextRequestId = 1;
   #nextSubscriptionId = 1;
 
@@ -288,10 +299,11 @@ export class MessagePortKernelRpcClient {
    * @template {KernelEventType} T
    * @param {T} type
    * @param {(event: import("@econ-v1/domain").KernelEventByType<T>) => void} listener
-   * @returns {Unsubscribe}
+   * @param {EventSubscribeOptions} [options]
+   * @returns {EventSubscription}
    */
-  subscribe(type, listener) {
-    return this.#subscribeEvent(undefined, type, listener);
+  subscribe(type, listener, options) {
+    return this.#subscribeEvent(undefined, type, listener, options);
   }
 
   /** @param {string} sessionId */
@@ -322,6 +334,42 @@ export class MessagePortKernelRpcClient {
     }));
   }
 
+  /** @template T @param {string} sessionId @param {string} name @param {unknown} payload @returns {Promise<T>} */
+  commandStage(sessionId, name, payload) {
+    return /** @type {Promise<T>} */ (this.#request({ name, payload: jsonValue(payload, "command payload"), sessionId, type: "stage.command" }));
+  }
+
+  /** @param {(name: string, payload: JsonValue) => Promise<JsonValue>} handler @returns {Unsubscribe} */
+  onUiRequest(handler) {
+    this.#uiRequestHandler = handler;
+    return () => { if (this.#uiRequestHandler === handler) this.#uiRequestHandler = undefined; };
+  }
+
+  /** @param {{ readonly name: string, readonly payload: JsonValue, readonly requestId: string }} event */
+  async #answerUiRequest(event) {
+    const handler = this.#uiRequestHandler;
+    /** @type {RpcRequestWithoutId} */
+    let response;
+    try {
+      if (handler === undefined) throw new TransportError({ code: "unavailable", message: "No shell is handling UI requests in this tab" });
+      const value = jsonValue(await handler(event.name, event.payload), "UI response value");
+      response = { ok: true, requestId: event.requestId, type: "ui.response", value };
+    } catch (error) {
+      const clientError = error instanceof DomainError || error instanceof SyncError || error instanceof TransportError
+        ? error
+        : new DomainError({ code: "invalid_request", message: "UI request handler failed" });
+      response = { error: clientError, ok: false, requestId: event.requestId, type: "ui.response" };
+    }
+    if (this.#closed || this.#transport.state !== "open") return;
+    const id = `request-${this.#nextRequestId}`;
+    this.#nextRequestId += 1;
+    try {
+      this.#transport.send(serializeRpcRequest(/** @type {RpcRequest} */ ({ ...response, id })));
+    } catch {
+      // UI responses are fire-and-forget; a closed transport cannot receive them.
+    }
+  }
+
   /**
    * @template T
    * @param {string} sessionId
@@ -368,10 +416,11 @@ export class MessagePortKernelRpcClient {
    * @param {string} sessionId
    * @param {T} type
    * @param {(event: import("@econ-v1/domain").KernelEventByType<T>) => void} listener
-   * @returns {Unsubscribe}
+   * @param {EventSubscribeOptions} [options]
+   * @returns {EventSubscription}
    */
-  subscribeStage(sessionId, type, listener) {
-    return this.#subscribeEvent(sessionId, type, listener);
+  subscribeStage(sessionId, type, listener, options) {
+    return this.#subscribeEvent(sessionId, type, listener, options);
   }
 
   #handleClose() {
@@ -381,6 +430,11 @@ export class MessagePortKernelRpcClient {
     this.#unsubscribeClose();
     const error = new TransportError({ code: "connection_lost", message: "Kernel RPC port closed" });
     for (const requestId of [...this.#pending.keys()]) this.#takePending(requestId, false)?.reject(error);
+    // Tell each subscription it went quiet, instead of leaving its listeners silent.
+    for (const group of this.#eventGroupsByKey.values()) {
+      group.cell.report("lost");
+      this.#cancelEventGroupReady(group, error);
+    }
     this.#eventGroupsByKey.clear();
     this.#eventGroupsBySubscription.clear();
     // A pending re-subscribe timer must not outlive the port it would retry on — otherwise a
@@ -429,6 +483,10 @@ export class MessagePortKernelRpcClient {
 
     try {
       const event = deserializeRpcEvent(message);
+      if (event.type === "ui.request") {
+        void this.#answerUiRequest(event);
+        return;
+      }
       if (event.type === "kernel.event") {
         const group = this.#eventGroupsBySubscription.get(event.subscriptionId);
         if (group === undefined || group.eventType !== event.event.type) return;
@@ -448,6 +506,11 @@ export class MessagePortKernelRpcClient {
         for (const listener of [...group.errorListeners]) this.#notify(() => listener({ message: failureMessage }));
         return;
       }
+      if (event.type === "subscription.state") {
+        const group = this.#eventGroupsBySubscription.get(event.subscriptionId);
+        if (group !== undefined) group.cell.report(event.state.status, event.state.confirmed, event.state.reason);
+        return;
+      }
       const group = this.#liveGroupsBySubscription.get(event.subscriptionId);
       if (group === undefined) return;
       for (const listener of [...group.listeners]) this.#notify(() => listener(event.diff));
@@ -495,6 +558,8 @@ export class MessagePortKernelRpcClient {
   #removeSessionSubscriptions(sessionId) {
     for (const [key, group] of [...this.#eventGroupsByKey]) {
       if (group.sessionId === sessionId) {
+        group.cell.report("lost");
+        this.#cancelEventGroupReady(group, new TransportError({ code: "connection_lost", message: "Stage RPC session closed" }));
         this.#eventGroupsByKey.delete(key);
         this.#eventGroupsBySubscription.delete(group.subscriptionId);
       }
@@ -559,32 +624,53 @@ export class MessagePortKernelRpcClient {
    * @param {string | undefined} sessionId
    * @param {T} eventType
    * @param {(event: import("@econ-v1/domain").KernelEventByType<T>) => void} listener
-   * @returns {Unsubscribe}
+   * @param {EventSubscribeOptions} [options]
+   * @returns {EventSubscription}
    */
-  #subscribeEvent(sessionId, eventType, listener) {
-    const key = `${sessionId ?? "host"}:event:${eventType}`;
-    let group = this.#eventGroupsByKey.get(key);
-    if (group === undefined) {
-      const subscriptionId = this.#newSubscriptionId();
-      group = { eventType, listeners: new Set(), sessionId, subscriptionId };
-      this.#eventGroupsByKey.set(key, group);
-      this.#eventGroupsBySubscription.set(subscriptionId, group);
-      const request = sessionId === undefined
-        ? /** @type {const} */ ({ eventType, subscriptionId, type: "event.subscribe" })
-        : /** @type {const} */ ({ eventType, sessionId, subscriptionId, type: "stage.event.subscribe" });
-      void this.#request(request).catch((error) => {
-        this.#dropEventGroup(key, /** @type {EventGroup} */ (group));
-        warnSubscriptionRejected("event", eventType, sessionId, error);
-      });
+  #subscribeEvent(sessionId, eventType, listener, options) {
+    if (this.#closed || this.#transport.state !== "open") {
+      if (!this.#closed) this.#handleClose();
+      return this.#lostEventSubscription(options);
     }
+    const key = `${sessionId ?? "host"}:event:${eventType}`;
+    const group = this.#eventGroupsByKey.get(key) ?? this.#openEventGroup(key, sessionId, eventType);
+    const { cell } = group;
     const storedListener = /** @type {(event: DomainEvent) => void} */ (listener);
     group.listeners.add(storedListener);
+    const unwatch = options?.onState && cell.watch(options.onState);
+    // This handle's own `ready`: a group that joined while lost or pending must wait for
+    // its next `live`, not reuse one from before the gap.
+    /** @type {((error: TransportError) => void) | undefined} */
+    let cancelReady;
+    /** @type {Promise<SubscriptionState>} */
+    const ready = new Promise((resolve, reject) => {
+      const off = cell.watch((state) => {
+        if (state.status === "live") resolve(state);
+        else if (state.status === "refused") reject(group.refusal ?? new TransportError({ code: "unavailable", message: "The home node refused this subscription" }));
+        else return;
+        off();
+        group.pendingReady.delete(cancel);
+        cancelReady = undefined;
+      });
+      const cancel = (/** @type {TransportError} */ error) => {
+        off();
+        group.pendingReady.delete(cancel);
+        cancelReady = undefined;
+        reject(error);
+      };
+      group.pendingReady.add(cancel);
+      cancelReady = cancel;
+    });
+    // A holder that never looks at `ready` must not surface a refusal as unhandled.
+    ready.catch(() => undefined);
     let active = true;
-    return () => {
+    const unsubscribe = () => {
       if (!active) return;
       active = false;
-      group?.listeners.delete(storedListener);
-      if (group !== undefined && group.listeners.size === 0) {
+      unwatch?.();
+      cancelReady?.(new TransportError({ code: "connection_lost", message: "Subscription handle closed" }));
+      group.listeners.delete(storedListener);
+      if (group.listeners.size === 0) {
         this.#dropEventGroup(key, group);
         const request = sessionId === undefined
           ? /** @type {const} */ ({ subscriptionId: group.subscriptionId, type: "event.unsubscribe" })
@@ -592,6 +678,49 @@ export class MessagePortKernelRpcClient {
         void this.#request(request).catch(() => undefined);
       }
     };
+    return /** @type {EventSubscription} */ (Object.defineProperty(Object.assign(unsubscribe, { ready }), "state", { get: () => cell.state }));
+  }
+
+  /** @param {EventSubscribeOptions | undefined} options @returns {EventSubscription} */
+  #lostEventSubscription(options) {
+    const cell = new SubscriptionStateCell();
+    cell.report("lost");
+    const unwatch = options?.onState && cell.watch(options.onState);
+    const ready = Promise.reject(new TransportError({ code: "connection_lost", message: "Kernel RPC port is closed" }));
+    ready.catch(() => undefined);
+    const unsubscribe = () => unwatch?.();
+    return /** @type {EventSubscription} */ (Object.defineProperty(Object.assign(unsubscribe, { ready }), "state", { get: () => cell.state }));
+  }
+
+  /**
+   * @param {string} key
+   * @param {string | undefined} sessionId
+   * @param {KernelEventType} eventType
+   * @returns {EventGroup}
+   */
+  #openEventGroup(key, sessionId, eventType) {
+    const subscriptionId = this.#newSubscriptionId();
+    /** @type {EventGroup} */
+    const group = { cell: new SubscriptionStateCell(), eventType, listeners: new Set(), pendingReady: new Set(), sessionId, subscriptionId };
+    this.#eventGroupsByKey.set(key, group);
+    this.#eventGroupsBySubscription.set(subscriptionId, group);
+    const request = sessionId === undefined
+      ? /** @type {const} */ ({ eventType, subscriptionId, type: "event.subscribe" })
+      : /** @type {const} */ ({ eventType, sessionId, subscriptionId, type: "stage.event.subscribe" });
+    void this.#request(request).then((reply) => {
+      if (this.#eventGroupsByKey.get(key) !== group) return;
+      // `{ subscriptionState: 1 }` means state events follow, before or after this
+      // reply. `null` means none will come for this subscription (an older kernel, or
+      // a type a stage session adapter serves): live, but unconfirmed.
+      if (reply === null && !group.cell.state) group.cell.report("live");
+    }, (error) => {
+      if (this.#eventGroupsByKey.get(key) !== group) return;
+      group.refusal = error;
+      group.cell.report("refused");
+      this.#dropEventGroup(key, group);
+      warnSubscriptionRejected("event", eventType, sessionId, error);
+    });
+    return group;
   }
 
   /**
@@ -710,6 +839,11 @@ export class MessagePortKernelRpcClient {
     this.#eventGroupsBySubscription.delete(group.subscriptionId);
   }
 
+  /** @param {EventGroup} group @param {TransportError} error */
+  #cancelEventGroupReady(group, error) {
+    for (const cancel of [...group.pendingReady]) cancel(error);
+  }
+
   /**
    * @param {string} key
    * @param {LiveQueryGroup} group
@@ -752,6 +886,12 @@ class BoundStageRpcSession {
     this.#client.closeStageSession(this.#sessionId);
   }
 
+  /** @template T @param {string} name @param {unknown} payload @returns {Promise<T>} */
+  command(name, payload) {
+    this.#assertOpen();
+    return this.#client.commandStage(this.#sessionId, name, payload);
+  }
+
   /**
    * @template T
    * @param {string} capability
@@ -802,11 +942,12 @@ class BoundStageRpcSession {
    * @template {KernelEventType} T
    * @param {T} type
    * @param {(event: import("@econ-v1/domain").KernelEventByType<T>) => void} listener
-   * @returns {Unsubscribe}
+   * @param {EventSubscribeOptions} [options]
+   * @returns {EventSubscription}
    */
-  subscribe(type, listener) {
+  subscribe(type, listener, options) {
     this.#assertOpen();
-    return this.#client.subscribeStage(this.#sessionId, type, listener);
+    return this.#client.subscribeStage(this.#sessionId, type, listener, options);
   }
 
   #assertOpen() {

package/src/model-picker-contract.js

@@ -48,15 +48,21 @@ export const ROUTE_MODES = /** @type {const} */ (["auto", "public", "private"]);
  * absent means this node runs it on its own key ("My Store"). */
 /** @typedef {{ readonly name: string, readonly peerNodeId?: string }} ModelRef */
 
-/** What the stage already knows, so the overlay opens on it instead of a default. */
-/** @typedef {{ readonly current?: ModelRef, readonly routeMode?: RouteMode, readonly webSearch?: WebSearchChoice }} ModelPickRequest */
+/** What the stage already knows, so the overlay opens on it instead of a default.
+ * `onSelect` hears each Select at once, while the overlay stays open for the chips:
+ * the pick carries `model` and the chips as they stand. The promise still resolves
+ * when the overlay closes, with the final pick, so a stage that applies both must
+ * treat the same model twice as one choice. A host before it ignores `onSelect`. */
+/** @typedef {{ readonly current?: ModelRef, readonly routeMode?: RouteMode, readonly webSearch?: WebSearchChoice, readonly onSelect?: (pick: ModelPick) => void }} ModelPickRequest */
 
 /** `model` is present only when the owner pressed Select on a row; absent means
  * "keep whatever model the stage already had" — the owner changed only the
  * web-search chip (or nothing but still closed with a chip change). `label` is
  * the catalog's `picker_label ?? name`, so a pill or chip shows the same words
- * the overlay did. */
-/** @typedef {{ readonly model?: ModelRef, readonly label?: string, readonly routeMode: RouteMode, readonly webSearch: WebSearchChoice }} ModelPick */
+ * the overlay did. `storeName` is the seller's store as the overlay named it
+ * (this node's own `mine.name`, or the peer's), so a chip can say whose store
+ * sells the model. */
+/** @typedef {{ readonly model?: ModelRef, readonly label?: string, readonly storeName?: string, readonly routeMode: RouteMode, readonly webSearch: WebSearchChoice }} ModelPick */
 
 /** Resolves `undefined` when the owner closes without choosing. Rejects with a
  * `DomainError` `conflict` while another `open()` is still pending — the overlay

package/src/protocol.js

@@ -2,6 +2,7 @@
 
 /** @import { AppEventPayload, AppEventType, ClientError, CoreKernelEventType, DomainEvent, JsonObject, JsonValue, KernelEventPayload, QueryDiff, QueryName } from '@econ-v1/domain' */
 /** @import { NodeReachability } from './transport-contract.js' */
+/** @import { SubscriptionState } from './client.js' */
 /** @typedef {{ readonly occurredAt: string; readonly payload: { readonly state?: string }; readonly type: "device-cleanup.changed" }} DeviceCleanupDomainEvent */
 /** @typedef {DomainEvent | DeviceCleanupDomainEvent} ProtocolDomainEvent */
 /** @typedef {CoreKernelEventType | "device-cleanup.changed"} ProtocolCoreKernelEventType */
@@ -36,6 +37,12 @@ export function serializeRpcRequest(request) {
             return stringify({ appName: request.appName, id: request.id, type: request.type });
         case "stage.open-session":
             return stringify({ appName: request.appName, id: request.id, manifestSha256: request.manifestSha256, ...(request.surfaceId === undefined ? {} : { surfaceId: request.surfaceId }), type: request.type });
+        case "stage.command":
+            return stringify({ id: request.id, name: request.name, payload: request.payload, sessionId: request.sessionId, type: request.type });
+        case "ui.response":
+            return request.ok
+                ? stringify({ id: request.id, ok: true, requestId: request.requestId, type: request.type, value: request.value })
+                : stringify({ error: serializeClientError(request.error), id: request.id, ok: false, requestId: request.requestId, type: request.type });
         case "stage.query":
             return stringify({ id: request.id, name: request.name, params: request.params, sessionId: request.sessionId, type: request.type });
         case "stage.live-query.subscribe":
@@ -74,6 +81,13 @@ export function deserializeRpcRequest(serialized) {
             const surfaceId = optionalStringField(value, "surfaceId");
             return { appName: stringField(value, "appName"), id, manifestSha256: stringField(value, "manifestSha256"), ...(surfaceId === undefined ? {} : { surfaceId }), type };
         }
+        case "stage.command": return { id, name: versionedNameField(value, "name"), payload: jsonField(value, "payload"), sessionId: stringField(value, "sessionId"), type };
+        case "ui.response": {
+            const requestId = stringField(value, "requestId");
+            if (value.ok === true) return { id, ok: true, requestId, type, value: jsonField(value, "value") };
+            if (value.ok === false && isSerializableClientError(value.error)) return { error: deserializeClientError(value.error), id, ok: false, requestId, type };
+            throw new TypeError("Invalid ui.response");
+        }
         case "stage.query": return { id, name: queryNameField(value), params: jsonField(value, "params"), sessionId: stringField(value, "sessionId"), type };
         case "stage.live-query.subscribe": return { id, name: queryNameField(value), params: jsonField(value, "params"), sessionId: stringField(value, "sessionId"), subscriptionId: stringField(value, "subscriptionId"), type };
         case "stage.live-query.unsubscribe": return { id, sessionId: stringField(value, "sessionId"), subscriptionId: stringField(value, "subscriptionId"), type };
@@ -123,10 +137,14 @@ export function deserializeRpcResponse(serialized) {
  * @returns {string}
  */
 export function serializeRpcEvent(event) {
+    if (event.type === "ui.request")
+        return stringify({ name: event.name, payload: event.payload, requestId: event.requestId, type: event.type });
     if (event.type === "live-query.changed")
         return stringify({ diff: projectQueryDiff(event.diff), subscriptionId: event.subscriptionId, type: event.type });
     if (event.type === "live-query.failed")
         return stringify({ message: event.message, subscriptionId: event.subscriptionId, type: event.type });
+    if (event.type === "subscription.state")
+        return stringify({ state: event.state, subscriptionId: event.subscriptionId, type: event.type });
     return stringify({ event: projectDomainEvent(event.event), subscriptionId: event.subscriptionId, type: event.type });
 }
 /**
@@ -135,6 +153,8 @@ export function serializeRpcEvent(event) {
  */
 export function deserializeRpcEvent(serialized) {
     const value = parseRecord(serialized);
+    if (value.type === "ui.request")
+        return { name: versionedNameField(value, "name"), payload: jsonField(value, "payload"), requestId: stringField(value, "requestId"), type: value.type };
     const subscriptionId = stringField(value, "subscriptionId");
     if (value.type === "live-query.changed")
         return { diff: queryDiffField(value), subscriptionId, type: value.type };
@@ -142,8 +162,26 @@ export function deserializeRpcEvent(serialized) {
         return { message: stringField(value, "message"), subscriptionId, type: value.type };
     if (value.type === "kernel.event")
         return { event: domainEventField(value), subscriptionId, type: value.type };
+    // Sent to one event subscription only (ADR-039). An older client throws below
+    // and drops it, which is the fallback it already had.
+    if (value.type === "subscription.state")
+        return { state: subscriptionStateField(value), subscriptionId, type: value.type };
     throw new TypeError("Unknown RPC event type");
 }
+/**
+ * @param {JsonObject} value
+ * @returns {SubscriptionState}
+ */
+function subscriptionStateField(value) {
+    const { confirmed, generation, reason, status } = objectField(value, "state");
+    if (typeof confirmed !== "boolean" || !Number.isSafeInteger(generation) || /** @type {number} */ (generation) < 0 ||
+        !["live", "lost", "pending", "refused"].includes(/** @type {string} */ (status)) ||
+        !(reason === undefined || ["resubscribed", "source_restarted", "source_unavailable", "subscribed"].includes(/** @type {string} */ (reason)))) {
+        throw new TypeError("Expected a subscription state");
+    }
+    // Every field was checked against the closed vocabulary just above; this drops any other.
+    return /** @type {SubscriptionState} */ ({ confirmed, generation, ...(reason === undefined ? {} : { reason }), status });
+}
 /**
  * @param {unknown} value
  * @returns {string}
@@ -864,6 +902,9 @@ function entityActionField(value) {
 }
 /**
  * @typedef {| { readonly id: string; readonly name: string; readonly payload: JsonValue; readonly type: "command" }
+ *   | { readonly id: string; readonly name: string; readonly payload: JsonValue; readonly sessionId: string; readonly type: "stage.command" }
+ *   | { readonly id: string; readonly ok: true; readonly requestId: string; readonly type: "ui.response"; readonly value: JsonValue }
+ *   | { readonly error: ClientError; readonly id: string; readonly ok: false; readonly requestId: string; readonly type: "ui.response" }
  *   | { readonly id: string; readonly name: QueryName; readonly params: JsonValue; readonly type: "query" }
  *   | { readonly id: string; readonly name: QueryName; readonly params: JsonValue; readonly subscriptionId: string; readonly type: "live-query.subscribe" }
  *   | { readonly id: string; readonly subscriptionId: string; readonly type: "live-query.unsubscribe" }
@@ -887,6 +928,8 @@ function entityActionField(value) {
  */
 /**
  * @typedef {| { readonly diff: QueryDiff<JsonValue>; readonly subscriptionId: string; readonly type: "live-query.changed" }
+ *   | { readonly name: string; readonly payload: JsonValue; readonly requestId: string; readonly type: "ui.request" }
  *   | { readonly message: string; readonly subscriptionId: string; readonly type: "live-query.failed" }
- *   | { readonly event: ProtocolDomainEvent; readonly subscriptionId: string; readonly type: "kernel.event" }} RpcEvent
+ *   | { readonly event: ProtocolDomainEvent; readonly subscriptionId: string; readonly type: "kernel.event" }
+ *   | { readonly state: SubscriptionState; readonly subscriptionId: string; readonly type: "subscription.state" }} RpcEvent
  */

package/src/stage-context.js

@@ -3,6 +3,8 @@
 /** @typedef {import("@econ-v1/domain").KernelEventType} KernelEventType */
 /** @typedef {import("@econ-v1/domain").QueryName} QueryName */
 /** @typedef {import("./client.js").Unsubscribe} Unsubscribe */
+/** @typedef {import("./client.js").EventSubscribeOptions} EventSubscribeOptions */
+/** @typedef {import("./client.js").EventSubscription} EventSubscription */
 /** @typedef {import("./dialog-contract.js").DialogCenter} DialogCenter */
 /** @typedef {import("./model-picker-contract.js").ModelPickerCenter} ModelPickerCenter */
 /** @typedef {import("./system-notice-contract.js").SystemNoticeCenter} SystemNoticeCenter */
@@ -18,15 +20,17 @@
  *   readonly app: { readonly name: string, readonly version: string },
  *   readonly events: {
  *     publish<T extends KernelEventType>(type: T, payload: import("@econ-v1/domain").KernelEventPayload<T>): Promise<void>,
- *     subscribe<T extends KernelEventType>(type: T, listener: (event: import("@econ-v1/domain").KernelEventByType<T>) => void): Unsubscribe
+ *     subscribe<T extends KernelEventType>(type: T, listener: (event: import("@econ-v1/domain").KernelEventByType<T>) => void, options?: EventSubscribeOptions): EventSubscription
  *   },
  *   invokeCapability<T>(capability: string, payload: unknown): Promise<T>,
  *   liveQuery<T>(name: QueryName, params: unknown, listener: (diff: import("@econ-v1/domain").QueryDiff<T>) => void): Unsubscribe,
+ *   command?: <T>(name: string, payload?: unknown) => Promise<T>,
  *   query<T>(name: QueryName, params: unknown): Promise<T>,
  *   readonly composition?: StageComposition,
  *   readonly stage: StageHost
  * }} StageContextShared */
-/** @typedef {{ navigate(path: string): void, readonly root: Element }} StageHostShared */
+/** @typedef {{ open(): void, close(): void, readonly isOpen: boolean, onVisibilityChange(cb: (open: boolean) => void): Unsubscribe, setStatus(text: string): void, setBadge(count: number): void }} AssistantPanelHost */
+/** @typedef {{ navigate(path: string): void, readonly root: Element, readonly context: { set(view: object): void, clear(): void }, readonly panel?: AssistantPanelHost }} StageHostShared */
 /** @typedef {StageContextShared & { readonly host: StageHostShared & { readonly uiApi: 1 } }} StageContextV1 */
 /** @typedef {StageContextShared & { readonly host: StageHostShared & { readonly dialogs: DialogCenter, readonly modelPicker: ModelPickerCenter, readonly systemNotices: SystemNoticeCenter, readonly uiApi: 2 } }} StageContextV2 */
 /** @typedef {StageContextV1 | StageContextV2} StageContext */