@k2b/cloud 0.26.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -98,9 +98,9 @@
     "@simplewebauthn/server": "14.0.3",
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
-    "@k2b/nessi": "0.12.1",
+    "@k2b/nessi": "0.15.0",
     "@k2b/ssr": "0.14.0",
-    "@k2b/ui": "0.16.0",
+    "@k2b/ui": "0.18.0",
     "@k2b/stdlib": "0.27.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",

package/src/_internal/define-app.ts

@@ -40,6 +40,7 @@ import {
   CapabilityOriginSchema,
 } from "../contracts/capabilities";
 import { type BoundNotificationMap, bindNotificationDefinitions, type NotificationDefinitionMap } from "../contracts/notification-types";
+import { type PlatformPermission, PlatformPermissionSchema } from "../contracts/outgoing-mail";
 import { isPwaPartId, PWA_AUTH_PATH, PWA_CANVAS_COLORS, PWA_MANIFEST_PATH, PWA_SHELL_APP_ID } from "../contracts/pwa";
 import type { AppRegistryEntry } from "../contracts/registry";
 import type { AppSettingsMap, KindToType } from "../contracts/settings-types";
@@ -201,6 +202,8 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
    * prefix-trie from these strings.
    */
   routes: readonly string[];
+  /** Platform services requested by this application, visible to administrators. */
+  platformPermissions?: readonly PlatformPermission[];
   /**
    * Gateway-relative URL at which this app's OpenAPI 3.x JSON spec is
    * served, e.g. `"/api/notebooks/openapi.json"`. Opt-in: only set this
@@ -471,6 +474,9 @@ export const defineApp = <
   // ── 2. Meta ───────────────────────────────────────────────────────────
   const baseMeta: AppMeta = {
     id: opts.id,
+    platformPermissions: opts.platformPermissions
+      ? opts.platformPermissions.map((permission) => PlatformPermissionSchema.parse(permission))
+      : undefined,
     name: opts.name,
     icon: opts.icon,
     description: opts.description,
@@ -528,7 +534,7 @@ export const defineApp = <
         }
       })());
     try {
-      bindProcessApplicationId(meta.id);
+      bindProcessApplicationId(meta.id, meta.platformPermissions);
       cleanup.unshift(clearProcessApplicationId);
       const startedAt = Date.now();
 
@@ -587,6 +593,7 @@ export const defineApp = <
           ? { href: meta.pwa.href, requiresRoles: meta.pwa.requiresRoles ? [...meta.pwa.requiresRoles] : undefined }
           : undefined,
         widgets: meta.widgets ? meta.widgets.map((w) => ({ ...w })) : undefined,
+        platformPermissions: meta.platformPermissions ? [...meta.platformPermissions] : undefined,
         settingKeys: meta.settingKeys ? [...meta.settingKeys] : undefined,
         openapi: advertiseOpenapi ? opts.openapi : undefined,
         cliModules: cliModules.length > 0 ? cliModules : undefined,

package/src/_internal/process-identity.ts

@@ -1,15 +1,21 @@
+import type { PlatformPermission } from "../contracts/outgoing-mail";
+
 /** Identity of the application started in this process, derived from its declaration. */
 let applicationId: string | undefined;
+let platformPermissions: readonly PlatformPermission[] = [];
+export const getProcessPlatformPermissions = (): readonly PlatformPermission[] => platformPermissions;
 
 export const getProcessApplicationId = (): string | undefined => applicationId;
 
-export const bindProcessApplicationId = (id: string): void => {
+export const bindProcessApplicationId = (id: string, permissions: readonly PlatformPermission[] = []): void => {
   if (applicationId !== undefined && applicationId !== id) {
     throw new Error(`This process already hosts application "${applicationId}"`);
   }
   applicationId = id;
+  platformPermissions = [...permissions];
 };
 
 export const clearProcessApplicationId = (): void => {
   applicationId = undefined;
+  platformPermissions = [];
 };

package/src/_internal/registry-validation.ts

@@ -1,4 +1,5 @@
 import { CLOUD_CLI_MODULE_NAME } from "../cli/plugin";
+import { PlatformPermissionSchema } from "../contracts/outgoing-mail";
 import type { AppRegistryEntry } from "../contracts/registry";
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -118,6 +119,8 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
       return invalid("widgets", "an array of valid widgets");
     }
   }
+  if (value.platformPermissions !== undefined && !PlatformPermissionSchema.array().safeParse(value.platformPermissions).success)
+    return invalid("platformPermissions", "an array of platform permissions");
   if (value.settingKeys !== undefined && !isStringArray(value.settingKeys)) return invalid("settingKeys", "an array of strings");
   if (
     value.cliModules !== undefined &&

package/src/_internal/runtime-context.ts

@@ -15,6 +15,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
     const searchTags = searchQueries?.flatMap((query) => query.universalSearch!.tags.flatMap((tag) => [tag.tag, ...(tag.aliases ?? [])]));
     return {
       id: e.id,
+      platformPermissions: e.platformPermissions ? [...e.platformPermissions] : undefined,
       name: e.name,
       icon: e.icon,
       description: e.description,

package/src/ai/admin.ts

@@ -1,5 +1,6 @@
 export { quotaAdminConfig, quotaReport } from "./quota-report";
 export { AiQuotaError, aiQuotas } from "./quotas";
+export { listAiRequestHeaderNames } from "./request-headers";
 /** Server-only AI administration and usage accounting. */
 
 export { type AiModelAccessDraft, type AiModelAccessMap, type AiModelAccessState, aiModelAccess } from "./model-access";

package/src/ai/browser-code-contracts.ts

@@ -10,20 +10,20 @@ export const CODE_RUNTIME_TOOL_NAMES = [
   "code_run",
   "code_action",
   "code_inspect",
-  "code_interact",
   "code_stop",
   "code_open",
   "code_export",
   "code_present",
+  "code_check",
   "code_secret",
 ] as const;
 export const CodeRunInput = z
   .object({
-    id: id.optional(),
+    id: id.optional().describe("Saved script resource to run; an app with an index.html interface opens with code_open instead."),
     resourceId: id
       .optional()
       .describe(
-        "Optional data context for one-off code. Requires Manage; uses this resource database and shared files/KV without changing its source. Local storage stays temporary.",
+        "Optional data context for one-off code. Requires Manage; uses this resource database and shared files/KV without changing its source. Runs use real shared and personal data; writes and capability effects keep normal permissions and approvals.",
       ),
     version: z
       .number()
@@ -36,14 +36,12 @@ export const CodeRunInput = z
       .min(1)
       .max(1024 * 1024)
       .optional()
-      .describe("One-off JavaScript/TypeScript entry exporting one function. Use code OR a saved resource id; no title or icon needed."),
+      .describe("One-off JavaScript/TypeScript script exporting one function. Use code OR a saved resource id; no title or icon needed."),
     inputPaths: z
       .array(z.string().min(1).max(500))
       .max(64)
       .default([])
-      .describe(
-        "Explicit current-chat input files. Scripts can read them; app test runs expose them only through the simulated picker. User apps never receive chat files.",
-      ),
+      .describe("Explicit current-chat input files; the script reads them from its context files. Apps never receive chat files."),
   })
   .strict()
   .refine((input) => Number(input.id !== undefined) + Number(input.code !== undefined) === 1, "Provide exactly one of id or code")
@@ -71,7 +69,10 @@ export const CodeActionInput = z
       .positive()
       .optional()
       .describe("Exact draft revision returned by code_actions({draft:true}); Manage required. Supply this OR publishedVersion."),
-    input: z.json().describe("Action input matching the discovered inputSchema."),
+    input: z
+      .record(z.string(), z.json())
+      .default({})
+      .describe("Action input object matching the discovered inputSchema. Pass the object itself, never JSON text."),
   })
   .strict()
   .refine(
@@ -88,66 +89,38 @@ export const CodeInspectInput = z
       .max(30000)
       .default(0)
       .describe("Wait up to this duration for background work to finish before returning its real state; never restarts work."),
-    nodeId: z.string().min(1).max(80).optional(),
-    offset: z.number().int().min(0).default(0),
-    limit: z.number().int().min(1).max(100).default(20),
   })
   .strict();
-const CodeInteraction = z
+export const CodeStopInput = z.object({ runId }).strict();
+export const CodeOpenInput = z.object({ id }).strict();
+const AppFilePath = z
+  .string()
+  .min(1)
+  .max(180)
+  .regex(/^[a-zA-Z0-9_.-]+(?:\/[a-zA-Z0-9_.-]+)*$/)
+  .refine((path) => path.split("/").every((part) => part !== "." && part !== ".."), "Expected a relative path without . or ..");
+export const CodePresentInput = z
   .object({
-    id: z.string().min(1).max(80).describe("Control ID or pending modal ID returned by the snapshot."),
-    event: z
-      .discriminatedUnion("type", [
-        z
-          .object({
-            type: z.literal("change"),
-            value: z.union([
-              z.string(),
-              z.number().finite(),
-              z.boolean(),
-              z.null(),
-              z.array(z.string()),
-              z.object({ start: z.iso.date().nullable(), end: z.iso.date().nullable() }).strict(),
-            ]),
-          })
-          .strict(),
-        z.object({ type: z.literal("select"), key: z.string().nullable() }).strict(),
-        z.object({ type: z.literal("view"), value: z.enum(["chart", "table"]) }).strict(),
-        z.object({ type: z.literal("refresh") }).strict(),
-        z.object({ type: z.literal("request"), request: z.record(z.string(), z.json()) }).strict(),
-      ])
+    id: id
       .optional()
-      .describe(
-        "An event object, never a JSON-encoded string. Omit to activate a button. Example: {type:'change',value:['Sued']} or {type:'view',value:'table'}.",
-      ),
-    answer: z.json().optional().describe("Only for the pending modal ID: the modal answer, or null to cancel. Do not use for controls."),
-  })
-  .strict();
-const validInteraction = (input: z.infer<typeof CodeInteraction>) => input.event === undefined || input.answer === undefined;
-export const CodeInteractInput = CodeInteraction.partial({ id: true })
-  .extend({
-    runId,
-    // Three normal 15-second callback budgets share the existing 45-second call budget.
-    steps: z
-      .array(CodeInteraction.refine(validInteraction, "Supply event OR answer"))
+      .describe("Saved app with an index.html interface; the card runs it live with its data. Omit title to use the app title."),
+    files: z
+      .array(z.object({ path: AppFilePath, content: z.string().max(1024 * 1024) }).strict())
       .min(1)
-      .max(3)
+      .max(64)
       .optional()
-      .describe(
-        "Up to three sequential interactions in one call. Use steps OR the top-level id/event/answer. Stops on an error, pending modal or background work; returns completedSteps and nextStep.",
-      ),
+      .describe("One-off app for this chat: index.html plus optional style.css, app.js and other modules. It has no saved data."),
+    title: z.string().trim().min(1).max(120).optional().describe("Card title; required with files."),
   })
   .strict()
-  .refine(
-    (input) =>
-      input.steps
-        ? input.id === undefined && input.event === undefined && input.answer === undefined
-        : input.id !== undefined && (input.event === undefined || input.answer === undefined),
-    "Supply steps OR one id with event/answer.",
-  );
-export const CodeStopInput = z.object({ runId }).strict();
-export const CodeOpenInput = z.object({ id }).strict();
-export const CodePresentInput = z.object({ runId, title: z.string().trim().min(1).max(120) }).strict();
+  .refine((input) => Number(input.id !== undefined) + Number(input.files !== undefined) === 1, "Provide exactly one of id or files")
+  .refine((input) => input.id !== undefined || input.title !== undefined, "A one-off app needs a title")
+  .refine((input) => !input.files || input.files.some((file) => file.path === "index.html"), "files must contain index.html");
+export const CodeCheckInput = z
+  .object({ id: id.optional(), files: CodePresentInput.shape.files })
+  .strict()
+  .refine((input) => Number(input.id !== undefined) + Number(input.files !== undefined) === 1, "Provide exactly one of id or files")
+  .refine((input) => !input.files || input.files.some((file) => file.path === "index.html"), "files must contain index.html");
 export const CodeExportInput = z
   .object({ runId, name: z.string().min(1).max(180).describe("Captured output filename returned by the snapshot.") })
   .strict();
@@ -162,16 +135,25 @@ export const CodeSecretInput = z
   })
   .strict();
 
+/**
+ * A runtime call that did not complete: rejected input, timeout, lost run or host failure.
+ * Hosts return it as data because a client tool result carries no error flag; the managed
+ * server tools report it to the model as a tool error. A run snapshot whose code failed is a
+ * completed call and keeps its own `status` and `error`.
+ */
+export const CodeToolFailure = z.object({ failed: z.literal(true), error: z.string(), guidance: z.string().optional() });
+export type CodeToolFailure = z.infer<typeof CodeToolFailure>;
+
 // Internal bridge envelope. Each model-facing tool receives only its own flat schema.
 export const CodeRuntimeInput = z.discriminatedUnion("operation", [
   CodeRunInput.safeExtend({ operation: z.literal("run") }),
   CodeActionInput.safeExtend({ operation: z.literal("action") }),
   CodeInspectInput.extend({ operation: z.literal("inspect") }),
-  CodeInteractInput.safeExtend({ operation: z.literal("interact") }),
   CodeStopInput.extend({ operation: z.literal("stop") }),
   CodeOpenInput.extend({ operation: z.literal("open") }),
   CodeSecretInput.extend({ operation: z.literal("secret") }),
-  CodePresentInput.extend({ operation: z.literal("present") }),
+  CodePresentInput.safeExtend({ operation: z.literal("present") }),
+  CodeCheckInput.safeExtend({ operation: z.literal("check") }),
   CodeExportInput.extend({ operation: z.literal("export") }),
 ]);
 export type CodeRuntimeInput = z.infer<typeof CodeRuntimeInput>;
@@ -185,12 +167,12 @@ export function parseCodeToolInput(name: string, args: unknown): CodeRuntimeInpu
       return { operation: "run", ...CodeRunInput.parse(args) };
     case "code_inspect":
       return { operation: "inspect", ...CodeInspectInput.parse(args) };
-    case "code_interact":
-      return { operation: "interact", ...CodeInteractInput.parse(args) };
     case "code_stop":
       return { operation: "stop", ...CodeStopInput.parse(args) };
     case "code_open":
       return { operation: "open", ...CodeOpenInput.parse(args) };
+    case "code_check":
+      return { operation: "check", ...CodeCheckInput.parse(args) };
     case "code_present":
       return { operation: "present", ...CodePresentInput.parse(args) };
     case "code_export":

package/src/ai/browser.ts

@@ -1,4 +1,12 @@
-export { CODE_RUNTIME_TOOL_NAMES, CodeActionInput, CodeResourceId, CodeRuntimeInput, parseCodeToolInput } from "./browser-code-contracts";
+export {
+  CODE_RUNTIME_TOOL_NAMES,
+  CodeActionInput,
+  CodeCheckInput,
+  CodeResourceId,
+  CodeRuntimeInput,
+  CodeToolFailure,
+  parseCodeToolInput,
+} from "./browser-code-contracts";
 export { type AiTaskRequest, type AiTaskRequestInput, AiTaskRequestSchema } from "./task-contracts";
 export { type AiTodoPlan, parseAiTodoPlan } from "./todo-contracts";
 

package/src/ai/capabilities.ts

@@ -72,6 +72,16 @@ type AiToolCatalogEntry = AiToolCatalogItem & {
 
 export type AiRememberableCapabilityApprovals = ReadonlyMap<string, string>;
 
+/**
+ * Why `load_tools` could not make a requested name callable:
+ * - `unknown`: no tool has this exact name;
+ * - `not_offered_in_turn`: the tool exists, but this turn's client or task does not provide it;
+ * - `not_allowed`: the conversation's fixed tool scope excludes it;
+ * - `app_offline`: the app operation is not in the live registry now.
+ */
+export const AI_TOOL_UNAVAILABLE_REASONS = ["unknown", "not_offered_in_turn", "not_allowed", "app_offline"] as const;
+export type AiToolUnavailableReason = (typeof AI_TOOL_UNAVAILABLE_REASONS)[number];
+
 const DEFAULT_SEARCH_LIMIT = 10;
 const DEFAULT_APP_LIST_LIMIT = 20;
 const MAX_APP_LIST_LIMIT = 25;
@@ -367,15 +377,16 @@ export const createAiHelpTools = (help: HelpReaderFactory = createHelpReader, lo
   return [search, read];
 };
 
+/** `null` when the registry could not be read. */
 const resolveCapabilityRegistry = async (
   listRegistry: () => Promise<CapabilityRegistryEntry[]>,
   onError?: (error: unknown) => void,
-): Promise<CapabilityRegistryEntry[]> => {
+): Promise<CapabilityRegistryEntry[] | null> => {
   try {
     return await listRegistry();
   } catch (error) {
     onError?.(error);
-    return [];
+    return null;
   }
 };
 
@@ -453,6 +464,9 @@ const ToolCatalogItemSchema = z
 
 type ToolStateStore = Pick<AiConversationService, "loadTools">;
 
+/** `call` is the name to call the tool by; app operations get a provider-safe name. */
+const LoadedToolSchema = z.object({ name: z.string(), call: z.string() }).strict();
+
 export const createAiToolMetaTools = (input: {
   apps: readonly CapabilityRegistryEntry[];
   catalog: readonly AiToolCatalogEntry[];
@@ -461,6 +475,10 @@ export const createAiToolMetaTools = (input: {
   store: ToolStateStore;
   maxLoadedTools?: number;
   unavailableLoadedNames?: readonly string[];
+  /** False when this turn offers no app operations at all. */
+  appOperationsOffered?: boolean;
+  /** Why a requested name that is not in `catalog` cannot be loaded; defaults to `unknown`. */
+  unavailableReason?: (name: string) => AiToolUnavailableReason;
 }): AiRuntimeTool[] => {
   const apps = buildAiCapabilityAppCatalog(input.apps);
   const directoryEntries: string[] = [];
@@ -476,17 +494,17 @@ export const createAiToolMetaTools = (input: {
   const liveAppDirectory =
     directoryEntries.length > 0
       ? ` Live capability apps: ${directoryEntries.join(", ")}${hiddenAppCount > 0 ? `, and ${hiddenAppCount} more` : ""}.`
-      : " No live capability apps are visible in this provider turn; retry discovery later instead of claiming a permanent product limitation.";
+      : input.appOperationsOffered === false
+        ? " App operations are not offered in this turn."
+        : " No Cloud app publishes operations right now. Do not search for app operations again in this turn; tell the user which app is not reachable instead of claiming a permanent product limitation.";
   const unavailableLoadedNames = input.unavailableLoadedNames ?? [];
   const unavailableLoadedNotice =
     unavailableLoadedNames.length > 0
-      ? ` Previously loaded tools currently absent from the live catalog: ${unavailableLoadedNames
-          .slice(-MAX_UNAVAILABLE_LOADED_NAMES)
-          .join(", ")}${
+      ? ` Previously loaded tools that are not available now: ${unavailableLoadedNames.slice(-MAX_UNAVAILABLE_LOADED_NAMES).join(", ")}${
           unavailableLoadedNames.length > MAX_UNAVAILABLE_LOADED_NAMES
             ? `, and ${unavailableLoadedNames.length - MAX_UNAVAILABLE_LOADED_NAMES} more`
             : ""
-        }. Treat them as temporarily unavailable; do not infer a permanent product limitation or search repeatedly.`
+        }. Do not search for them again in this turn; continue without them or tell the user what is missing.`
       : "";
   const search = defineAiTool({
     name: "search_tools",
@@ -524,38 +542,52 @@ export const createAiToolMetaTools = (input: {
   const load = defineAiTool({
     name: "load_tools",
     description:
-      "Load stable capability ids such as mail.conversation.list, or exact built-in names returned by search_tools, as ordinary tools for the next model turn. Skills may name capability ids directly, so load them without searching first.",
+      "Load stable capability ids such as mail.conversation.list, or exact built-in names returned by search_tools, as ordinary tools for the next model turn. Skills may name capability ids directly, so load them without searching first. Call each loaded tool by the `call` name returned for it. `unavailable` gives a reason per name: unknown means no tool has this exact name, so look it up once with search_tools instead of guessing; not_offered_in_turn means this client or task does not provide the tool; not_allowed means this chat's fixed tool scope excludes it; app_offline means its app is not reachable now. For the last three, do not search or load the name again in this turn.",
     inputSchema: z.object({ names: z.array(z.string().trim().min(1)).min(1).max(25) }).strict(),
     outputSchema: z
       .object({
-        loaded: z.array(z.string()),
-        alreadyLoaded: z.array(z.string()),
-        missing: z.array(z.string()),
+        loaded: z.array(LoadedToolSchema),
+        alreadyLoaded: z.array(LoadedToolSchema),
+        unavailable: z.array(z.object({ name: z.string(), reason: z.enum(AI_TOOL_UNAVAILABLE_REASONS) }).strict()),
         evicted: z.array(z.string()),
         titles: z.record(z.string(), z.string()),
       })
       .strict(),
     approval: "never",
   }).server(async ({ names }) => {
-    const available = new Set(input.catalog.map((entry) => entry.name));
+    const catalogByName = new Map(input.catalog.map((entry) => [entry.name, entry]));
+    // A provider name the model saw in an earlier call loads its operation, too.
+    const byProviderName = new Map(input.catalog.flatMap((entry) => (entry.capability ? [[entry.capability.providerName, entry]] : [])));
     const requested = [...new Set(names)];
-    const eager = requested.filter((name) => input.eagerNames.has(name));
-    const valid = requested.filter((name) => available.has(name) && !input.eagerNames.has(name));
-    const missing = requested.filter((name) => !available.has(name));
+    const found = requested.flatMap((name) => {
+      const entry = catalogByName.get(name) ?? byProviderName.get(name);
+      return entry ? [entry.name] : [];
+    });
+    const eager = [...new Set(found.filter((name) => input.eagerNames.has(name)))];
+    const valid = [...new Set(found.filter((name) => !input.eagerNames.has(name)))];
+    const unavailable = requested
+      .filter((name) => !catalogByName.has(name) && !byProviderName.has(name))
+      .map((name) => ({ name, reason: input.unavailableReason?.(name) ?? ("unknown" as const) }));
     const updated = await input.store.loadTools({
       conversationId: input.conversationId,
       names: valid,
       maxLoadedTools: input.maxLoadedTools,
     });
+    const callable = (name: string) => ({ name, call: catalogByName.get(name)?.capability?.providerName ?? name });
     const alreadyLoaded = [...new Set([...eager, ...updated.alreadyLoaded])];
-    const catalogByName = new Map(input.catalog.map((entry) => [entry.name, entry]));
     const titles = Object.fromEntries(
       [...new Set([...updated.loaded, ...alreadyLoaded, ...updated.evicted])].flatMap((name) => {
         const entry = catalogByName.get(name);
         return entry ? [[name, entry.title]] : [];
       }),
     );
-    return { ...updated, alreadyLoaded, missing, titles };
+    return {
+      loaded: updated.loaded.map(callable),
+      alreadyLoaded: alreadyLoaded.map(callable),
+      unavailable,
+      evicted: updated.evicted,
+      titles,
+    };
   });
 
   return [search, load, listApps];
@@ -657,6 +689,8 @@ export const createAiToolResolver =
     actor: RequestActor;
     staticTools: AiRuntimeTool[];
     allowedTools?: readonly string[] | null;
+    /** Built-in tools that exist but that this turn does not offer, such as client tools its client did not declare or tools outside `allowedTools`. */
+    unofferedTools?: readonly string[];
     runtimeContext?: Omit<AiToolPreparationContext, "actor" | "conversationId">;
     store: Pick<AiConversationService, "getLoadedTools" | "loadTools">;
     listRegistry?: () => Promise<CapabilityRegistryEntry[]>;
@@ -675,10 +709,11 @@ export const createAiToolResolver =
     }) => void;
   }): ToolResolver =>
   async (): Promise<Tool[]> => {
-    const [registry, persistedLoadedNames] = await Promise.all([
+    const [liveRegistry, persistedLoadedNames] = await Promise.all([
       input.listRegistry ? resolveCapabilityRegistry(input.listRegistry, input.onCapabilityRegistryError) : [],
       input.store.getLoadedTools({ conversationId: input.conversationId }),
     ]);
+    const registry = liveRegistry ?? [];
     const configuredLimit = Math.floor(input.maxLoadedTools ?? 0);
     const loadedNames = configuredLimit > 0 ? persistedLoadedNames.slice(-configuredLimit) : persistedLoadedNames;
     if (loadedNames.length !== persistedLoadedNames.length) {
@@ -689,18 +724,41 @@ export const createAiToolResolver =
       });
     }
     const allowed = input.allowedTools == null ? null : new Set(input.allowedTools);
-    const capabilityCatalog = buildAiCapabilityCatalog(registry, input.locale).filter((entry) => !allowed || allowed.has(entry.name));
+    const fullCapabilityCatalog = buildAiCapabilityCatalog(registry, input.locale);
+    const capabilityCatalog = fullCapabilityCatalog.filter((entry) => !allowed || allowed.has(entry.name));
     const helpTools = input.help ? createAiHelpTools(input.help, input.locale) : [];
     const resourceTool =
       input.execute && (capabilityCatalog.length > 0 || input.staticTools.some((tool) => tool.def.name === "code_read"))
         ? createAiResourceReaderTool({ apps: registry, catalog: capabilityCatalog, execute: input.execute })
         : null;
-    const builtIns = [...input.staticTools, ...helpTools, ...(resourceTool ? [resourceTool] : [])].filter(
-      (tool) => !allowed || allowed.has(tool.def.name),
-    );
+    const allBuiltIns = [...input.staticTools, ...helpTools, ...(resourceTool ? [resourceTool] : [])];
+    const builtIns = allBuiltIns.filter((tool) => !allowed || allowed.has(tool.def.name));
     const catalog = buildAiToolCatalog(builtIns, capabilityCatalog);
     const catalogNames = new Set(catalog.map((entry) => entry.name));
     const unavailableLoadedNames = loadedNames.filter((name) => !catalogNames.has(name));
+    const outOfScope = new Set([
+      ...allBuiltIns.map((tool) => tool.def.name),
+      ...fullCapabilityCatalog.flatMap((entry) => [entry.name, entry.providerName]),
+      ...(input.unofferedTools ?? []),
+    ]);
+    const unoffered = new Set(input.unofferedTools);
+    // A model may name a loaded operation by the provider name it called it by; app IDs contain no dot.
+    const loadedByProviderName = new Map(
+      persistedLoadedNames.flatMap((id) => {
+        const dot = id.indexOf(".");
+        if (dot < 1) return [];
+        return (["query", "action"] as const).map((kind) => [aiCapabilityToolName(id.slice(0, dot), kind, id.slice(dot + 1)), id] as const);
+      }),
+    );
+    // App operation IDs always contain a dot; built-in names never do.
+    const unavailableReason = (requested: string): AiToolUnavailableReason => {
+      const name = loadedByProviderName.get(requested) ?? requested;
+      if (allowed && outOfScope.has(name) && !allowed.has(name)) return "not_allowed";
+      if (unoffered.has(name)) return "not_offered_in_turn";
+      if (!name.includes(".")) return "unknown";
+      if (!input.listRegistry) return "not_offered_in_turn";
+      return liveRegistry === null || persistedLoadedNames.includes(name) ? "app_offline" : "unknown";
+    };
     const eagerNames = new Set(builtIns.map((tool) => tool.def.name).filter((name) => !CLOUD_AI_DEFERRED_BUILTIN_TOOL_NAMES.has(name)));
     const activeBuiltIns = builtIns.filter((tool) => eagerNames.has(tool.def.name) || loadedNames.includes(tool.def.name));
     const runtimeTools = [
@@ -712,6 +770,8 @@ export const createAiToolResolver =
         store: input.store,
         maxLoadedTools: input.maxLoadedTools,
         unavailableLoadedNames,
+        appOperationsOffered: Boolean(input.listRegistry),
+        unavailableReason,
       }),
       ...activeBuiltIns,
       ...(input.execute

package/src/ai/chat/blocks.tsx

@@ -283,7 +283,7 @@ export function ApprovalBlockView(props: { turnId: string; block: ToolBlock }) {
             <div class="mt-4 flex flex-col gap-4 text-xs leading-5 text-secondary">
               <p class="whitespace-pre-wrap">{description()}</p>
               <Show when={inlineReviewDetails().length > 0}>
-                <dl class="grid gap-x-5 gap-y-1.5 border-t border-[var(--k2b-border)] pt-3 sm:grid-cols-[max-content_minmax(0,1fr)]">
+                <dl class="grid gap-x-5 gap-y-1.5 sm:grid-cols-[max-content_minmax(0,1fr)]">
                   <For each={inlineReviewDetails()}>
                     {(detail) => (
                       <>
@@ -313,7 +313,12 @@ export function ApprovalBlockView(props: { turnId: string; block: ToolBlock }) {
                         </pre>
                       }
                     >
-                      <div class="max-h-72 overflow-auto text-xs text-secondary" role="region" tabIndex={0} aria-label={detail.label}>
+                      <div
+                        class="-mx-2 max-h-72 overflow-auto px-2 text-xs text-secondary"
+                        role="region"
+                        tabIndex={0}
+                        aria-label={detail.label}
+                      >
                         <MarkdownView class="cloud-ai-approval-detail" markdown={detail.value} headingScale="compact" allowImages={false} />
                       </div>
                     </Show>
@@ -323,10 +328,12 @@ export function ApprovalBlockView(props: { turnId: string; block: ToolBlock }) {
             </div>
           </Show>
         </div>
-        <footer
-          class="flex min-h-12 flex-wrap items-center gap-2 border-t border-[var(--k2b-border)] bg-[var(--k2b-surface-subtle)] px-4 py-2.5"
-          data-ai-approval-footer
-        >
+        {/* The decision continues the card below its content: spacing, not a line or a band, sets it apart. */}
+        <footer class="flex min-h-12 flex-wrap items-center gap-2 px-4 pb-3" data-ai-approval-footer>
+          {/* Present from the start, so screen readers announce progress after the decision buttons leave. */}
+          <span class="k2b-sr-only" role="status" aria-live="polite">
+            {approval.loading() ? t().submitting : submitted() ? t().submitted : ""}
+          </span>
           <Show when={reviewLinks().length > 0}>
             <nav class="flex flex-wrap gap-1" aria-label={t().linksFor({ title: title() })}>
               <For each={reviewLinks()}>
@@ -339,7 +346,9 @@ export function ApprovalBlockView(props: { turnId: string; block: ToolBlock }) {
             </nav>
           </Show>
           <Show when={approval.error()}>
-            <p class="text-xs text-red-700 dark:text-red-300">{t().approvalFailed}</p>
+            <p class="text-xs text-red-700 dark:text-red-300" role="alert">
+              {t().approvalFailed}
+            </p>
           </Show>
           <div class="ml-auto shrink-0">
             <Show