@k2b/cloud 0.27.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -30,6 +30,7 @@
     "./server/*": "./src/server/*",
     "./browser": "./src/server/api-client.ts",
     "./browser/app-approval": "./src/browser/app-approval.ts",
+    "./browser/app-badges": "./src/browser/app-badges.ts",
     "./browser/live": "./src/browser/live.ts",
     "./browser/mermaid": "./src/browser/mermaid.ts",
     "./browser/reload": "./src/browser/reload.ts",
@@ -52,6 +53,7 @@
     "./cli/admin": "./src/cli/admin/index.ts",
     "./shared": "./src/shared/index.ts",
     "./services": "./src/services/index.ts",
+    "./services/image-metadata": "./src/services/image-metadata.ts",
     "./services/document-extraction": "./src/services/document-extraction.ts",
     "./services/ipa/service-account": null,
     "./services/*": "./src/services/*",
@@ -98,10 +100,10 @@
     "@simplewebauthn/server": "14.0.3",
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
-    "@k2b/nessi": "0.15.0",
-    "@k2b/ssr": "0.14.0",
-    "@k2b/ui": "0.17.0",
-    "@k2b/stdlib": "0.27.0",
+    "@k2b/nessi": "0.17.0",
+    "@k2b/ssr": "0.15.0",
+    "@k2b/ui": "0.19.0",
+    "@k2b/stdlib": "0.28.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",
     "@nats-io/transport-node": "3.4.0",

package/src/_internal/cli-plugins.ts

@@ -94,6 +94,24 @@ export const buildCliPlugin = async (params: {
     minify: true,
     // Playwright references this optional BiDi adapter lazily; Cloud uses CDP.
     external: ["chromium-bidi/*"],
+    plugins: [
+      {
+        name: "playwright-metadata",
+        setup(build) {
+          build.onLoad({ filter: /[/\\]playwright-core[/\\]lib[/\\](?:coreBundle|serverRegistry|package)\.js$/ }, async ({ path }) => ({
+            // Computed package-relative JSON requires evade Bun's dependency
+            // graph and retain the container's absolute path. Static requires
+            // carry the version and browser registry in the single-file plugin.
+            contents: (await readFile(path, "utf8")).replace(
+              /require\(import_path\d*\.default\.join\(packageRoot, "(package|browsers)\.json"\)\)/g,
+              (_, file: string) => `require("../${file}.json")`,
+            ),
+            loader: "js",
+            resolveDir: dirname(path),
+          }));
+        },
+      },
+    ],
   });
   if (!result.success) {
     throw new Error(`CLI module "${name}" failed to bundle:\n${result.logs.map((log) => String(log)).join("\n")}`);

package/src/_internal/define-app.ts

@@ -86,6 +86,7 @@ import { configurePostgresApplicationName } from "./postgres-application-name";
 import { getProcessSync, startProcessSync } from "./process-sync";
 import { APP_READINESS_PATH, appReadinessResponse } from "./readiness";
 import { appRegistry, type CapabilityRegistryRecord, capabilityRegistry } from "./registry";
+import { canonicalRoute, isOwnNavBadge } from "./registry-validation";
 import { ensureRuntimeWatcher, getCurrentRuntime, stopRuntimeWatcher } from "./runtime-watcher";
 import { servePublicAsset } from "./static-assets";
 import { createStatusPreservingSsrHandler } from "./status-preserving-ssr";
@@ -144,6 +145,13 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
     section: "primary" | "more" | "hidden";
     requiresAuth?: boolean;
     requiresRoles?: Role[];
+    /**
+     * Same-origin path of a `GET` route this app serves below one of its
+     * `routes`. After the page loads, the shell reads it with the person's
+     * session and shows the returned `AppNavBadge` count on the app's icon in
+     * the rail and the app grid. Protect it like any other route.
+     */
+    badge?: string;
   };
   /**
    * Settings owned by this app, declared as a map of dotted-key → definition.
@@ -332,11 +340,6 @@ export type AppDefinition<S extends AppSettingsMap = {}, N extends NotificationD
 // ── Implementation ──────────────────────────────────────────────────────────
 
 const isPwaPath = (route: string): boolean => route === "/pwa" || route.startsWith("/pwa/");
-/** A route as the gateway reads it: trimmed and without empty segments, so `//pwa/x/` is `/pwa/x`. */
-const canonicalRoute = (route: string): string => {
-  const trimmed = route.trim();
-  return trimmed.startsWith("/") ? `/${trimmed.split("/").filter(Boolean).join("/")}` : trimmed;
-};
 
 /**
  * `/pwa` belongs to the mobile app shell, `/pwa/_auth` to Core, and `/pwa/<id>`
@@ -357,6 +360,14 @@ const validateAppPwaPart = (opts: Pick<AppOptions, "id" | "routes" | "pwa">): Ap
   return { href: `/pwa/${opts.id}`, requiresRoles: opts.pwa.requiresRoles ? [...opts.pwa.requiresRoles] : undefined };
 };
 
+/** The badge route is read by the browser through the gateway, so it must be one of this app's own paths. */
+const validateAppNavBadge = (opts: Pick<AppOptions, "id" | "routes" | "nav">): void => {
+  const badge = opts.nav?.badge;
+  if (badge !== undefined && !isOwnNavBadge(badge, opts.routes)) {
+    throw new Error(`App "${opts.id}" declares nav.badge "${badge}"; it must be a same-origin path below one of its routes`);
+  }
+};
+
 export const defineApp = <
   const S extends AppSettingsMap = {},
   const N extends NotificationDefinitionMap = {},
@@ -369,6 +380,7 @@ export const defineApp = <
   const notifications = bindNotificationDefinitions(opts.id, opts.notifications);
   const cliModules = validateAppCliModules(opts.id, opts.cli);
   const pwaPart = validateAppPwaPart(opts);
+  validateAppNavBadge(opts);
 
   // ── 0. Register declared settings into the runtime registry ──────────
   // SETTINGS_MAP is the single source of truth for validation in store.ts
@@ -387,6 +399,9 @@ export const defineApp = <
     rootDir,
     componentRoots: [resolve(env.APP_DIR ?? rootDir, "src"), fileURLToPath(new URL("../", import.meta.url))],
     basePath: opts.basePath,
+    // Every island instance already mounts inside its own error boundary; this
+    // only gives the fallback Cloud's look and the reader's language.
+    errorFallback: fileURLToPath(new URL("../ssr/IslandError.tsx", import.meta.url)),
     template: ({ body, scripts, title, description, theme, lang, performanceRoute, pwa }) => {
       const themeFixed = theme !== undefined;
       // App pages paint the canvas before any stylesheet and give it to the
@@ -571,6 +586,7 @@ export const defineApp = <
                 section: meta.nav?.section ?? "hidden",
                 requiresAuth: meta.nav?.requiresAuth,
                 requiresRoles: meta.nav?.requiresRoles,
+                badge: meta.nav?.badge,
                 adminHref: meta.adminHref,
               }
             : undefined,

package/src/_internal/registry-validation.ts

@@ -7,6 +7,32 @@ const isString = (value: unknown): value is string => typeof value === "string";
 const isStringArray = (value: unknown): value is string[] => Array.isArray(value) && value.every(isString);
 const isStringRecord = (value: unknown): value is Record<string, string> => isRecord(value) && Object.values(value).every(isString);
 
+/** An absolute path on the current origin: one leading slash, no backslash or whitespace. */
+const SAME_ORIGIN_PATH = /^\/(?![\/\\])[^\\\s]*$/;
+
+/** A route as the gateway reads it: trimmed and without empty segments, so `//pwa/x/` is `/pwa/x`. */
+export const canonicalRoute = (route: string): string => {
+  const trimmed = route.trim();
+  return trimmed.startsWith("/") ? `/${trimmed.split("/").filter(Boolean).join("/")}` : trimmed;
+};
+
+/**
+ * Whether a `nav.badge` path stays below one of the app's own `routes`. It is
+ * checked on the path the browser actually requests, after dot segments, and
+ * never starts with `//`, which a URL resolver reads as another host.
+ */
+export const isOwnNavBadge = (badge: string, routes: readonly string[]): boolean => {
+  if (!SAME_ORIGIN_PATH.test(badge)) return false;
+  const path = new URL(badge, "https://cloud.invalid").pathname;
+  return (
+    !path.startsWith("//") &&
+    routes.some((route) => {
+      const prefix = canonicalRoute(route);
+      return prefix === "/" || path === prefix || path.startsWith(`${prefix}/`);
+    })
+  );
+};
+
 const invalid = (path: string, expected: string): string => `${path} must be ${expected}`;
 
 export const validateAppRegistryEntry = (value: unknown): string | null => {
@@ -61,6 +87,9 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
     if (value.nav.requiresRoles !== undefined && !isStringArray(value.nav.requiresRoles)) {
       return invalid("nav.requiresRoles", "an array of strings");
     }
+    if (value.nav.badge !== undefined && (!isString(value.nav.badge) || !isOwnNavBadge(value.nav.badge, value.routes))) {
+      return invalid("nav.badge", "a same-origin path below one of the entry's routes");
+    }
   }
   if (value.adminNav !== undefined) {
     if (
@@ -98,7 +127,7 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
           !link.label.trim() ||
           (link.description !== undefined && !isString(link.description)) ||
           !isString(link.href) ||
-          !/^\/(?![\/\\])[^\\\s]*$/.test(link.href) ||
+          !SAME_ORIGIN_PATH.test(link.href) ||
           (link.icon !== undefined && !isString(link.icon)) ||
           (link.keywords !== undefined && !isStringArray(link.keywords)),
       )

package/src/_internal/runtime-context.ts

@@ -55,6 +55,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
             // Registry stores roles as serialized strings; the source type is
             // Role[] and round-trip is value-preserving.
             requiresRoles: e.nav.requiresRoles as Role[] | undefined,
+            badge: e.nav.badge,
           }
         : undefined,
       help: e.help ? { ...e.help } : undefined,

package/src/access/PermissionEditor.tsx

@@ -1,6 +1,6 @@
 import { mutation } from "@k2b/stdlib/solid";
 import { IconButton, Placeholder, prompts, SelectChip, Tooltip, useLocale } from "@k2b/ui";
-import { For, Show } from "solid-js";
+import { createMemo, For, Show } from "solid-js";
 import { createStore } from "solid-js/store";
 import { CloudAvatar } from "../account/Avatar";
 import type { AccessEntry, PermissionLevel, Principal, ServiceAccountKind } from "../contracts/shared";
@@ -52,6 +52,13 @@ type PermissionEditorProps = {
    *  account), its row can neither be lowered nor removed. */
   revokeAccess: (accessId: string) => Promise<void>;
 
+  /** The entries that still apply when the resource lets one entry shadow
+   *  another, such as a `none` that overrides the same principal's `admin`.
+   *  The editor counts managers only among them, so pass the same function
+   *  the service applies before `ensureManagerRemains()`. Defaults to every
+   *  entry. */
+  effectiveEntries?: (entries: readonly AccessEntry[]) => readonly AccessEntry[];
+
   /** Allow granting `public` access from this editor. */
   allowPublic?: boolean;
 
@@ -218,10 +225,10 @@ export default function PermissionEditor(props: PermissionEditorProps) {
   });
   const busy = () => grantMut.loading() || updateMut.loading() || revokeMut.loading();
   // The service refuses to remove the last manager; the row says so up front.
-  const lastManagerId = () => {
-    const managers = entries.filter(isManagerEntry);
+  const lastManagerId = createMemo(() => {
+    const managers = (props.effectiveEntries?.(entries) ?? entries).filter(isManagerEntry);
     return managers.length === 1 ? managers[0]!.id : null;
-  };
+  });
 
   return (
     <div class="flex flex-col gap-3">

package/src/ai/assistant-models.ts

@@ -2,8 +2,9 @@ import type { AccessSubject, RequestActor } from "../server";
 import { aiModelAccess } from "./model-access";
 import { personalAiModelPolicy } from "./personal-agent";
 import { listAiModels, toPublicAiSettingsState } from "./settings";
-import { resolveAiAudioModel } from "./transcription";
-import type { AiChatTurnRunConfig, AiModelPolicy, AiSettingsError } from "./types";
+import { type AiResolvedAudioModel, AiTranscriptionError, resolveAiAudioModel } from "./transcription";
+import type { AiChatTurnRunConfig, AiDataBoundary, AiModelPolicy, AiSettingsError } from "./types";
+import { isAiSettingsError } from "./validate";
 
 export const aiChatAccessSubject = (actor: RequestActor | undefined): AccessSubject | null => {
   if (!actor) return null;
@@ -20,14 +21,34 @@ export const isAssistantChatTurn = (config: AiChatTurnRunConfig): boolean => con
 export const listAssistantAiModels = async (subject: AccessSubject | null, policy: AiModelPolicy = personalAiModelPolicy) =>
   aiModelAccess.filterModels(await listAiModels(policy), subject);
 
+/** The one audio check behind the composer microphone, dictation, and offering and running transcribe_audio. */
+export const resolveAssistantAudioModel = async (
+  subject: AccessSubject | null,
+  allowedDataBoundaries?: AiDataBoundary[],
+): Promise<AiResolvedAudioModel> => {
+  const model = await resolveAiAudioModel({ allowedDataBoundaries });
+  try {
+    await aiModelAccess.assertAllowed(model.profile.id, subject);
+  } catch (error) {
+    if (!isAiSettingsError(error) || error.aiError.code !== "model_access_denied") throw error;
+    throw Object.assign(
+      new AiTranscriptionError(
+        "transcription_access_denied",
+        "Audio transcription is not available to you: you do not have access to the audio model. An administrator can grant access in the AI settings.",
+      ),
+      { aiError: error.aiError },
+    );
+  }
+  return model;
+};
+
 export const assistantAiSettingsState = async (subject: AccessSubject | null) => {
   const [status, models, audioModelConfigured] = await Promise.all([
     toPublicAiSettingsState(personalAiModelPolicy.allowedDataBoundaries),
     listAssistantAiModels(subject),
     (async () => {
       try {
-        const model = await resolveAiAudioModel({ allowedDataBoundaries: personalAiModelPolicy.allowedDataBoundaries });
-        await aiModelAccess.assertAllowed(model.profile.id, subject);
+        await resolveAssistantAudioModel(subject, personalAiModelPolicy.allowedDataBoundaries);
         return true;
       } catch {
         return false;

package/src/ai/audio-tool.ts

@@ -1,10 +1,9 @@
 import { z } from "zod";
-import { aiChatAccessSubject } from "./assistant-models";
+import { aiChatAccessSubject, resolveAssistantAudioModel } from "./assistant-models";
 import { aiProjectFilePathFromMount } from "./file-mount";
 import { aiFileStore, normalizeAiFilePath } from "./files-store";
-import { aiModelAccess } from "./model-access";
 import { defineAiTool } from "./tools";
-import { type AiResolvedAudioModel, resolveAiAudioModel, runAiTranscription } from "./transcription";
+import { type AiResolvedAudioModel, runAiTranscription } from "./transcription";
 
 export const CloudAiTranscribeAudioInputSchema = z.object({
   path: z.string().trim().min(1).describe("Absolute path of the stored audio file. Project files are below /project."),
@@ -53,13 +52,7 @@ export const createCloudAiTranscribeAudioTool = (options: { resolveModel?: () =>
       signal: ctx.signal,
       allowedDataBoundaries: ctx.allowedDataBoundaries,
       attribution: { conversationId: ctx.conversationId, turnId: ctx.turnId },
-      resolveModel:
-        options.resolveModel ??
-        (async () => {
-          const resolved = await resolveAiAudioModel({ allowedDataBoundaries: ctx.allowedDataBoundaries });
-          await aiModelAccess.assertAllowed(resolved.profile.id, aiChatAccessSubject(ctx.actor));
-          return resolved;
-        }),
+      resolveModel: options.resolveModel ?? (() => resolveAssistantAudioModel(aiChatAccessSubject(ctx.actor), ctx.allowedDataBoundaries)),
     });
     ctx.signal.throwIfAborted();
     const producerCallKey = `${ctx.turnId}:${ctx.callId}`;

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. Test runs use real shared and personal data; writes and capability effects keep normal permissions and approvals.",
+        "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")
@@ -91,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();
@@ -179,11 +149,11 @@ 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>;
@@ -197,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,6 +1,7 @@
 export {
   CODE_RUNTIME_TOOL_NAMES,
   CodeActionInput,
+  CodeCheckInput,
   CodeResourceId,
   CodeRuntimeInput,
   CodeToolFailure,

package/src/ai/capabilities.ts

@@ -14,6 +14,7 @@ import {
 import type { CapabilityRegistryEntry } from "../contracts/registry";
 import type { RequestActor } from "../server";
 import { createHelpReader, type HelpReaderFactory } from "../services/help";
+import { type MandatePolicyV1, mandatePolicyCanPermitCapability } from "../services/mandates/policy";
 import { resolveAppIdentityPresentation } from "../shared/app-presentation";
 import { recordRejectedAiCapability } from "./capability-execution";
 import { CODE_SOURCE_TOOLS } from "./code-source-contracts";
@@ -76,7 +77,7 @@ 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;
+ * - `not_allowed`: the conversation's fixed tool scope or task grants exclude 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;
@@ -475,8 +476,8 @@ export const createAiToolMetaTools = (input: {
   store: ToolStateStore;
   maxLoadedTools?: number;
   unavailableLoadedNames?: readonly string[];
-  /** False when this turn offers no app operations at all. */
-  appOperationsOffered?: boolean;
+  /** Whether this turn offers app operations, offers none, or its fixed scope or task grants exclude all of them. */
+  appOperations?: "not_offered" | "not_allowed" | "offered";
   /** Why a requested name that is not in `catalog` cannot be loaded; defaults to `unknown`. */
   unavailableReason?: (name: string) => AiToolUnavailableReason;
 }): AiRuntimeTool[] => {
@@ -494,9 +495,11 @@ export const createAiToolMetaTools = (input: {
   const liveAppDirectory =
     directoryEntries.length > 0
       ? ` Live capability apps: ${directoryEntries.join(", ")}${hiddenAppCount > 0 ? `, and ${hiddenAppCount} more` : ""}.`
-      : input.appOperationsOffered === false
+      : input.appOperations === "not_offered"
         ? " 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.";
+        : input.appOperations === "not_allowed"
+          ? " This chat's tool scope or task grants allow no app operations. Do not search for app operations in this turn; continue with the available tools or tell the user which grant is missing."
+          : " 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
@@ -542,7 +545,7 @@ 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. 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.",
+      "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 or task grants exclude 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({
@@ -689,6 +692,8 @@ export const createAiToolResolver =
     actor: RequestActor;
     staticTools: AiRuntimeTool[];
     allowedTools?: readonly string[] | null;
+    /** Undefined for interactive runs; null fails closed when a background mandate cannot be loaded. */
+    mandatePolicy?: MandatePolicyV1 | 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">;
@@ -725,7 +730,19 @@ export const createAiToolResolver =
     }
     const allowed = input.allowedTools == null ? null : new Set(input.allowedTools);
     const fullCapabilityCatalog = buildAiCapabilityCatalog(registry, input.locale);
-    const capabilityCatalog = fullCapabilityCatalog.filter((entry) => !allowed || allowed.has(entry.name));
+    const mandateAllows = (entry: AiCapabilityCatalogEntry) =>
+      input.mandatePolicy === undefined ||
+      (input.mandatePolicy !== null &&
+        mandatePolicyCanPermitCapability(input.mandatePolicy, {
+          appId: entry.appId,
+          capabilityId: entry.operation.localId,
+          kind: entry.kind,
+          approval: entry.kind === "action" && "approval" in entry.operation ? entry.operation.approval : undefined,
+        }));
+    const mandateExcluded = new Set(
+      fullCapabilityCatalog.filter((entry) => !mandateAllows(entry)).flatMap((entry) => [entry.name, entry.providerName]),
+    );
+    const capabilityCatalog = fullCapabilityCatalog.filter((entry) => (!allowed || allowed.has(entry.name)) && mandateAllows(entry));
     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"))
@@ -753,24 +770,33 @@ export const createAiToolResolver =
     // App operation IDs always contain a dot; built-in names never do.
     const unavailableReason = (requested: string): AiToolUnavailableReason => {
       const name = loadedByProviderName.get(requested) ?? requested;
+      if (mandateExcluded.has(name)) return "not_allowed";
       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";
     };
+    // Independent of which apps are live: the fixed scope or task grants name no app operation at all.
+    const scopeExcludesAppOperations =
+      input.mandatePolicy === null ||
+      (input.mandatePolicy?.grants !== undefined && !input.mandatePolicy.grants.some((grant) => "appId" in grant)) ||
+      (allowed !== null && ![...allowed].some((name) => name.includes(".")));
     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 = [
       ...createAiToolMetaTools({
-        apps: allowed ? registry.filter((app) => capabilityCatalog.some((entry) => entry.appId === app.appId)) : registry,
+        apps:
+          allowed || input.mandatePolicy !== undefined
+            ? registry.filter((app) => capabilityCatalog.some((entry) => entry.appId === app.appId))
+            : registry,
         catalog,
         eagerNames,
         conversationId: input.conversationId,
         store: input.store,
         maxLoadedTools: input.maxLoadedTools,
         unavailableLoadedNames,
-        appOperationsOffered: Boolean(input.listRegistry),
+        appOperations: !input.listRegistry ? "not_offered" : scopeExcludesAppOperations ? "not_allowed" : "offered",
         unavailableReason,
       }),
       ...activeBuiltIns,