@k2b/cloud 0.38.0 → 0.40.0

package/src/browser/CloudResourceSearch.tsx

@@ -44,6 +44,9 @@ export type CloudResourceSearchProps = {
   excludeRefs?: readonly CloudResourceRef[];
 };
 
+/** What `/api/search` accepts as `q`; a prefilled query is cut to it as typing is. */
+const MAX_QUERY_LENGTH = 500;
+
 const isLinkableCommand = (command: PaletteCommand) => typeof command.action !== "function" && "command" in command.action;
 
 const itemKey = (item: SearchItem) => `${item.ref.type}:${item.ref.id}`;
@@ -62,23 +65,24 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
   const locale = useLocale();
   const t = () => resourceSearchMessages.resolve([locale()]).t;
   const id = createUniqueId();
-  const [input, setInput] = createSignal("");
+  const [input, setInput] = createSignal((props.request?.query ?? "").slice(0, MAX_QUERY_LENGTH));
   const [tags, setTags] = createSignal<string[]>([]);
   const [scope, setScope] = createSignal<SearchScope | undefined>(
     props.request?.scope ?? (props.initialAppId ? { appId: props.initialAppId, label: props.initialAppId } : undefined),
   );
   const appId = () => scope()?.appId ?? scope()?.ref?.type.split(".")[0];
   const scopeLabel = () =>
-    !props.request && props.initialAppId
+    !props.request?.scope && props.initialAppId
       ? (catalogApps()?.find((app) => app.id === props.initialAppId)?.name ?? scope()?.label)
       : scope()?.label;
   createEffect(() => {
     const request = props.request;
     if (!request) return;
-    setScope(request.scope);
+    setScope(request.scope ?? (props.initialAppId ? { appId: props.initialAppId, label: props.initialAppId } : undefined));
     if (request.query !== undefined) {
-      setInput(request.query);
-      setCaret(request.query.length);
+      const query = request.query.slice(0, MAX_QUERY_LENGTH);
+      setInput(query);
+      setCaret(query.length);
     }
     setTags([]);
     setBrowsingTags(false);
@@ -556,7 +560,7 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
             autocomplete="off"
             autocapitalize="off"
             spellcheck={false}
-            maxLength={500}
+            maxLength={MAX_QUERY_LENGTH}
           />
         </div>
       </label>

package/src/browser/app-approval.ts

@@ -7,10 +7,19 @@ import {
   APP_ACTION_LIMITS,
   APP_APPROVAL_LIMITS,
   APP_APPROVAL_PATH,
+  APP_APPROVAL_PENDING_ACCEPT,
   APP_APPROVAL_PROTOCOL,
   type AppActionView,
   AppActionViewSchema,
+  type AppApprovalAccept,
+  type AppApprovalPendingAccept,
+  type AppDeviceChange,
+  AppDeviceChangeSchema,
   AppDeviceCommandSchema,
+  type AppDeviceInbox,
+  AppDeviceInboxSchema,
+  type AppDeviceInboxWithChanges,
+  AppDeviceInboxWithChangesSchema,
   AppDeviceProofSchema,
   type AppDevicePublicKey,
   AppDevicePublicKeySchema,
@@ -196,7 +205,8 @@ const connect = async (options: {
       );
     },
     pairingResult: (payload: AppPairingPayload, key: AppApprovalKey, signal?: AbortSignal) => {
-      const p = pairing(payload);
+      const p = AppPairingPayloadSchema.parse(payload);
+      if (p.issuer !== issuer) throw new AppApprovalClientError("INVALID_INPUT");
       return request(
         "/pairings/result",
         AppPairingResultSchema,
@@ -204,8 +214,10 @@ const connect = async (options: {
         signal,
       );
     },
-    pending: async (device: AppApprovalDevice, signal?: AbortSignal) => {
-      const result = await command(device, { operation: "pending" }, signal);
+    pending: async (device: AppApprovalDevice, signal?: AbortSignal, options?: { accept?: AppApprovalPendingAccept[] }) => {
+      // Untyped callers may reuse their inbox list; drop what pending does not serve instead of failing every poll.
+      const accept = options?.accept?.filter((entry) => APP_APPROVAL_PENDING_ACCEPT.includes(entry) && info.features?.includes(entry));
+      const result = await command(device, { operation: "pending", ...(accept?.length ? { accept } : {}) }, signal);
       if (!("requests" in result)) throw new AppApprovalClientError("INVALID_RESPONSE");
       return result;
     },
@@ -223,10 +235,48 @@ const connect = async (options: {
     },
     /** Whether this Cloud serves `inbox`, `action` and `act`. Older Clouds answer those commands with HTTP 400. */
     actions: info.features?.includes("actions") === true,
+    /** Whether this Cloud can include terminal consent in an explicitly opted-in inbox. */
+    terminalLogins: info.features?.includes("terminal-logins") === true,
+    /** Whether this Cloud serves sign-in context through a signed opt-in. */
+    loginContext: info.features?.includes("login-context") === true,
+    /** Whether this Cloud lists requests to pair or remove a device in an inbox that accepts `device-changes`. */
+    deviceChanges: info.features?.includes("device-changes") === true,
     /** Pending sign-ins and the newest open Action approvals in one call; use it instead of `pending` where `actions` is true. */
-    inbox: async (device: AppApprovalDevice, signal?: AbortSignal) => {
-      const result = await command(device, { operation: "inbox" }, signal);
-      if (!("actions" in result)) throw new AppApprovalClientError("INVALID_RESPONSE");
+    inbox: async (
+      device: AppApprovalDevice,
+      signal?: AbortSignal,
+      options?: { accept?: AppApprovalAccept[] },
+    ): Promise<AppDeviceInbox | AppDeviceInboxWithChanges> => {
+      // SDK upgrades alone must not expose consent the app cannot show. Old Clouds never see the new key.
+      const accept = options?.accept?.filter((entry) => info.features?.includes(entry));
+      const result = await command(device, { operation: "inbox", ...(accept?.length ? { accept } : {}) }, signal);
+      if (!("actions" in result) || (accept?.includes("device-changes") && (!("changes" in result) || !("moreChanges" in result))))
+        throw new AppApprovalClientError("INVALID_RESPONSE");
+      return "changes" in result ? AppDeviceInboxWithChangesSchema.parse(result) : AppDeviceInboxSchema.parse(result);
+    },
+    /**
+     * Signs a decision on one entry of `changes`, a request to pair or remove a device of this account. Only call it on an
+     * explicit choice of the person. The device being removed can approve its own removal; its `deny` throws
+     * `AppApprovalClientError` with code `HTTP` and status 409.
+     */
+    decideChange: async (device: AppApprovalDevice, change: AppDeviceChange, decision: "approve" | "deny", signal?: AbortSignal) => {
+      const parsed = AppDeviceChangeSchema.safeParse(change);
+      if (!parsed.success || Date.parse(parsed.data.expiresAt) <= Date.now()) throw new AppApprovalClientError("INVALID_INPUT");
+      change = parsed.data;
+      const result = await command(
+        device,
+        {
+          operation: "change",
+          changeId: change.changeId,
+          kind: change.kind,
+          targetId: change.device.id,
+          endSessions: change.endSessions,
+          decision,
+        },
+        signal,
+      );
+      if (!("state" in result) || result.state !== (decision === "approve" ? "approved" : "denied"))
+        throw new AppApprovalClientError("INVALID_RESPONSE");
       return result;
     },
     /** One open Action approval. The digest is recomputed here, so a view that does not match it is never returned. */
@@ -258,6 +308,10 @@ const connect = async (options: {
       if (!("state" in result) || result.state !== "updated") throw new AppApprovalClientError("INVALID_RESPONSE");
       return result;
     },
+    /**
+     * Removes this device itself at once, without approval from a paired device. Sign-ins it approved stay signed in.
+     * Removing a device from Cloud in the browser waits for a paired device to approve instead.
+     */
     revoke: async (device: AppApprovalDevice, signal?: AbortSignal) => {
       const result = await command(device, { operation: "revoke" }, signal);
       if (!("state" in result) || result.state !== "revoked") throw new AppApprovalClientError("INVALID_RESPONSE");

package/src/browser/commands.ts

@@ -14,17 +14,33 @@ export type { CommandOptions } from "../contracts/commands";
 export type { CommandTarget, ContextAwareCommand } from "./command-bridge";
 export { registerCommandHandler, registerContextAwareCommand } from "./command-bridge";
 
-/** Opens locally only when a mounted owner explicitly accepts; otherwise follows the app's URL. */
-export const openCommand = async (command: string, input: unknown = {}, options: CommandOptions = {}): Promise<void> => {
+/**
+ * Opens locally only when a mounted owner accepts; otherwise follows the app's URL.
+ * Resolves true after the owner's handler resolves or navigation starts.
+ * Resolves false if code cannot load (with a reload notice) or `signal` aborts before handling or while resolving the link.
+ * An accepting owner takes over without the signal. Handler rejections and link resolution failures still reject.
+ */
+export const openCommand = async (
+  command: string,
+  input: unknown = {},
+  options: CommandOptions = {},
+  signal?: AbortSignal,
+): Promise<boolean> => {
   const modules = await importOnDemand(() => Promise.all([import("../contracts/commands"), import("../capabilities/client")]));
-  if (!modules) return;
+  if (!modules || signal?.aborted) return false;
   const [contracts, capabilities] = modules;
   const parsedOptions = contracts.CommandOptionsSchema.parse(options);
   const handled = requestCommandHandling({ command, input, options: parsedOptions });
-  if (handled) return handled;
-  const result = await capabilities.resolveCommand(command, input, parsedOptions);
-  if (!result.ok) throw new Error(result.error.message);
+  if (handled) {
+    await handled;
+    return true;
+  }
+  // An abort also ends the request, so a cancelled opening does not wait for its answer.
+  const result = await capabilities.resolveCommand(command, input, parsedOptions, { signal });
+  if (signal?.aborted) return false;
+  if (!result.ok) throw new Error(result.error.message, { cause: result.error });
   window.location.assign(result.data.href);
+  return true;
 };
 
 /** Call after this page's handlers have mounted. Each entry is consumed, including invalid links. */

package/src/browser/composer-catalog.ts

@@ -0,0 +1,145 @@
+import type { ChatCommandSearch } from "@k2b/ui";
+import { createSignal } from "solid-js";
+import { listCapabilityCatalog } from "../capabilities/client";
+import { LOCALE_HEADER } from "../shared/locale";
+import { discoverableCommandInput } from "./discoverable-command";
+import { navigationApps } from "./navigation-apps";
+
+export type CloudSearchTag = {
+  appId: string;
+  appName: string;
+  appIcon: string;
+  tag: string;
+  title: string;
+  description: string;
+  aliases: readonly string[];
+};
+
+export type CloudComposerCommand = {
+  id: string;
+  appId: string;
+  appName: string;
+  appIcon: string;
+  title: string;
+  description: string;
+  icon: string;
+  keywords: readonly string[];
+  input: unknown;
+};
+
+/**
+ * What composers read from the page's one Capability catalog load. It leaves out the tags of apps without a resource
+ * reader: a picker that requires one can show none of their results. A composer that reads such a type itself adds its
+ * tag on its own and names the type in `cloudInsertMenu`'s `ownReaders`.
+ */
+export type CloudComposerCatalog = { tags: readonly CloudSearchTag[]; commands: readonly CloudComposerCommand[] };
+export type CloudComposerCatalogState = "loading" | "ready" | "failed";
+
+/** The budget of one Capability query (and of resolving a Command), applied to each catalog page. */
+const CATALOG_PAGE_TIMEOUT_MS = 15_000;
+
+const catalogs = new Map<string, Promise<CloudComposerCatalog>>();
+
+const loadCatalog = async (locale: string): Promise<CloudComposerCatalog> => {
+  const tags: CloudSearchTag[] = [];
+  const commands: CloudComposerCommand[] = [];
+  const { appIds, currentAppId } = navigationApps();
+  const seen = new Set<string>();
+  let cursor: string | undefined;
+  do {
+    // A page that never answers fails like any other, so the load is forgotten and the next opening asks again.
+    const result = await listCapabilityCatalog({
+      limit: 25,
+      cursor,
+      headers: { [LOCALE_HEADER]: locale },
+      signal: AbortSignal.timeout(CATALOG_PAGE_TIMEOUT_MS),
+    });
+    if (!result.ok) throw new Error(result.error.message);
+    for (const app of result.data.apps) {
+      if (app.appId !== currentAppId) {
+        for (const command of app.manifest.commands) {
+          const input = discoverableCommandInput(command, app.appId, appIds);
+          if (!input?.success) continue;
+          commands.push({
+            id: `${app.appId}.${command.localId}`,
+            appId: app.appId,
+            appName: app.appName,
+            appIcon: app.appIcon,
+            title: command.title,
+            description: command.description,
+            icon: command.icon ?? app.appIcon,
+            keywords: command.keywords,
+            input: input.data,
+          });
+        }
+      }
+      if (!app.manifest.types.some((type) => type.reader)) continue;
+      for (const query of app.manifest.queries) {
+        for (const tag of query.universalSearch?.tags ?? []) {
+          const key = `${app.appId}\u0000${tag.tag}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          tags.push({ appId: app.appId, appName: app.appName, appIcon: app.appIcon, ...tag, aliases: tag.aliases ?? [] });
+        }
+      }
+    }
+    const next = result.data.page.hasMore ? result.data.page.nextCursor : undefined;
+    if (next && cursor && next <= cursor) throw new Error("Invalid Composer catalog cursor");
+    cursor = next;
+  } while (cursor);
+  return { tags, commands };
+};
+
+/**
+ * One catalog load per page and locale, shared by every composer on the page. A failed load is forgotten,
+ * so the next menu opening can try again; nothing polls or retries on its own.
+ */
+export const loadCloudComposerCatalog = (locale: string): Promise<CloudComposerCatalog> => {
+  const cached = catalogs.get(locale);
+  if (cached) return cached;
+  const pending = loadCatalog(locale).catch((error: unknown) => {
+    if (catalogs.get(locale) === pending) catalogs.delete(locale);
+    throw error;
+  });
+  catalogs.set(locale, pending);
+  return pending;
+};
+
+/**
+ * The search tags, Commands, and load state of one composer. Call `ready` at the start of every `searchCommands` run: each menu opening starts
+ * the shared load once, so only the first opening, or one after a failure, sends a request, and no keystroke does.
+ * A search with typed text and no scope waits for that answer, so "/notiz" never settles as "nothing found" before its
+ * tag arrives. The overview and scoped searches do not wait, and after a failed load no search waits again; a later
+ * success still brings the tags in. A failure keeps the tags the composer had.
+ */
+export function createCloudComposerCatalog(load: (locale: string) => Promise<CloudComposerCatalog> = loadCloudComposerCatalog) {
+  const [tags, setTags] = createSignal<readonly CloudSearchTag[]>([]);
+  const [commands, setCommands] = createSignal<readonly CloudComposerCommand[]>([]);
+  const [state, setState] = createSignal<CloudComposerCatalogState>("loading");
+  let opening: number | undefined;
+  let settled: Promise<void> = Promise.resolve();
+  let failed = false;
+  return {
+    tags,
+    commands,
+    state,
+    ready(query: string, search: ChatCommandSearch, locale: string): Promise<void> {
+      if (opening !== search.opening) {
+        opening = search.opening;
+        if (state() === "failed") setState("loading");
+        settled = load(locale).then(
+          (catalog) => {
+            setTags(catalog.tags);
+            setCommands(catalog.commands);
+            setState("ready");
+          },
+          () => {
+            failed = true;
+            setState("failed");
+          },
+        );
+      }
+      return failed || search.scope !== undefined || !query.trim() ? Promise.resolve() : settled;
+    },
+  };
+}

package/src/browser/composer-insert-messages.ts

@@ -0,0 +1,31 @@
+import { i18n } from "@k2b/stdlib";
+
+export const composerInsertMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      insertFromCloud: "Insert from Cloud",
+      insertFromCloudHint: "Find something in your apps and insert it",
+      insertTag: ({ tag }: { tag: string }) => `Insert ${tag}`,
+      chooseFrom: ({ app }: { app: string }) => `Choose from ${app}`,
+      tagFromApp: ({ tag, app }: { tag: string; app: string }) => `${tag} from ${app}`,
+      searchTagFor: ({ tag, query }: { tag: string; query: string }) => `Search ${tag} for “${query}”`,
+      searchTag: ({ tag }: { tag: string }) => `Search ${tag}`,
+      fromAppWithPreview: ({ app }: { app: string }) => `From ${app}, with preview`,
+      searchCloudFor: ({ query }: { query: string }) => `Search Cloud for “${query}”`,
+      searchAllApps: "Search all apps for content",
+    },
+    de: {
+      insertFromCloud: "Aus Cloud einfügen",
+      insertFromCloudHint: "Etwas aus deinen Apps suchen und einfügen",
+      insertTag: ({ tag }) => `${tag} einfügen`,
+      chooseFrom: ({ app }) => `Aus ${app} wählen`,
+      tagFromApp: ({ tag, app }) => `${tag} aus ${app}`,
+      searchTagFor: ({ tag, query }) => `„${query}“ in ${tag} suchen`,
+      searchTag: ({ tag }) => `${tag} durchsuchen`,
+      fromAppWithPreview: ({ app }) => `Aus ${app}, mit Vorschau`,
+      searchCloudFor: ({ query }) => `„${query}“ in Cloud suchen`,
+      searchAllApps: "In allen Apps nach Inhalten suchen",
+    },
+  },
+});

package/src/browser/composer-insert.ts

@@ -0,0 +1,160 @@
+import type { ChatAttachment, ChatCommand, ChatCommandResult, ChatCommandScope } from "@k2b/ui";
+import type { CloudResourceRef } from "../contracts";
+import type { CloudSearchTag } from "./composer-catalog";
+import { composerInsertMessages } from "./composer-insert-messages";
+import { type CloudResourcePickerItem, openCloudResourcePicker } from "./resource-picker";
+
+export {
+  type CloudComposerCatalog,
+  type CloudComposerCatalogState,
+  type CloudComposerCommand,
+  type CloudSearchTag,
+  createCloudComposerCatalog,
+  loadCloudComposerCatalog,
+} from "./composer-catalog";
+
+export {
+  type CloudCommandMenu,
+  type CloudCommandMenuOptions,
+  cloudCommandMenu,
+  type OpenComposerCommandOptions,
+  openComposerCommand,
+} from "./composer-open";
+
+export type CloudInsertMenuOptions = {
+  locale: string;
+  /** Every app's search tags, from `loadCloudComposerCatalog`. */
+  tags: readonly CloudSearchTag[];
+  /** Section of the rows in the composer's slash list. */
+  section?: string;
+  /** Turns the chosen resource into the reference the composer puts where `/…` was. */
+  mention: (item: CloudResourcePickerItem) => ChatAttachment;
+  /** References the draft already holds; the picker leaves them out. Read when the picker opens. */
+  excludeRefs?: () => readonly CloudResourceRef[];
+  /** Why nothing can be inserted now, such as a full message; it replaces each row's description. */
+  reason?: string;
+  /** First words of the composer's own scopes. A tag never claims them, so they keep narrowing as before. */
+  reservedWords?: readonly string[];
+  /** More first words for one tag, keyed `appId:tag`, such as a short word an app uses for its own tag. */
+  scopeWords?: Readonly<Record<string, readonly string[]>>;
+  /**
+   * Tags, keyed `appId:tag`, whose resources of one type this composer reads itself, such as
+   * `{ "assistant:studio-app": "assistant.app" }`. Their picker lists only that type, also without a Cloud reader, even
+   * after the person removes the scope chip. Every other picker lists only resources with a reader (`requireReader`).
+   */
+  ownReaders?: Readonly<Record<string, string>>;
+};
+
+export type CloudInsertMenu = {
+  /** "Insert from Cloud": the picker across all apps. */
+  insert: ChatCommand;
+  /** One row per search tag, only while searching. Enter opens the picker narrowed to the tag; Tab narrows the list. */
+  tags: ChatCommand[];
+  /** One scope per tag that keeps a first word of its own, titled like "Notes from Notebooks". */
+  scopes: ChatCommandScope[];
+  /** For the composer's `commandFallback`: "Search Notes for “q3”" in a tag scope, "Search Cloud for “q3”" otherwise. */
+  fallback: (search: { query: string; scope?: string }) => ChatCommand | undefined;
+};
+
+const fold = (text: string) => text.toLowerCase().normalize("NFD").replace(/\p{M}/gu, "").replace(/ß/g, "ss");
+const tagKey = (tag: Pick<CloudSearchTag, "appId" | "tag">) => `${tag.appId}:${tag.tag}`;
+const scopeId = (tag: Pick<CloudSearchTag, "appId" | "tag">) => `cloud-tag:${tagKey(tag)}`;
+
+/**
+ * Slash-list rows that insert Cloud content the person can read. Every row opens the resource picker, narrowed on the
+ * server to an app and tag when it has one, and hands the chosen item back as a `mention` for the token's place.
+ */
+export const cloudInsertMenu = (options: CloudInsertMenuOptions): CloudInsertMenu => {
+  const t = composerInsertMessages.resolve([options.locale]).t;
+  const pick = async (tag: CloudSearchTag | undefined, query: string): Promise<ChatCommandResult> => {
+    const ownType = tag ? options.ownReaders?.[tagKey(tag)] : undefined;
+    const item = await openCloudResourcePicker({
+      title: tag ? t.insertTag({ tag: tag.title }) : t.insertFromCloud,
+      scope: tag ? { appId: tag.appId, tag: tag.tag, label: `${tag.title} · ${tag.appName}`, icon: tag.appIcon } : undefined,
+      query: query || undefined,
+      ...(ownType ? { resourceType: ownType } : { requireReader: true }),
+      excludeRefs: options.excludeRefs?.(),
+    });
+    return item ? { mention: options.mention(item) } : "cancelled";
+  };
+
+  const reserved = new Set((options.reservedWords ?? []).map(fold));
+  // The title comes first, so Tab writes the word the person reads ("notizen ").
+  const candidates = options.tags.map((tag) => {
+    const title = fold(tag.title);
+    return [
+      ...new Set(
+        [...(/\s/.test(title) ? [] : [title]), tag.tag, ...tag.aliases, ...(options.scopeWords?.[tagKey(tag)] ?? [])]
+          .map(fold)
+          .filter((word) => word && !/\s/.test(word) && !reserved.has(word)),
+      ),
+    ];
+  });
+  // A word two tags share narrows to neither, so Tab on either row would leave the list unscoped; neither keeps it.
+  const uses = new Map<string, number>();
+  for (const word of candidates.flat()) uses.set(word, (uses.get(word) ?? 0) + 1);
+  const scoped = new Map<string, CloudSearchTag>();
+  const scopes: ChatCommandScope[] = [];
+  const tags = options.tags.map((tag, index): ChatCommand => {
+    const words = candidates[index]!.filter((word) => uses.get(word) === 1);
+    if (words.length) {
+      scoped.set(scopeId(tag), tag);
+      scopes.push({ id: scopeId(tag), title: t.tagFromApp({ tag: tag.title, app: tag.appName }), words });
+    }
+    return {
+      id: scopeId(tag),
+      section: options.section,
+      name: tag.tag,
+      label: tag.title,
+      description: t.chooseFrom({ app: tag.appName }),
+      icon: tag.appIcon,
+      keywords: [tag.title, tag.appName, tag.tag, ...tag.aliases, ...(options.scopeWords?.[tagKey(tag)] ?? [])],
+      app: tag.appName,
+      scope: words.length ? scopeId(tag) : undefined,
+      hiddenUntilSearch: true,
+      reason: options.reason,
+      action: () => pick(tag, ""),
+    };
+  });
+
+  return {
+    insert: {
+      id: "cloud-insert",
+      section: options.section,
+      name: "cloud",
+      label: t.insertFromCloud,
+      description: t.insertFromCloudHint,
+      icon: "ti ti-cloud-search",
+      keywords: ["cloud", "insert", "einfügen", "inhalt", "content", "ressource", "resource", "verweis", "reference", "link"],
+      reason: options.reason,
+      action: () => pick(undefined, ""),
+    },
+    tags,
+    scopes,
+    fallback: ({ query, scope }) => {
+      if (scope !== undefined) {
+        const tag = scoped.get(scope);
+        if (!tag) return undefined;
+        return {
+          id: `cloud-search:${tagKey(tag)}`,
+          name: `cloud-search:${tagKey(tag)}`,
+          label: query ? t.searchTagFor({ tag: tag.title, query }) : t.searchTag({ tag: tag.title }),
+          description: t.fromAppWithPreview({ app: tag.appName }),
+          icon: "ti ti-search",
+          reason: options.reason,
+          action: () => pick(tag, query),
+        };
+      }
+      if (!query) return undefined;
+      return {
+        id: "cloud-search",
+        name: "cloud-search",
+        label: t.searchCloudFor({ query }),
+        description: t.searchAllApps,
+        icon: "ti ti-search",
+        reason: options.reason,
+        action: () => pick(undefined, query),
+      };
+    },
+  };
+};

package/src/browser/composer-open-messages.ts

@@ -0,0 +1,17 @@
+import { i18n } from "@k2b/stdlib";
+
+export const composerOpenMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      appUnavailable: ({ app }: { app: string }) => `${app} is not reachable right now. Choose it again to try once more.`,
+      commandsFailed: "Commands from apps could not be loaded",
+      tryAgain: "Try again",
+    },
+    de: {
+      appUnavailable: ({ app }) => `${app} ist gerade nicht erreichbar. Erneut wählen versucht es nochmal.`,
+      commandsFailed: "Befehle aus Apps konnten nicht geladen werden",
+      tryAgain: "Erneut versuchen",
+    },
+  },
+});

package/src/browser/composer-open.ts

@@ -0,0 +1,110 @@
+import type { ChatCommand, ChatCommandDraft, ChatCommandOpenResult } from "@k2b/ui";
+import { CAPABILITY_FRAMEWORK_ERROR_CODES } from "../contracts/capabilities";
+import { isCommandPath } from "../contracts/command-path";
+import { openCommand } from "./commands";
+import type { CloudComposerCatalogState, CloudComposerCommand } from "./composer-catalog";
+import { composerOpenMessages } from "./composer-open-messages";
+
+export type OpenComposerCommandOptions = {
+  before: () => Promise<void>;
+  returnTo: () => string | undefined;
+  /** Read after `before`; once it aborts, for example because the person left the chat, nothing opens. */
+  signal?: () => AbortSignal | undefined;
+  locale: string;
+};
+
+/**
+ * Save first, then resolve and open. If nothing opens, cancel so the composer keeps its token and restores the live draft.
+ * Save errors reach the status line; resolution errors stay on the retryable row.
+ */
+export const openComposerCommand = async (
+  command: CloudComposerCommand,
+  options: OpenComposerCommandOptions,
+): Promise<ChatCommandOpenResult> => {
+  await options.before();
+  const signal = options.signal?.();
+  if (signal?.aborted) return "cancelled";
+  const returnTo = options.returnTo();
+  if (returnTo !== undefined && !isCommandPath(returnTo)) throw new Error("Invalid Command return path");
+  try {
+    if (!(await openCommand(command.id, command.input, { returnTo }, signal))) return "cancelled";
+  } catch (error) {
+    if (signal?.aborted) return "cancelled";
+    const cause = error instanceof Error ? error.cause : undefined;
+    if (
+      typeof cause === "object" &&
+      cause !== null &&
+      "code" in cause &&
+      typeof cause.code === "string" &&
+      "status" in cause &&
+      typeof cause.status === "number" &&
+      "message" in cause &&
+      typeof cause.message === "string" &&
+      cause.code !== CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable &&
+      ![502, 503, 504].includes(cause.status) &&
+      cause.message
+    ) {
+      return { failed: cause.message };
+    }
+    return { failed: composerOpenMessages.resolve([options.locale]).t.appUnavailable({ app: command.appName }) };
+  }
+  if (signal?.aborted) return "cancelled";
+};
+
+export type CloudCommandMenuOptions = {
+  locale: string;
+  commands: readonly CloudComposerCommand[];
+  state: CloudComposerCatalogState;
+  section?: string;
+  before: (draft: ChatCommandDraft, signal: AbortSignal, follow: () => void) => Promise<void>;
+  returnTo: () => string | undefined;
+  /** See `OpenComposerCommandOptions.signal`. */
+  signal?: () => AbortSignal | undefined;
+};
+export type CloudCommandMenu = { commands: ChatCommand[]; pending: boolean };
+
+/** Put this section last. Pending placeholders reserve its end; a failed catalog offers one explicit reload. */
+export const cloudCommandMenu = (options: CloudCommandMenuOptions): CloudCommandMenu => {
+  const t = composerOpenMessages.resolve([options.locale]).t;
+  if (options.state === "loading") return { commands: [], pending: true };
+  if (options.state === "failed")
+    return {
+      commands: [
+        {
+          id: "cloud-commands-retry",
+          name: "cloud-commands-retry",
+          label: t.commandsFailed,
+          description: t.tryAgain,
+          icon: "ti ti-alert-circle",
+          searchAgain: true,
+          persistent: true,
+          section: options.section,
+        },
+      ],
+      pending: false,
+    };
+  return {
+    commands: options.commands.map((command) => ({
+      id: `cloud-command:${command.id}`,
+      name: command.id,
+      label: command.title,
+      description: `${command.appName} · ${command.description}`,
+      icon: command.icon,
+      keywords: [command.title, ...command.keywords, command.appName, command.description],
+      app: command.appName,
+      section: options.section,
+      // The composer's signal aborts when the person closes the list; the opener's, when it leaves the chat.
+      open: (draft, closed, follow) =>
+        openComposerCommand(command, {
+          before: () => options.before(draft, closed, follow),
+          returnTo: options.returnTo,
+          signal: () => {
+            const left = options.signal?.();
+            return left ? AbortSignal.any([closed, left]) : closed;
+          },
+          locale: options.locale,
+        }),
+    })),
+    pending: false,
+  };
+};

package/src/browser/discoverable-command.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+import type { CapabilityCommandManifest } from "../contracts/capabilities";
+
+/** Shared discovery rule for the palette and composers; it grants no access to the destination. */
+export const discoverableCommandInput = (command: CapabilityCommandManifest, appId: string, appIds: ReadonlySet<string>) =>
+  appIds.has(appId) ? z.fromJSONSchema(structuredClone(command.inputSchema)).safeParse({}) : undefined;