@k2b/cloud 0.37.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/help.ts

@@ -1,14 +1,16 @@
+import { keyboardPlatform } from "@k2b/ui";
 import { Hono, type MiddlewareHandler } from "hono";
+import { helpAgentMarkdown } from "../_internal/help-catalog";
 import { type AuthContext, auth, getLocale } from "../server";
 import { createHelpReader, type HelpReaderFactory } from "../services/help";
-import type { HelpDocumentPayload, HelpSearchPayload } from "../shared/help";
+import { type HelpDocumentPayload, type HelpSearchPayload, parseHelpReference } from "../shared/help";
 import { renderHelpMarkdown } from "../shared/markdown";
 import { helpApiMessages } from "./help-messages";
 
 export type HelpRouteDependencies = {
   help?: HelpReaderFactory;
   authenticate?: MiddlewareHandler<AuthContext>;
-  renderMarkdown?: (markdown: string, locale: string) => string;
+  renderMarkdown?: typeof renderHelpMarkdown;
 };
 
 export const createHelpRoutes = (dependencies: HelpRouteDependencies = {}) => {
@@ -34,12 +36,29 @@ export const createHelpRoutes = (dependencies: HelpRouteDependencies = {}) => {
       const { t } = helpApiMessages.resolve([locale]);
       const document = await reader(locale, c.get("actor")).read({ appId: c.req.param("appId"), documentId: c.req.param("documentId") });
       if (!document) return c.json({ code: "HELP_NOT_FOUND", message: t.notFound }, 404);
+      const links = (reference: { appId?: string; documentId: string }) =>
+        document.links[`${reference.appId ?? document.appId}/${reference.documentId}`];
+      const resolve = (reference: string) => {
+        const ref = parseHelpReference(reference);
+        return ref ? links(ref) : undefined;
+      };
       const payload: HelpDocumentPayload = {
         locale: document.locale,
         id: document.documentId,
         title: document.title,
-        markdown: document.markdown,
-        html: (dependencies.renderMarkdown ?? renderHelpMarkdown)(document.markdown, document.locale),
+        markdown: helpAgentMarkdown(document),
+        kind: document.kind,
+        needs: document.needs,
+        next: document.next ? resolve(document.next) : undefined,
+        related: document.related.flatMap((reference) => {
+          const target = resolve(reference);
+          return target ? [target] : [];
+        }),
+        html: (dependencies.renderMarkdown ?? renderHelpMarkdown)(document.markdown, {
+          locale: document.locale,
+          platform: keyboardPlatform(c.req.header("User-Agent") ?? ""),
+          links,
+        }),
       };
       return c.json(payload);
     });

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/api/mcp.ts

@@ -15,7 +15,13 @@ import {
 import { Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
 import { readBoundedJson } from "../_internal/bounded-json";
-import { HELP_SEARCH_MAX_LIMIT, helpResourceUri, parseHelpResourceUri, readHelpArticle } from "../_internal/help-catalog";
+import {
+  HELP_SEARCH_MAX_LIMIT,
+  helpAgentMarkdown,
+  helpResourceUri,
+  parseHelpResourceUri,
+  readHelpArticle,
+} from "../_internal/help-catalog";
 import { getCapability, listApps } from "../_internal/registry";
 import { addCloudResourceHrefs } from "../ai/resource-refs";
 import { capabilityValueMeta, recordCapabilityExecution } from "../capabilities/executions";
@@ -540,7 +546,7 @@ const createMcpServer = (
         {
           uri: message.params.uri,
           mimeType: "text/markdown",
-          text: document.markdown,
+          text: helpAgentMarkdown(document),
           _meta: { "cloud/manifestHash": document.manifestHash, "cloud/locale": document.locale },
         },
       ],

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/FileChooser.tsx

@@ -14,7 +14,7 @@ import {
 } from "@k2b/ui";
 import { batch, createMemo, createSignal, For, type JSX, Match, onCleanup, Show, Switch } from "solid-js";
 import { createStore } from "solid-js/store";
-import type { FileProviderEntry, FileProviderTag } from "../contracts/file-provider";
+import type { FileProviderContext, FileProviderEntry, FileProviderTag } from "../contracts/file-provider";
 import { fileChooserMessages } from "./file-chooser-messages";
 import {
   type EntryProblem,
@@ -39,6 +39,14 @@ export type ChooseFilesOptions = {
    * above it, so it also bounds what the browser holds. The provider's own read limit applies to each file as well.
    */
   maxBytes?: number;
+  /**
+   * What the person is working on, as resource refs, for providers that understand it. Only providers whose `list`
+   * accepts `context` receive it; others list as before. A function runs only when the person opens such a provider,
+   * at most once per chooser, and again after it failed. Refs are hints, never access.
+   */
+  context?: FileProviderContext | ((signal: AbortSignal) => Promise<FileProviderContext>);
+  /** The empty root title for a provider that received context. Defaults to the chooser's "No matching files". */
+  noMatchingFiles?: string;
   /** Closes the chooser, or stops waiting for the device's dialog, and resolves `[]` when aborted. */
   signal?: AbortSignal;
 };
@@ -95,7 +103,7 @@ export function FileChooser(props: {
       if (first) (location() ? selection : sourceSelection).focus(first);
     });
   };
-  const folder = createProviderFolder({ caller: props.caller, t, settled: refocus });
+  const folder = createProviderFolder({ caller: props.caller, t, settled: refocus, context: props.options.context });
   const { location, items, openFolder } = folder;
   const [downloads, setDownloads] = createStore<Download[]>([]);
   const [downloading, setDownloading] = createSignal(false);
@@ -297,7 +305,7 @@ export function FileChooser(props: {
               </Switch>
             </Match>
             <Match when={true}>
-              <FolderContents folder={folder} t={t}>
+              <FolderContents folder={folder} t={t} noMatchingFiles={props.options.noMatchingFiles}>
                 <FileGrid
                   rows={items()}
                   getRowId={(entry) => entry.id}

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;
     },