@k2b/cloud 0.38.0 → 0.40.0

package/src/_internal/registry-validation.ts

@@ -1,37 +1,14 @@
 import { CLOUD_CLI_MODULE_NAME } from "../cli/plugin";
 import { PlatformPermissionSchema } from "../contracts/outgoing-mail";
 import type { AppRegistryEntry } from "../contracts/registry";
+import { isOwnAppPath, SAME_ORIGIN_PATH } from "./app-path";
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
 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}/`);
-    })
-  );
-};
+export { canonicalRoute, isOwnAppPath } from "./app-path";
 
 const invalid = (path: string, expected: string): string => `${path} must be ${expected}`;
 
@@ -69,6 +46,12 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
       if (!isRecord(translation)) return invalid(`presentation.translations.${locale}`, "an object");
       if (translation.name !== undefined && !isString(translation.name))
         return invalid(`presentation.translations.${locale}.name`, "a string");
+      if (
+        translation.panelLabel !== undefined &&
+        (!isString(translation.panelLabel) || !translation.panelLabel.trim() || value.panel === undefined)
+      ) {
+        return invalid(`presentation.translations.${locale}.panelLabel`, "a non-empty string for a declared panel");
+      }
       if (translation.description !== undefined && !isString(translation.description)) {
         return invalid(`presentation.translations.${locale}.description`, "a string");
       }
@@ -87,10 +70,22 @@ 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))) {
+    if (value.nav.badge !== undefined && (!isString(value.nav.badge) || !isOwnAppPath(value.nav.badge, value.routes))) {
       return invalid("nav.badge", "a same-origin path below one of the entry's routes");
     }
   }
+  if (value.panel !== undefined) {
+    if (!isRecord(value.panel)) return invalid("panel", "an object");
+    if (!isString(value.panel.href) || !isOwnAppPath(value.panel.href, value.routes)) {
+      return invalid("panel.href", "a same-origin path below one of the entry's routes");
+    }
+    for (const field of ["label", "icon"] as const) {
+      if (!isString(value.panel[field]) || !value.panel[field].trim()) return invalid(`panel.${field}`, "a non-empty string");
+    }
+    if (value.panel.requiresRoles !== undefined && !isStringArray(value.panel.requiresRoles)) {
+      return invalid("panel.requiresRoles", "an array of strings");
+    }
+  }
   if (value.adminNav !== undefined) {
     if (
       !Array.isArray(value.adminNav) ||

package/src/_internal/runtime-context.ts

@@ -58,6 +58,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
             badge: e.nav.badge,
           }
         : undefined,
+      panel: e.panel ? { ...e.panel, requiresRoles: e.panel.requiresRoles ? [...e.panel.requiresRoles] : undefined } : undefined,
       help: e.help ? { ...e.help } : undefined,
       searchTags,
       searchHelp: searchQueries?.map((query) => query.description).join(" "),

package/src/_internal/runtime-watcher.ts

@@ -19,6 +19,7 @@ import { buildRuntimeFromRegistry } from "./runtime-context";
 const log = logger("runtime-watcher");
 
 let current: CloudRuntime | undefined;
+let coreRelease: string | undefined;
 let initPromise: Promise<void> | undefined;
 let watcherTask: Promise<void> | undefined;
 let abort: AbortController | undefined;
@@ -27,8 +28,12 @@ const refresh = async () => {
   const apps = await listApps();
   const capabilities = await listCapabilities(apps);
   current = buildRuntimeFromRegistry(apps, capabilities);
+  coreRelease = apps.find((app) => app.id === "core")?.runtime?.release;
 };
 
+/** Core's release from the live registry, absent before initialization and after shutdown. */
+export const registeredCoreRelease = (): string | undefined => coreRelease;
+
 export const ensureRuntimeWatcher = (): Promise<void> => {
   // Concurrent callers (start() + first request) wait on the same init —
   // returning before `current` is populated would race getCurrentRuntime().
@@ -68,6 +73,7 @@ export const stopRuntimeWatcher = async (): Promise<void> => {
   watcherTask = undefined;
   initPromise = undefined;
   current = undefined;
+  coreRelease = undefined;
 };
 
 export const getCurrentRuntime = (): CloudRuntime => {

package/src/_internal/static-assets.ts

@@ -1,7 +1,43 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
 import { resolve, sep } from "node:path";
 import type { Context } from "hono";
 
 const publicRoot = resolve(process.cwd(), "public");
+const versions = new Map<string, { size: number; mtimeMs: number; version: string }>();
+
+/**
+ * Version of Core's shared stylesheets: the release, which names one build. `local` and `development` are the
+ * defaults of unnamed builds and name many, so those sheets get no version and are revalidated instead.
+ */
+export function sharedStylesheetVersion(release: string | undefined): string | undefined {
+  return !release || release === "local" || release === "development" ? undefined : release;
+}
+
+/**
+ * Content version of a file below `public/`: hashed on first use and re-hashed only when the file's size or
+ * modification time changes; a missing or unreadable file has no version.
+ */
+export function publicFileVersion(pathname: string): string | undefined {
+  const path = resolvePublicAsset(pathname);
+  if (!path) return undefined;
+  try {
+    const stat = statSync(path, { throwIfNoEntry: false });
+    if (!stat?.isFile()) return undefined;
+    const cached = versions.get(path);
+    if (cached && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs) return cached.version;
+    const version = createHash("sha256").update(readFileSync(path)).digest("hex").slice(0, 16);
+    versions.set(path, { size: stat.size, mtimeMs: stat.mtimeMs, version });
+    return version;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Append a URL-encoded version only when the asset has one. */
+export function versionedPublicHref(pathname: string, version: string | undefined): string {
+  return version === undefined ? pathname : `${pathname}?v=${encodeURIComponent(version)}`;
+}
 
 function decodePathname(pathname: string): string | null {
   try {
@@ -48,14 +84,15 @@ async function encodedFile(path: string, encoding: "br" | "gzip"): Promise<Bun.B
   return (await file.exists()) ? file : null;
 }
 
-export function servePublicAsset(isDevelopment: boolean) {
+export function servePublicAsset(isDevelopment: boolean, sharedVersion?: string) {
   return async (c: Context) => {
     if (c.req.method !== "GET" && c.req.method !== "HEAD") {
       c.header("Allow", "GET, HEAD");
       return c.text("Method Not Allowed", 405);
     }
 
-    const path = resolvePublicAsset(new URL(c.req.url).pathname);
+    const url = new URL(c.req.url);
+    const path = resolvePublicAsset(url.pathname);
     if (!path) return c.notFound();
 
     const sourceFile = Bun.file(path);
@@ -84,8 +121,20 @@ export function servePublicAsset(isDevelopment: boolean) {
     // Development rebuilds files in place under the same address, so the browser asks again on every use; an
     // unchanged file then costs one round trip instead of its whole size on every page.
     const etag = `"${selectedEncoding ?? "identity"}-${selected.size.toString(36)}-${selected.lastModified.toString(36)}"`;
+    // The page head links these files with the version this process names for them. Any other version may name
+    // other content (a rolling deploy, an app started before a Core redeploy), so it is revalidated, never kept.
+    let cacheControl = isDevelopment ? "no-cache" : "public, max-age=31536000, immutable";
+    if (!isDevelopment) {
+      const pathname = decodePathname(url.pathname)!;
+      const shared = /^\/public\/(fonts|tabler-icons|global)\.css$/.test(pathname);
+      const own = /^\/public\/[^/]+\/(app\.css|favicon\.svg)$/.test(pathname);
+      if (shared || own) {
+        const expected = shared ? sharedVersion : publicFileVersion(url.pathname);
+        if (expected === undefined || url.searchParams.get("v") !== expected) cacheControl = "no-cache";
+      }
+    }
     const headers = new Headers({
-      "Cache-Control": isDevelopment ? "no-cache" : "public, max-age=31536000, immutable",
+      "Cache-Control": cacheControl,
       ETag: etag,
       Vary: "Accept-Encoding",
     });

package/src/_internal/status-preserving-ssr.ts

@@ -2,6 +2,7 @@ import type { HtmlFn, RenderFn } from "@k2b/ssr";
 import { createSSRHandler } from "@k2b/ssr/hono";
 import type { Context, Env, MiddlewareHandler, TypedResponse } from "hono";
 import type { StatusCode } from "hono/utils/http-status";
+import type { PanelConsentSnapshot } from "../contracts/panel-context";
 import type { RailSnapshot } from "../contracts/rail-preferences";
 import type { SettingsFlat, Unflatten } from "../contracts/settings-types";
 import type { User } from "../contracts/shared";
@@ -13,6 +14,7 @@ type PageEnv<T extends object> = {
     page: Partial<T>;
     user?: User;
     railPreferences?: RailSnapshot;
+    panelConsent?: PanelConsentSnapshot;
     settings?: Unflatten<SettingsFlat<typeof CORE_SETTINGS>>;
   };
 };

package/src/access/PermissionEditor.browser-harness.tsx

@@ -1,46 +1,65 @@
 import { LocaleProvider } from "@k2b/ui";
+import { createSignal, onCleanup, Show } from "solid-js";
 import { render } from "solid-js/web";
+import type { AccessEntry } from "../contracts/shared";
 import PermissionEditor from "./PermissionEditor";
 
 const host = document.getElementById("root");
 if (!host) throw new Error("Missing harness root");
-render(
-  () => (
+render(() => {
+  let saved: AccessEntry[] = ["Mara Lind", "Lea Sommer", "Jonas Weber"].map((displayName, index) => ({
+    id: `access-${index}`,
+    principal: { type: "user", userId: `user-${index}` },
+    displayName,
+    permission: "read",
+    createdAt: "2026-10-15T07:00:00.000Z",
+  }));
+  const [data, setData] = createSignal(saved);
+  const refetch = () => {
+    // Like a consumer's query: fresh objects contain the saved level and another person's change.
+    saved = saved.map((entry, index) => ({
+      ...entry,
+      principal: { ...entry.principal },
+      ...(index === 2 ? { permission: "write" as const } : {}),
+    }));
+    setData(saved);
+  };
+  document.addEventListener("refetch-access", refetch);
+  onCleanup(() => document.removeEventListener("refetch-access", refetch));
+  return (
     <LocaleProvider locale="en">
-      <PermissionEditor
-        initialEntries={["Mara Lind", "Lea Sommer", "Jonas Weber"].map((displayName, index) => ({
-          id: `access-${index}`,
-          principal: { type: "user", userId: `user-${index}` },
-          displayName,
-          permission: "read",
-          createdAt: "2026-10-15T07:00:00.000Z",
-        }))}
-        // Equal-width labels isolate pending-state layout from a normal change in label width.
-        allowedLevels={[
-          { level: "read", label: "Level 1" },
-          { level: "write", label: "Level 2" },
-        ]}
-        allowAuthenticated={false}
-        grantAccess={async () => {
-          throw new Error("Not used");
-        }}
-        updateAccess={() =>
-          new Promise<void>((resolve) => {
-            // The test waits for this mark, so it does not depend on how the editor shows a pending change.
-            document.documentElement.dataset.saving = "true";
-            document.addEventListener(
-              "settle-access",
-              () => {
-                delete document.documentElement.dataset.saving;
-                resolve();
-              },
-              { once: true },
-            );
-          })
-        }
-        revokeAccess={async () => {}}
-      />
+      <Show when={data()}>
+        {(entries) => (
+          <PermissionEditor
+            initialEntries={entries()}
+            // Equal-width labels isolate pending-state layout from a normal change in label width.
+            allowedLevels={[
+              { level: "read", label: "Level 1" },
+              { level: "write", label: "Level 2" },
+            ]}
+            allowAuthenticated={false}
+            grantAccess={async () => {
+              throw new Error("Not used");
+            }}
+            updateAccess={(id, permission) =>
+              new Promise<void>((resolve) => {
+                // Existing tests use this mark and event to control the save.
+                document.documentElement.dataset.saving = "true";
+                document.addEventListener(
+                  "settle-access",
+                  () => {
+                    saved = saved.map((entry) => (entry.id === id ? { ...entry, permission } : entry));
+                    delete document.documentElement.dataset.saving;
+                    resolve();
+                  },
+                  { once: true },
+                );
+              })
+            }
+            revokeAccess={async () => {}}
+          />
+        )}
+      </Show>
     </LocaleProvider>
-  ),
-  host,
-);
+  );
+}, host);

package/src/access/PermissionEditor.tsx

@@ -1,6 +1,6 @@
 import { mutation } from "@k2b/stdlib/solid";
 import { announce, IconButton, Placeholder, prompts, SelectChip, Tooltip, useLocale } from "@k2b/ui";
-import { createMemo, createSignal, For, onCleanup, Show } from "solid-js";
+import { createEffect, createMemo, createSignal, For, onCleanup, Show } from "solid-js";
 import { createStore, reconcile } from "solid-js/store";
 import { CloudAvatar } from "../account/Avatar";
 import type { AccessEntry, PermissionLevel, Principal, ServiceAccountKind } from "../contracts/shared";
@@ -27,9 +27,9 @@ export type GrantableLevel = Exclude<PermissionLevel, "none">;
 export type AllowedLevel = GrantableLevel | { level: GrantableLevel; scope?: string; label?: string; icon?: string; description?: string };
 
 type PermissionEditorProps = {
-  /** Initial access entries — caller stays the source of truth for
-   *  what's stored on the resource; the editor updates its local copy
-   *  after successful mutations. */
+  /** The editor mounts from this list and merges later lists by entry id once no change is saving.
+   *  Rows the caller changed since its last list win; unchanged rows keep the editor's confirmed result.
+   *  Keep the editor mounted (no keyed Show or unmount during refresh) and pass refetched data. */
   initialEntries: AccessEntry[];
 
   /** Whether the current user can edit permissions. When `false`, the
@@ -179,7 +179,9 @@ export default function PermissionEditor(props: PermissionEditorProps) {
   const t = () => accessMessages.resolve([locale()]).t;
   // A store keeps each row's identity across level changes, so an expanded member list stays open. It holds
   // copies: store writes go into the objects themselves, and the caller's entries are not the editor's to change.
-  const [entries, setEntries] = createStore<AccessEntry[]>(props.initialEntries.map((entry) => ({ ...entry })));
+  const initialEntries = props.initialEntries;
+  let appliedCallerEntries = new Map(initialEntries.map((entry) => [entry.id, JSON.stringify(entry)]));
+  const [entries, setEntries] = createStore<AccessEntry[]>(initialEntries.map((entry) => ({ ...entry })));
   const [pending, setPending] = createSignal<string | null>(null);
   const grantPending = () => pending() !== null;
   let disposed = false;
@@ -281,6 +283,29 @@ export default function PermissionEditor(props: PermissionEditorProps) {
     },
   });
   const busy = () => grantPending() || updateMut.loading() || revokeMut.loading();
+  createEffect(() => {
+    const next = props.initialEntries;
+    const nextCallerEntries = new Map(next.map((entry) => [entry.id, JSON.stringify(entry)]));
+    // Mutation loading clears before onSuccess; wait for its local writes and onFinally too.
+    if (busy() || updating() !== null || revoking() !== null) return;
+    if (
+      nextCallerEntries.size === appliedCallerEntries.size &&
+      next.every((entry) => nextCallerEntries.get(entry.id) === appliedCallerEntries.get(entry.id))
+    )
+      return;
+    // Rows the caller changed since its last list win; unchanged rows keep the editor's confirmed result.
+    const localEntries = new Map(entries.map((entry) => [entry.id, entry]));
+    const merged: AccessEntry[] = [];
+    for (const entry of next) {
+      const row = nextCallerEntries.get(entry.id) !== appliedCallerEntries.get(entry.id) ? entry : localEntries.get(entry.id);
+      if (row) merged.push({ ...row });
+    }
+    for (const entry of entries) {
+      if (!nextCallerEntries.has(entry.id) && !appliedCallerEntries.has(entry.id)) merged.push({ ...entry });
+    }
+    setEntries(reconcile(merged, { key: "id" }));
+    appliedCallerEntries = nextCallerEntries;
+  });
   // The service refuses to remove the last manager; the row says so up front.
   const lastManagerId = createMemo(() => {
     // A grant on part of the resource never manages it.
@@ -400,7 +425,7 @@ function AccessEntryRow(props: {
         <Show
           when={props.entry.principal.type === "user"}
           fallback={
-            <div class="flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-zinc-200 text-zinc-600 dark:bg-zinc-700 dark:text-zinc-300">
+            <div class="flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-zinc-200 text-secondary dark:bg-zinc-700">
               <i class={`ti ${getPrincipalIcon(props.entry, t())} text-sm`} />
             </div>
           }
@@ -484,7 +509,7 @@ function AccessEntryRow(props: {
               aria-label={t().remove({ name: displayName() })}
               // A disabled button takes no focus and touch has no hover, so the reason also reaches assistive technology.
               aria-description={props.lastManager ? removeLabel() : undefined}
-              class="focus-ui flex h-7 w-7 items-center justify-center rounded text-zinc-400 transition-colors focus:opacity-100 enabled:hover:bg-red-500/[0.08] enabled:hover:text-red-600 dark:enabled:hover:text-red-400"
+              class="focus-ui flex h-7 w-7 items-center justify-center rounded text-dimmed transition-colors focus:opacity-100 enabled:hover:bg-red-500/[0.08] enabled:hover:text-red-600 dark:enabled:hover:text-red-400"
             >
               <i class="ti ti-x text-sm" />
             </IconButton>

package/src/access/ResourceApiKeys.tsx

@@ -176,7 +176,11 @@ export default function ResourceApiKeys(props: ResourceApiKeysProps) {
   const createMutation = mutations.create<{ credential: ResourceApiKey; token: string }, CreateResourceApiKeyInput>({
     mutation: props.createKey,
     onSuccess: async (data) => {
-      setKeys([data.credential, ...keys()]);
+      setKeys((current) =>
+        current.some((key) => key.id === data.credential.id)
+          ? current.map((key) => (key.id === data.credential.id ? data.credential : key))
+          : [data.credential, ...current],
+      );
       await prompts.dialog<void>(() => <TokenDialog token={data.token} />, {
         title: t().keyCreated,
         icon: "ti ti-key",

package/src/account/EntitySearch.tsx

@@ -350,7 +350,7 @@ const ResultRow = (props: {
     <Show
       when={props.avatar}
       fallback={
-        <div class="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-zinc-200 text-xs text-zinc-600 dark:bg-zinc-700 dark:text-zinc-300">
+        <div class="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-zinc-200 text-xs text-secondary dark:bg-zinc-700">
           <i class={`ti ${props.icon} text-sm`} />
         </div>
       }

package/src/ai/action-review.ts

@@ -0,0 +1,101 @@
+import type {
+  CapabilityActionCallReview,
+  CapabilityActionPolicy,
+  CapabilityActionReceipt,
+  CapabilityActionReview,
+  CapabilityActionReviewData,
+  CapabilitySemanticLink,
+} from "../contracts/capabilities";
+
+/**
+ * What the chat stores about one Action call so that a reload shows the same question and receipt even after the app
+ * changed: the app's per-call review as it was when Cloud asked, or, for an app that still returns the old review shape,
+ * that review as literal text. Pure and browser-safe: the server stores it, the chat renders it.
+ */
+
+/** One old review detail: a label and its value, kept complete. */
+export type AiLegacyReviewRow = { label: string; value: string; format?: "date" | "date-time" };
+
+/**
+ * An old review (`message`, `details`, `links`) kept as literal text, never as a template: the message is the question,
+ * every inline or plain-text detail is a row without the 12-row bound, Markdown details are one Markdown block, and
+ * `summary` is the old success summary used as the receipt text.
+ */
+export type AiLegacyActionReview = {
+  legacy: {
+    question: string;
+    rows: AiLegacyReviewRow[];
+    markdown?: string;
+    summary?: string;
+    links?: CapabilitySemanticLink[];
+  };
+};
+
+/** A new review, with `ask` filled from the declared policy when the call itself names no reason. */
+export type AiStoredActionReview = CapabilityActionCallReview | AiLegacyActionReview;
+
+export const isLegacyActionReview = (review: AiStoredActionReview): review is AiLegacyActionReview => "legacy" in review;
+
+/** The old review shape as stored literal text. */
+export const legacyActionReview = (review: CapabilityActionReview): AiLegacyActionReview => {
+  const details = review.details ?? [];
+  // One Markdown block, each detail under its own label, so a reader keeps knowing which text belongs where.
+  const markdown = details
+    .filter((detail) => detail.format === "markdown" && detail.value.trim())
+    .map((detail) => `**${detail.label.replace(/([\\*_`[\]])/g, "\\$1")}**\n\n${detail.value}`)
+    .join("\n\n");
+  return {
+    legacy: {
+      question: review.message,
+      rows: details
+        .filter((detail) => detail.format !== "markdown")
+        .map((detail) => ({
+          label: detail.label,
+          value: detail.value,
+          ...(detail.format === "date" || detail.format === "date-time" ? { format: detail.format } : {}),
+        })),
+      ...(markdown ? { markdown } : {}),
+      ...(review.links?.length ? { links: review.links } : {}),
+    },
+  };
+};
+
+/** The review Cloud stores and shows for one call. */
+export const storedActionReview = (review: CapabilityActionReviewData, policy?: CapabilityActionPolicy | null): AiStoredActionReview => {
+  if (!("sentence" in review)) return legacyActionReview(review);
+  if (review.ask || !policy || !("ask" in policy)) return review;
+  return { ...review, ask: policy.ask };
+};
+
+/**
+ * The app's `check` Query after an outcome Cloud could not see. `checking` while it runs; `done` and `not_done` settle
+ * the call; `pending` means the app does not know yet; `failed` means the check itself gave no usable answer.
+ */
+export type AiActionCheckState = "checking" | "done" | "not_done" | "pending" | "failed";
+export type AiActionCheck = { state: AiActionCheckState; receipt?: CapabilityActionReceipt; at?: string };
+
+/** A settled outcome survives an open response; otherwise prefer the later timestamp, or incoming without both. */
+export const preferredActionCheck = (current: AiActionCheck | undefined, incoming: AiActionCheck): AiActionCheck => {
+  if (!current) return incoming;
+  const currentSettled = current.state === "done" || current.state === "not_done";
+  const incomingSettled = incoming.state === "done" || incoming.state === "not_done";
+  if (currentSettled !== incomingSettled) return currentSettled ? current : incoming;
+  return current.at && incoming.at && Date.parse(current.at) > Date.parse(incoming.at) ? current : incoming;
+};
+
+/** The framework's unknown-outcome codes, in persisted `CODE: message` or structured error results. */
+export const isUnknownActionOutcome = (result: unknown): boolean => {
+  const code =
+    typeof result === "string"
+      ? /^([A-Z][A-Z0-9_]{2,}):/.exec(result.trim())?.[1]
+      : result !== null && typeof result === "object" && "code" in result && typeof result.code === "string"
+        ? result.code
+        : undefined;
+  return code === "ACTION_OUTCOME_UNKNOWN" || code === "IDEMPOTENCY_UNCERTAIN" || code === "IDEMPOTENCY_IN_PROGRESS";
+};
+
+/**
+ * A `checking` claim older than this belonged to a worker or request that stopped and is open again: twice a Query's
+ * 15-second budget, plus a margin. Core takes such a claim over, and the card offers to check again.
+ */
+export const AI_TOOL_CHECK_STALE_MS = 2 * 15_000 + 30_000;

package/src/ai/approval-routes.ts

@@ -56,7 +56,7 @@ type AiApprovalRouteDependencies = {
   limit?: MiddlewareHandler<AuthContext>;
   authenticate?: MiddlewareHandler<AuthContext>;
   listPreferences?: (actorUserId: string, options: { conversationId?: string }) => Promise<AiToolApprovalPreference[]>;
-  revokePreference?: (actorUserId: string, preferenceId: string) => Promise<boolean>;
+  revokePreference?: typeof revokeAiToolApprovalPreference;
   listCapabilities?: () => Promise<CapabilityRegistryEntry[]>;
   /** Resolves a chat the user owns by its ID or short ID. */
   findConversation?: (ownerUserId: string, conversation: string) => Promise<{ id: string } | null>;
@@ -157,7 +157,10 @@ export const createAiApprovalPreferenceRoutes = (dependencies: AiApprovalRouteDe
       v("param", AiApprovalPreferenceParamSchema),
       async (c) => {
         const user = expectUserBackedActor(c);
-        const deleted = await revokePreference(user.id, c.req.valid("param").preferenceId);
+        const deleted = await revokePreference(user.id, c.req.valid("param").preferenceId, {
+          actor: c.get("actor"),
+          requestId: c.req.header("x-request-id") ?? null,
+        });
         return deleted ? c.json({ deleted: true as const }) : c.json({ message: "Approval not found", code: "NOT_FOUND" }, 404);
       },
     );