@k2b/cloud 0.38.0 → 0.39.0

package/src/api/admin-core-settings.ts

@@ -46,9 +46,10 @@ const BulkSaveSchema = z.union([
     .object({
       updates: z.record(z.string(), z.unknown()).optional().default({}),
       resets: z.array(z.string()).optional().default([]),
+      replaceUnreadable: z.array(z.string()).optional().default([]),
     })
     .strict(),
-  z.record(z.string(), z.unknown()).transform((updates) => ({ updates, resets: [] as string[] })),
+  z.record(z.string(), z.unknown()).transform((updates) => ({ updates, resets: [] as string[], replaceUnreadable: [] as string[] })),
 ]);
 const LEGAL_DOCUMENTS = [
   { kind: "terms", path: "/legal/terms" },
@@ -58,6 +59,13 @@ const LEGAL_DOCUMENTS = [
 
 type FieldErrors = Record<string, string>;
 
+const unreadableSettingMessage = (locale: string): string =>
+  locale.startsWith("de")
+    ? "Der gespeicherte Wert kann von dieser Anwendung nicht gelesen werden. Ersetze ihn ausdrücklich oder nutze den Standardwert."
+    : "The stored value cannot be read by this application. Replace it explicitly or use the default.";
+const settingsNotSavedMessage = (locale: string): string =>
+  locale.startsWith("de") ? "Die Einstellungen wurden nicht gespeichert." : "The settings were not saved.";
+
 const isKnownSetting = (key: string): boolean => SETTINGS_MAP.has(key);
 
 const AI_PROFILES_KEY = "ai.model_profiles_json";
@@ -335,168 +343,211 @@ const app = new Hono<AuthContext>()
     if (result.ok) return c.json({ ok: true });
     return c.json({ message: result.error, kind: result.kind }, result.status);
   })
-  .put("/", auth.requireRole("admin"), v("json", BulkSaveSchema), async (c) => {
-    const { updates, resets } = c.req.valid("json");
-    const updateKeys = Object.keys(updates);
-    const keys = [...updateKeys, ...resets];
+  .put(
+    "/",
+    auth.requireRole("admin"),
+    describeRoute({
+      tags: ["Administration"],
+      summary: "Save platform settings",
+      ...requiresAdmin,
+      responses: {
+        204: { description: "Settings saved" },
+        400: jsonResponse(z.object({ message: z.string(), errors: z.record(z.string(), z.string()).optional() }), "Invalid settings"),
+        409: jsonResponse(
+          z.object({ message: z.string(), errors: z.record(z.string(), z.string()), code: z.literal("setting_unreadable").optional() }),
+          "Stored setting unreadable or model access conflict",
+        ),
+      },
+    }),
+    v("json", BulkSaveSchema),
+    async (c) => {
+      const { updates, resets, replaceUnreadable } = c.req.valid("json");
+      const replace = new Set(replaceUnreadable);
+      const updateKeys = Object.keys(updates);
+      const keys = [...updateKeys, ...resets];
 
-    if (keys.length === 0) {
-      return c.body(null, 204);
-    }
+      if (keys.length === 0 && replace.size === 0) {
+        return c.body(null, 204);
+      }
 
-    const ownership: FieldErrors = {};
-    for (const key of keys) {
-      if (!isKnownSetting(key)) {
-        ownership[key] = `Unknown setting "${key}"`;
+      const ownership: FieldErrors = {};
+      for (const key of keys) {
+        if (!isKnownSetting(key)) {
+          ownership[key] = `Unknown setting "${key}"`;
+        }
       }
-    }
-    for (const key of resets) {
-      if (key in updates) {
-        ownership[key] = `Setting "${key}" cannot be updated and reset in the same save`;
+      for (const key of replace) {
+        if (!Object.hasOwn(updates, key)) ownership[key] = `Setting "${key}" must be included in updates to replace its unreadable value`;
+      }
+      for (const key of resets) {
+        if (key in updates) {
+          ownership[key] = `Setting "${key}" cannot be updated and reset in the same save`;
+        }
+      }
+      if (Object.keys(ownership).length > 0) {
+        return c.json({ message: "Invalid keys", errors: ownership }, 400);
       }
-    }
-    if (Object.keys(ownership).length > 0) {
-      return c.json({ message: "Invalid keys", errors: ownership }, 400);
-    }
 
-    // Strip AI provider keys before anything is validated or written, so the
-    // value that gets checked is the value that gets stored.
-    const aiSplit = AI_PROFILES_KEY in updates ? splitAiProfileCredentials(updates[AI_PROFILES_KEY]) : null;
-    if (AI_PROFILES_KEY in updates && !aiSplit) {
-      // Unsplittable means the keys could not be separated out, and storing the
-      // value as posted would put them back in a setting the browser reads.
-      return c.json({ message: "Invalid values", errors: { [AI_PROFILES_KEY]: "Model profiles must be a JSON array" } }, 400);
-    }
-    let accessChanges: AiModelAccessChange[] = [];
-    if (aiSplit) {
-      try {
-        aiSplit.profilesJson = prepareAiModelProfileImages(aiSplit.profilesJson);
-      } catch (error) {
-        if (error instanceof ImageMetadataError)
-          return c.json({ message: error.message, code: error.code, errors: { [AI_PROFILES_KEY]: error.message } }, 422);
-        throw error;
+      const states = await settings.readStates(updateKeys);
+      const unreadable: FieldErrors = {};
+      for (const key of updateKeys) {
+        if (states.get(key)?.stored === "unreadable" && !replace.has(key)) unreadable[key] = unreadableSettingMessage(getLocale(c));
       }
-      try {
-        const split = splitAiModelAccess(aiSplit.profilesJson);
-        aiSplit.profilesJson = split.profilesJson;
-        accessChanges = split.changes;
-      } catch {
-        return c.json(
-          {
-            message: "Invalid model permissions",
-            errors: { [AI_PROFILES_KEY]: "Invalid Assistant model permissions. Reload the settings and try again." },
-          },
-          400,
-        );
+      if (Object.keys(unreadable).length > 0) {
+        return c.json({ message: settingsNotSavedMessage(getLocale(c)), errors: unreadable, code: "setting_unreadable" }, 409);
       }
-    }
-    const finalValues: Record<string, unknown> = aiSplit ? { ...updates, [AI_PROFILES_KEY]: aiSplit.profilesJson } : updates;
 
-    // Validate everything up front. settings.set validates as it writes, so a
-    // single bad field used to leave the earlier keys already saved — with the
-    // AI profiles among them, whose save also prunes credentials.
-    const invalid: FieldErrors = {};
-    const validatedValues: Record<string, unknown> = {};
-    for (const [key, value] of Object.entries(finalValues)) {
-      const def = SETTINGS_MAP.get(key);
-      if (!def) continue;
-      const validated = validateSettingValue(def, value);
-      if (validated.ok) validatedValues[key] = validated.value;
-      else invalid[key] = validated.error;
-      if (key === "freeipa.ca_cert") {
-        const certificate = validateFreeIpaCaCert(value);
-        if (!certificate.ok) invalid[key] = certificate.error;
+      // Strip AI provider keys before anything is validated or written, so the
+      // value that gets checked is the value that gets stored.
+      const aiSplit = AI_PROFILES_KEY in updates ? splitAiProfileCredentials(updates[AI_PROFILES_KEY]) : null;
+      if (AI_PROFILES_KEY in updates && !aiSplit) {
+        // Unsplittable means the keys could not be separated out, and storing the
+        // value as posted would put them back in a setting the browser reads.
+        return c.json({ message: "Invalid values", errors: { [AI_PROFILES_KEY]: "Model profiles must be a JSON array" } }, 400);
       }
-      if (INTEGER_FREEIPA_SETTINGS.has(key) && (typeof value !== "number" || !Number.isInteger(value))) {
-        invalid[key] = "Value must be a whole number";
+      let accessChanges: AiModelAccessChange[] = [];
+      if (aiSplit) {
+        try {
+          aiSplit.profilesJson = prepareAiModelProfileImages(aiSplit.profilesJson);
+        } catch (error) {
+          if (error instanceof ImageMetadataError)
+            return c.json({ message: error.message, code: error.code, errors: { [AI_PROFILES_KEY]: error.message } }, 422);
+          throw error;
+        }
+        try {
+          const split = splitAiModelAccess(aiSplit.profilesJson);
+          aiSplit.profilesJson = split.profilesJson;
+          accessChanges = split.changes;
+        } catch {
+          return c.json(
+            {
+              message: "Invalid model permissions",
+              errors: { [AI_PROFILES_KEY]: "Invalid Assistant model permissions. Reload the settings and try again." },
+            },
+            400,
+          );
+        }
       }
-    }
-    if (Object.keys(invalid).length > 0) {
-      return c.json({ message: "Invalid values", errors: invalid }, 400);
-    }
+      const finalValues: Record<string, unknown> = aiSplit ? { ...updates, [AI_PROFILES_KEY]: aiSplit.profilesJson } : updates;
 
-    let aiPlan: AiSettingsMutationPlan;
-    try {
-      aiPlan = await prepareAiSettingsMutation(validatedValues, resets, aiSplit, getLocale(c));
-    } catch (error) {
-      console.error("[settings] failed to validate the prospective AI configuration", error);
-      return c.json({ message: "Failed to validate AI settings" }, 500);
-    }
-    if (Object.keys(aiPlan.errors).length > 0) {
-      return c.json({ message: aiSettingsNotSavedMessage(getLocale(c)), errors: aiPlan.errors, issues: aiPlan.issues ?? [] }, 400);
-    }
+      // Validate everything up front. settings.set validates as it writes, so a
+      // single bad field used to leave the earlier keys already saved — with the
+      // AI profiles among them, whose save also prunes credentials.
+      const invalid: FieldErrors = {};
+      const validatedValues: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(finalValues)) {
+        const def = SETTINGS_MAP.get(key);
+        if (!def) continue;
+        const validated = validateSettingValue(def, value);
+        if (validated.ok) validatedValues[key] = validated.value;
+        else invalid[key] = validated.error;
+        if (key === "freeipa.ca_cert") {
+          const certificate = validateFreeIpaCaCert(value);
+          if (!certificate.ok) invalid[key] = certificate.error;
+        }
+        if (INTEGER_FREEIPA_SETTINGS.has(key) && (typeof value !== "number" || !Number.isInteger(value))) {
+          invalid[key] = "Value must be a whole number";
+        }
+      }
+      if (Object.keys(invalid).length > 0) {
+        return c.json({ message: "Invalid values", errors: invalid }, 400);
+      }
 
-    const fieldErrors: FieldErrors = {};
-    try {
-      // Every settings and AI credential write runs on the transaction's own
-      // connection, so a failure rolls the whole save back.
-      await sql.begin(async (tx) => {
-        for (const [key, value] of Object.entries(validatedValues)) {
-          try {
-            await settings.set(key, value, tx);
-          } catch (error) {
-            fieldErrors[key] = `Failed to update ${key}`;
-            throw error;
+      let aiPlan: AiSettingsMutationPlan;
+      try {
+        aiPlan = await prepareAiSettingsMutation(validatedValues, resets, aiSplit, getLocale(c));
+      } catch (error) {
+        console.error("[settings] failed to validate the prospective AI configuration", error);
+        return c.json({ message: "Failed to validate AI settings" }, 500);
+      }
+      if (Object.keys(aiPlan.errors).length > 0) {
+        return c.json({ message: aiSettingsNotSavedMessage(getLocale(c)), errors: aiPlan.errors, issues: aiPlan.issues ?? [] }, 400);
+      }
+
+      const fieldErrors: FieldErrors = {};
+      try {
+        // Every settings and AI credential write runs on the transaction's own
+        // connection, so a failure rolls the whole save back.
+        await sql.begin(async (tx) => {
+          for (const [key, value] of Object.entries(validatedValues)) {
+            try {
+              await settings.set(key, value, tx, { replaceUnreadable: replace.has(key) });
+            } catch (error) {
+              fieldErrors[key] = `Failed to update ${key}`;
+              throw error;
+            }
           }
-        }
-        for (const key of resets) {
-          try {
-            await settings.remove(key, tx);
-          } catch (error) {
-            fieldErrors[key] = `Failed to reset ${key}`;
-            throw error;
+          for (const key of resets) {
+            try {
+              await settings.remove(key, tx);
+            } catch (error) {
+              fieldErrors[key] = `Failed to reset ${key}`;
+              throw error;
+            }
           }
-        }
-        const categoryKeys = keys.filter((key) => key.startsWith("user.category."));
-        if (categoryKeys.length > 0)
-          await audit.record(
-            {
-              action: "accounts.categories.configure",
-              outcome: "allowed",
-              actor: { userId: c.get("user").id },
-              target: { type: "settings", id: "user.category" },
-              metadata: {
-                keys: categoryKeys,
-                updates: Object.fromEntries(categoryKeys.filter((key) => key in validatedValues).map((key) => [key, validatedValues[key]])),
-                resets: resets.filter((key) => categoryKeys.includes(key)),
+          const categoryKeys = keys.filter((key) => key.startsWith("user.category."));
+          if (categoryKeys.length > 0)
+            await audit.record(
+              {
+                action: "accounts.categories.configure",
+                outcome: "allowed",
+                actor: { userId: c.get("user").id },
+                target: { type: "settings", id: "user.category" },
+                metadata: {
+                  keys: categoryKeys,
+                  updates: Object.fromEntries(
+                    categoryKeys.filter((key) => key in validatedValues).map((key) => [key, validatedValues[key]]),
+                  ),
+                  resets: resets.filter((key) => categoryKeys.includes(key)),
+                },
               },
+              tx,
+            );
+          if (aiSplit && aiPlan.keepCredentialProfileIds) {
+            await storeAiCredentials(aiSplit, aiPlan.keepCredentialProfileIds, tx);
+          } else if (aiPlan.keepCredentialProfileIds) {
+            await pruneAiCredentials(aiPlan.keepCredentialProfileIds, tx);
+          }
+          if (aiPlan.headerPlan) await storeAiRequestHeaderPlan(aiPlan.headerPlan, tx);
+          if (aiPlan.modelProfileIds) {
+            await aiModelAccess.syncProfiles(aiPlan.modelProfileIds, accessChanges, tx);
+          }
+        });
+      } catch (error) {
+        if (error instanceof settings.SettingUnreadableError) {
+          return c.json(
+            {
+              message: settingsNotSavedMessage(getLocale(c)),
+              errors: { [error.key]: unreadableSettingMessage(getLocale(c)) },
+              code: "setting_unreadable",
             },
-            tx,
+            409,
           );
-        if (aiSplit && aiPlan.keepCredentialProfileIds) {
-          await storeAiCredentials(aiSplit, aiPlan.keepCredentialProfileIds, tx);
-        } else if (aiPlan.keepCredentialProfileIds) {
-          await pruneAiCredentials(aiPlan.keepCredentialProfileIds, tx);
         }
-        if (aiPlan.headerPlan) await storeAiRequestHeaderPlan(aiPlan.headerPlan, tx);
-        if (aiPlan.modelProfileIds) {
-          await aiModelAccess.syncProfiles(aiPlan.modelProfileIds, accessChanges, tx);
+        if (error instanceof ImageMetadataError) return c.json({ message: error.message, code: error.code, errors: fieldErrors }, 422);
+        if (error instanceof AiModelAccessConflict || error instanceof AiModelAccessInvalid) {
+          return c.json(
+            { message: error.message, errors: { [AI_PROFILES_KEY]: error.message } },
+            error instanceof AiModelAccessConflict ? 409 : 400,
+          );
         }
-      });
-    } catch (error) {
-      if (error instanceof ImageMetadataError) return c.json({ message: error.message, code: error.code, errors: fieldErrors }, 422);
-      if (error instanceof AiModelAccessConflict || error instanceof AiModelAccessInvalid) {
+        console.error("[settings] failed to commit settings update", error);
         return c.json(
-          { message: error.message, errors: { [AI_PROFILES_KEY]: error.message } },
-          error instanceof AiModelAccessConflict ? 409 : 400,
+          {
+            message: "Save failed",
+            errors: Object.keys(fieldErrors).length > 0 ? fieldErrors : { _form: "The settings could not be saved." },
+          },
+          500,
         );
       }
-      console.error("[settings] failed to commit settings update", error);
-      return c.json(
-        {
-          message: "Save failed",
-          errors: Object.keys(fieldErrors).length > 0 ? fieldErrors : { _form: "The settings could not be saved." },
-        },
-        500,
-      );
-    }
 
-    // Only now: dropping the cache before the commit would let another
-    // container miss, read the pre-commit row and cache it for the full TTL.
-    await invalidateCommittedSettings(keys);
+      // Only now: dropping the cache before the commit would let another
+      // container miss, read the pre-commit row and cache it for the full TTL.
+      await invalidateCommittedSettings(keys);
 
-    return c.body(null, 204);
-  })
+      return c.body(null, 204);
+    },
+  )
   .delete("/:key{.+}", auth.requireRole("admin"), async (c) => {
     const key = c.req.param("key");
     if (!isKnownSetting(key)) {

package/src/api/admin-outgoing-mail.ts

@@ -131,8 +131,10 @@ export const createAdminOutgoingMailRoutes = (authenticate: MiddlewareHandler<Au
         const next = c.req.valid("json");
         const old = await readMailRetention();
         await sql.begin(async (tx) => {
-          await settings.set(MAIL_RETENTION_KEYS[0], next.contentDays, tx);
-          await settings.set(MAIL_RETENTION_KEYS[1], next.recordDays, tx);
+          // complete value from explicit admin input; nothing is merged over a read (#1303)
+          await settings.set(MAIL_RETENTION_KEYS[0], next.contentDays, tx, { replaceUnreadable: true });
+          // complete value from explicit admin input; nothing is merged over a read (#1303)
+          await settings.set(MAIL_RETENTION_KEYS[1], next.recordDays, tx, { replaceUnreadable: true });
           await audit.record(
             {
               ...context(c),

package/src/api/app-approval.ts

@@ -15,7 +15,13 @@ import {
   AppPairingStartSchema,
 } from "../contracts/app-approval";
 import { type AuthContext, auth, rateLimit, v } from "../server";
-import { type AppApprovalActor, AppApprovalError, appApproval, type createAppApprovalService } from "../services/app-approval";
+import {
+  type AppApprovalActor,
+  AppApprovalError,
+  type AppTerminalLogins,
+  appApproval,
+  type createAppApprovalService,
+} from "../services/app-approval";
 import { appNameIn } from "../ssr/runtime";
 import { createDeviceActions } from "./app-approval-actions";
 
@@ -24,7 +30,7 @@ const DevicePageSchema = z.object({ after: z.string().uuid().optional() }).stric
 type Service = ReturnType<typeof createAppApprovalService>;
 
 /** This is a separate credential surface, never a user API-key or OAuth scope. */
-export const createAppApprovalRoutes = (service: Service = appApproval, actions = createDeviceActions) => {
+export const createAppApprovalRoutes = (service: Service = appApproval, actions = createDeviceActions, terminal?: AppTerminalLogins) => {
   const actor = async (c: Parameters<typeof auth.session.getToken>[0]): Promise<AppApprovalActor> => {
     // The web session (or an explicit bearer session), never the mobile app's session: a phone
     // that pairs sign-in devices would hand out authority that outlives its removal.
@@ -111,6 +117,7 @@ export const createAppApprovalRoutes = (service: Service = appApproval, actions
           await service.deviceCommand(
             c.req.valid("json"),
             actions((appId, locale) => appNameIn(c, appId, locale, appId)),
+            terminal,
           ),
         ),
     )

package/src/api/approvals.ts

@@ -111,7 +111,7 @@ export const approvalRoutes = new Hono<AuthContext>()
             client: c.req.header(APPROVAL_CLIENT_HEADER),
           }),
         },
-        toolApprovalContext: ctx.toolApprovalContext,
+        toolApprovalContext: ctx.toolApprovalChangeContext,
         signedInSession: ctx.signedInSession,
       });
       if (!result.ok) return toAiActionFailureResponse(c, result);

package/src/api/index.ts

@@ -56,6 +56,7 @@ export { createPwaPhoneRoutes } from "./pwa-phone";
  * the typed shape for the client.
  */
 export type CoreApiOptions = {
+  terminalLogins?: import("../services/app-approval").AppTerminalLogins;
   notifications: import("../services/auth-flows/notification-sender").AuthNotificationSender;
 };
 
@@ -68,7 +69,7 @@ const buildCoreApi = (options: CoreApiOptions) => {
   const widgetRoutes = createWidgetRoutes();
   return new Hono()
     .use(prettyJSON())
-    .route("/auth/app-approval/v1", createAppApprovalRoutes())
+    .route("/auth/app-approval/v1", createAppApprovalRoutes(undefined, undefined, options.terminalLogins))
     .route("/auth/pwa/v1", createPwaRoutes())
     .route("/auth", createAuthRoutes(options.notifications))
     .route("/me", meRoutes)

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

@@ -10,6 +10,7 @@ import {
   APP_APPROVAL_PROTOCOL,
   type AppActionView,
   AppActionViewSchema,
+  type AppApprovalAccept,
   AppDeviceCommandSchema,
   AppDeviceProofSchema,
   type AppDevicePublicKey,
@@ -223,9 +224,13 @@ 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,
     /** 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);
+    inbox: async (device: AppApprovalDevice, signal?: AbortSignal, options?: { accept?: AppApprovalAccept[] }) => {
+      // 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)) throw new AppApprovalClientError("INVALID_RESPONSE");
       return result;
     },

package/src/browser/composer-catalog.ts

@@ -0,0 +1,103 @@
+import type { ChatCommandSearch } from "@k2b/ui";
+import { createSignal } from "solid-js";
+import { listCapabilityCatalog } from "../capabilities/client";
+import { LOCALE_HEADER } from "../shared/locale";
+
+export type CloudSearchTag = {
+  appId: string;
+  appName: string;
+  appIcon: string;
+  tag: string;
+  title: string;
+  description: string;
+  aliases: readonly string[];
+};
+
+/**
+ * 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[] };
+
+/** 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 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.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 };
+};
+
+/**
+ * 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 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[]>([]);
+  let opening: number | undefined;
+  let settled: Promise<void> = Promise.resolve();
+  let failed = false;
+  return {
+    tags,
+    ready(query: string, search: ChatCommandSearch, locale: string): Promise<void> {
+      if (opening !== search.opening) {
+        opening = search.opening;
+        settled = load(locale).then(
+          (catalog) => {
+            setTags(catalog.tags);
+          },
+          () => {
+            failed = true;
+          },
+        );
+      }
+      return failed || search.scope !== undefined || !query.trim() ? Promise.resolve() : settled;
+    },
+  };
+}