@k2b/cloud 0.30.0 → 0.31.0

package/src/cli/index.ts

@@ -51,6 +51,12 @@ export type CloudCliContext = {
   profiles?: {
     saveClientCredentials: (input: CloudCliClientCredentialsProfile) => Promise<void>;
   };
+  /**
+   * Open an `http:` or `https:` URL in the user's browser, when the host can.
+   * Resolves `false` when nothing was opened, so the command still prints the
+   * link. Absent in hosts without a local browser.
+   */
+  openUrl?: (url: string) => Promise<boolean>;
 };
 
 /** A profile that signs in with the OAuth client-credentials grant. */
@@ -70,6 +76,16 @@ export type CloudCliClientCredentialsProfile = {
 export type CloudCliModule = {
   name: string;
   summary: string;
+  /**
+   * `cld <alias> …` runs `cld <name> …`. Names match CLOUD_CLI_MODULE_NAME;
+   * cld uses them only when exactly one installed module claims them and no built-in or module has that name.
+   */
+  alias?: string;
+  /**
+   * Top-level names mapped to space-separated command paths relative to this module, never preset flags or args.
+   * Names match CLOUD_CLI_MODULE_NAME; cld uses them only when exactly one installed module claims them and no built-in or module has that name.
+   */
+  shortcuts?: Readonly<Record<string, string>>;
   booleanFlags?: readonly string[];
   requiresCloud?: boolean;
   requiresCloudFor?: (args: string[], flags: CloudCliFlags) => boolean;

package/src/cli/plugin.ts

@@ -67,6 +67,27 @@ export const cloudCliPluginDigest = (files: readonly Pick<CloudCliPluginFile, "p
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
 
+/** Whether an alias is a valid extra name for this module. */
+export const isCloudCliAlias = (value: unknown, name: string): value is string =>
+  typeof value === "string" && CLOUD_CLI_MODULE_NAME.test(value) && value !== name;
+
+/** Validate short names and command-path syntax without loading a module's command tree. */
+export const isCloudCliShortcuts = (value: unknown, name: string, alias?: string): value is Record<string, string> =>
+  isRecord(value) &&
+  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null) &&
+  Object.entries(value).every(
+    ([key, target]) =>
+      CLOUD_CLI_MODULE_NAME.test(key) &&
+      key !== name &&
+      key !== alias &&
+      typeof target === "string" &&
+      target.trim() !== "" &&
+      target
+        .trim()
+        .split(/\s+/)
+        .every((segment) => !segment.startsWith("-")),
+  );
+
 /** Validate a served manifest, including its digest. Throws an `Error` naming the first problem. */
 export const parseCloudCliPluginManifest = (value: unknown): CloudCliPluginManifest => {
   if (!isRecord(value)) throw new Error("plugin manifest is not an object");
@@ -111,6 +132,15 @@ export const validateCloudCliModule = (value: unknown): CloudCliModule => {
   if (typeof value.name !== "string" || !CLOUD_CLI_MODULE_NAME.test(value.name)) {
     throw new Error("default export needs a lowercase kebab-case name");
   }
+  if (value.alias !== undefined && !isCloudCliAlias(value.alias, value.name)) {
+    throw new Error("alias must be a lowercase kebab-case name different from the module name");
+  }
+  if (
+    value.shortcuts !== undefined &&
+    !isCloudCliShortcuts(value.shortcuts, value.name, typeof value.alias === "string" ? value.alias : undefined)
+  ) {
+    throw new Error("shortcuts must be a plain object with unique kebab-case names and non-empty command paths without flags");
+  }
   if (typeof value.summary !== "string") throw new Error("default export needs a string summary");
   if (typeof value.run !== "function") throw new Error("default export needs a run function");
   for (const key of ["help", "requiresCloudFor"] as const) {

package/src/contracts/app.ts

@@ -2,7 +2,7 @@ import type { Sync } from "@k2b/sync";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { AppRegistryHelpSummary } from "./registry";
 import type { Role } from "./shared";
-import type { DashboardWidgetPresentation } from "./widgets";
+import type { DashboardWidgetPresentation, DashboardWidgetSize } from "./widgets";
 
 /**
  * One link entry contributed by an app to the global legal/info footer
@@ -69,6 +69,13 @@ export type AppPresentationTranslation = {
   searchLinks?: Readonly<Record<string, string>>;
   /** Search-link descriptions keyed by their stable same-origin href. */
   searchLinkDescriptions?: Readonly<Record<string, string>>;
+  /** Dashboard widget titles and descriptions keyed by `widgets[].id`. */
+  widgets?: Readonly<Record<string, AppWidgetTranslation>>;
+};
+
+export type AppWidgetTranslation = {
+  title?: string;
+  description?: string;
 };
 
 export type AppPresentationCatalog = {
@@ -161,7 +168,32 @@ export type WidgetEndpoint = {
   id: string;
   /** Absolute path on the app's HTTP service, e.g. "/api/accounts/widget/open-requests". */
   path: string;
-  /** Optional initial layout recommendation. Explicit user choices win. */
+  /**
+   * Name of the widget in the dashboard and its widget gallery, up to 80 characters, in the app's `baseLocale`;
+   * translate it with `presentation.translations[locale].widgets[id].title`. Defaults to the app's name.
+   */
+  title?: string;
+  /** One sentence for the widget gallery, up to 200 characters; translated like `title`. Defaults to the app's description. */
+  description?: string;
+  /** Sizes the widget offers on the board. Defaults to `["large"]`; offer smaller sizes only when the handler fills them. */
+  sizes?: readonly DashboardWidgetSize[];
+  /** Size the widget starts in, one of `sizes`. Defaults to the largest offered size. */
+  defaultSize?: DashboardWidgetSize;
+  /**
+   * Put the widget on the default board of everyone who may see it and list it under "Suggested for you" in the
+   * gallery. Suggest only widgets that are useful without any setup.
+   */
+  suggest?: boolean;
+  /**
+   * Show the widget in the gallery and on the default board only to people with one of these roles, like
+   * `nav.requiresRoles`. Visibility only: the handler still authorizes every request and answers `403`.
+   */
+  requiresRoles?: readonly Role[];
+  /**
+   * @deprecated The dashboard has no zones or widths any more; declare `sizes` and `defaultSize` instead. Keep an
+   * existing value: the dashboard reads it only to convert a board saved before sizes existed into the one the person
+   * saw.
+   */
   presentation?: DashboardWidgetPresentation;
 };
 

package/src/contracts/registry.ts

@@ -2,7 +2,7 @@ import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPre
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { Role } from "./shared";
-import type { DashboardWidgetPresentation } from "./widgets";
+import type { DashboardWidgetPresentation, DashboardWidgetSize } from "./widgets";
 
 /**
  * App-registry entry type. Populated internally by `defineApp()` + the
@@ -52,10 +52,18 @@ export type AppRegistryLegalLink = {
   icon?: string;
 };
 
+/** A widget declaration as the registry carries it; see `WidgetEndpoint`. Older apps send only `id` and `path`. */
 export type AppRegistryWidget = {
   id: string;
   /** Absolute path on the app's HTTP service, e.g. "/api/quotes/widget/random". */
   path: string;
+  title?: string;
+  description?: string;
+  sizes?: readonly DashboardWidgetSize[];
+  defaultSize?: DashboardWidgetSize;
+  suggest?: boolean;
+  requiresRoles?: readonly Role[];
+  /** @deprecated Read only to convert dashboard boards saved before sizes existed. */
   presentation?: DashboardWidgetPresentation;
 };
 

package/src/contracts/widgets.ts

@@ -38,18 +38,63 @@ const WidgetHrefSchema = z
 export const WidgetToneSchema = z.enum(["emerald", "amber", "red", "blue", "zinc"]);
 export type WidgetTone = z.infer<typeof WidgetToneSchema>;
 
+/** @deprecated The dashboard no longer has zones; declare `sizes` and `defaultSize` instead. */
 export type DashboardWidgetZone = "focus" | "overview" | "context";
+/** @deprecated The dashboard no longer has spans; declare `sizes` and `defaultSize` instead. */
 export type DashboardWidgetSpan = "standard" | "wide";
 
 /**
- * Stable, app-owned recommendation for a widget's initial dashboard layout.
- * Explicit user layout settings always take precedence.
+ * @deprecated The dashboard has no zones or widths any more. Declare `sizes` and `defaultSize` on the widget instead;
+ * the dashboard reads this recommendation only to convert a board saved before sizes existed.
  */
 export type DashboardWidgetPresentation = {
   defaultZone?: DashboardWidgetZone;
   defaultSpan?: DashboardWidgetSpan;
 };
 
+/**
+ * The three sizes a widget can take on the dashboard board, which has four columns on wider screens and two on
+ * phones: `small` is one column and one row, `medium` two columns and one row, and `large` two columns and two rows.
+ * On a phone, `small` takes half the width and `medium` and `large` the full width.
+ */
+export const DASHBOARD_WIDGET_SIZES = ["small", "medium", "large"] as const;
+export type DashboardWidgetSize = (typeof DASHBOARD_WIDGET_SIZES)[number];
+
+/** Longest declared widget title, in characters, the same bound as a shortcut title. */
+export const WIDGET_TITLE_MAX_LENGTH = 80;
+/** Longest declared widget description, in characters: one sentence in the widget gallery. */
+export const WIDGET_DESCRIPTION_MAX_LENGTH = 200;
+
+export const isDashboardWidgetSize = (value: unknown): value is DashboardWidgetSize =>
+  DASHBOARD_WIDGET_SIZES.some((size) => size === value);
+
+/**
+ * The sizes a widget offers and the size it starts with. A widget that declares no valid size offers only `large`,
+ * the height every widget had before sizes existed; without a valid `defaultSize`, it starts at its largest size.
+ */
+export const resolveWidgetSizes = (declaration: {
+  sizes?: readonly unknown[];
+  defaultSize?: unknown;
+}): { sizes: DashboardWidgetSize[]; defaultSize: DashboardWidgetSize } => {
+  const declared = DASHBOARD_WIDGET_SIZES.filter((size) => declaration.sizes?.includes(size));
+  const sizes: DashboardWidgetSize[] = declared.length > 0 ? declared : ["large"];
+  const defaultSize =
+    isDashboardWidgetSize(declaration.defaultSize) && sizes.includes(declaration.defaultSize) ? declaration.defaultSize : sizes.at(-1)!;
+  return { sizes, defaultSize };
+};
+
+/** `requested` when the widget offers it, otherwise the widget's default size. */
+export const fitWidgetSize = (
+  requested: unknown,
+  widget: { sizes: readonly DashboardWidgetSize[]; defaultSize: DashboardWidgetSize },
+): DashboardWidgetSize => (isDashboardWidgetSize(requested) && widget.sizes.includes(requested) ? requested : widget.defaultSize);
+
+/** What the dashboard asks a widget handler for, read with `getWidgetRequest(c)`. */
+export type WidgetRequest = {
+  /** The size the widget is shown in, always one the widget declares. */
+  size: DashboardWidgetSize;
+};
+
 export const WidgetAccentSchema = z
   .object({
     tone: WidgetToneSchema,

package/src/desktop/solid.tsx

@@ -1,3 +1,4 @@
+import { suppressTextSelection } from "@k2b/ui";
 import { deserialize as deserializeProps, serialize as serializeProps } from "seroval";
 import type { Component, JSX, ParentProps } from "solid-js";
 import { children, createContext, createMemo, createSignal, For, onCleanup, onMount, Show, useContext } from "solid-js";
@@ -483,10 +484,11 @@ const startDesktopResize = (event: PointerEvent, onMove: (dx: number, dy: number
   const startX = event.clientX;
   const startY = event.clientY;
   const move = (next: PointerEvent) => onMove(next.clientX - startX, next.clientY - startY);
+  const releaseTextSelection = suppressTextSelection(event.pointerId);
   const stop = () => {
     window.removeEventListener("pointermove", move);
     window.removeEventListener("pointerup", stop);
-    document.body.style.userSelect = "";
+    releaseTextSelection();
     document.body.style.cursor = "";
   };
   window.addEventListener("pointermove", move);
@@ -631,10 +633,9 @@ export const DesktopWorkspace = ((props: DesktopWorkspaceProps) => {
 
   const resizeSidebar = (event: PointerEvent) => {
     const pane = sidebar();
-    if (!pane?.resizable) return;
+    if (!pane?.resizable || event.button !== 0) return;
     const start = sidebarOpen() ? sidebarSize() : sidebarColumnSize();
     document.body.style.cursor = "col-resize";
-    document.body.style.userSelect = "none";
     startDesktopResize(event, (dx) => {
       const raw = start + dx;
       if (shouldRail(pane, raw)) {
@@ -650,10 +651,9 @@ export const DesktopWorkspace = ((props: DesktopWorkspaceProps) => {
 
   const resizeRight = (event: PointerEvent) => {
     const pane = right();
-    if (!pane?.resizable) return;
+    if (!pane?.resizable || event.button !== 0) return;
     const start = rightOpen() ? rightSize() : rightColumnSize();
     document.body.style.cursor = "col-resize";
-    document.body.style.userSelect = "none";
     startDesktopResize(event, (dx) => {
       const raw = start - dx;
       if (shouldRail(pane, raw)) {
@@ -669,10 +669,9 @@ export const DesktopWorkspace = ((props: DesktopWorkspaceProps) => {
 
   const resizeBottom = (event: PointerEvent) => {
     const pane = bottom();
-    if (!pane?.resizable) return;
+    if (!pane?.resizable || event.button !== 0) return;
     const start = bottomOpen() ? bottomSize() : bottomRowSize();
     document.body.style.cursor = "row-resize";
-    document.body.style.userSelect = "none";
     startDesktopResize(event, (_dx, dy) => {
       const raw = start - dy;
       if (shouldRail(pane, raw)) {

package/src/server/index.ts

@@ -94,3 +94,4 @@ export {
   updateAccess,
 } from "./services";
 export { getDateConfig, getTimeZone, TIMEZONE_COOKIE, time } from "./time";
+export { getWidgetRequest } from "./widget-request";

package/src/server/widget-request.ts

@@ -0,0 +1,27 @@
+import type { Context } from "hono";
+import { type DashboardWidgetSize, fitWidgetSize, resolveWidgetSizes, type WidgetRequest } from "../contracts/widgets";
+
+/** The query parameter Core uses to ask a widget handler for one size. */
+export const WIDGET_SIZE_PARAM = "size";
+
+const requests = new WeakMap<Request, WidgetRequest>();
+
+/**
+ * Records what the dashboard asked a declared widget for, already fitted to the declaration. Only the framework's
+ * internal widget route calls this, before it runs the handler.
+ */
+export const setWidgetRequest = (
+  c: Context,
+  declaration: { sizes?: readonly DashboardWidgetSize[]; defaultSize?: DashboardWidgetSize },
+): WidgetRequest => {
+  const request = { size: fitWidgetSize(c.req.query(WIDGET_SIZE_PARAM), resolveWidgetSizes(declaration)) };
+  requests.set(c.req.raw, request);
+  return request;
+};
+
+/**
+ * What the dashboard asks this widget handler for. `size` is always one of the sizes the widget declares; return the
+ * content that fits it, for example only the one number in `small`. Outside a dashboard invocation, such as a request
+ * to the handler's own public route, the request is `large`, the height every widget had before sizes existed.
+ */
+export const getWidgetRequest = (c: Context): WidgetRequest => requests.get(c.req.raw) ?? { size: "large" };

package/src/services/approvals/index.ts

@@ -0,0 +1,225 @@
+import { type SQL, sql } from "bun";
+import { capabilityRequestHash } from "../../capabilities/claims";
+import type { CapabilityActionReview } from "../../contracts/capabilities";
+import { isAppSessionActor } from "../../server/actor";
+import type { RequestActor, RequestCredentialKind } from "../../server/middleware/auth";
+import { audit } from "../audit";
+import { toPgTextArray } from "../postgres";
+
+export { migrateApprovals } from "./migrate";
+
+// Derived from chat's AI_ACTION_BUDGET_MS and Studio's one-day abandonment of pending calls.
+export const APPROVAL_MAX_WAIT_MS = 24 * 60 * 60_000;
+export type ApprovalDecisionChannel = "web_session" | "app_session" | "oauth" | "api_key" | "invocation";
+export type ApprovalRequesterKind = "assistant_turn" | "studio_app";
+export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled" | "consumed";
+export type ApprovalAssurance = "standard" | "confirm";
+
+/**
+ * `standard` when the person may remember the approval of this call: an Action with `approval: "rememberable"` whose
+ * review names a scope for these arguments, a tool whose policy allows remembering, or a website. Otherwise `confirm`.
+ */
+export const approvalAssurance = (rememberable: boolean): ApprovalAssurance => (rememberable ? "standard" : "confirm");
+export const approvalArgsDigest = (input: unknown): string => capabilityRequestHash(input);
+export const approvalReviewDigest = (review: CapabilityActionReview | null | undefined): string => capabilityRequestHash(review ?? null);
+export const approvalDecisionChannel = (input: {
+  credentialKind?: RequestCredentialKind;
+  actor?: RequestActor;
+}): ApprovalDecisionChannel =>
+  input.credentialKind === "session"
+    ? isAppSessionActor(input.actor)
+      ? "app_session"
+      : "web_session"
+    : (input.credentialKind ?? "invocation");
+export const approvalScopeFromToolName = (name: string): { appId: string; action: string } => {
+  const dot = name.indexOf(".");
+  return dot < 0 ? { appId: "assistant", action: name } : { appId: name.slice(0, dot), action: name.slice(dot + 1) };
+};
+
+export type ApprovalRequestInput = {
+  appId: string;
+  action: string;
+  approvalScope?: string | null;
+  requester: { kind: ApprovalRequesterKind; ref: string; appId: string; title?: string | null };
+  subjectId: string;
+  approverUserId: string;
+  assurance: ApprovalAssurance;
+  sentence: string;
+  review?: CapabilityActionReview | null;
+  input: unknown;
+  expiresInMs: number;
+};
+export type ApprovalRequest = {
+  id: string;
+  appId: string;
+  action: string;
+  approvalScope: string | null;
+  requesterKind: ApprovalRequesterKind;
+  requesterRef: string;
+  requesterAppId: string;
+  requesterTitle: string | null;
+  subjectId: string;
+  approverUserId: string;
+  assurance: ApprovalAssurance;
+  sentence: string;
+  details: CapabilityActionReview | null;
+  argsDigest: string;
+  reviewDigest: string;
+  status: ApprovalStatus;
+  decidedVia: ApprovalDecisionChannel | null;
+  decidedAt: Date | null;
+  consumedAt: Date | null;
+  createdAt: Date;
+  expiresAt: Date;
+};
+// SQL aliases keep the public row shape identical for reads and locked transaction reads. A function, because a
+// fragment built at import time would bind the default sql handle before a test can choose its database.
+const columns = () => sql`id, app_id AS "appId", action, approval_scope AS "approvalScope",
+  requester_kind AS "requesterKind", requester_ref AS "requesterRef", requester_app_id AS "requesterAppId",
+  requester_title AS "requesterTitle", subject_id AS "subjectId", approver_user_id AS "approverUserId",
+  assurance, sentence, details, args_digest AS "argsDigest", review_digest AS "reviewDigest", status,
+  decided_via AS "decidedVia", decided_at AS "decidedAt", consumed_at AS "consumedAt",
+  created_at AS "createdAt", expires_at AS "expiresAt"`;
+
+const transaction = <T>(db: SQL | undefined, run: (tx: SQL) => Promise<T>): Promise<T> => (db && db !== sql ? run(db) : sql.begin(run));
+
+export type ApprovalRequestResult = { ok: true; id: string } | { ok: false; code: "CONFLICT" };
+/**
+ * Records the question once per requester reference. Asking again, for example after a worker restart, returns the
+ * open request unchanged: its snapshot is what the person may already see, so a changed effect fails `consume` and
+ * asks again instead of rebinding that decision. A reference whose request is decided, expired, or another person's
+ * is a conflict.
+ */
+export const request = async (input: ApprovalRequestInput, db?: SQL): Promise<ApprovalRequestResult> => {
+  // Zero or less records a request that is already expired, such as a call that waited too long before the upgrade.
+  const expiresInMs = Number.isNaN(input.expiresInMs)
+    ? APPROVAL_MAX_WAIT_MS
+    : Math.max(0, Math.min(input.expiresInMs, APPROVAL_MAX_WAIT_MS));
+  return transaction(db, async (tx): Promise<ApprovalRequestResult> => {
+    const [row] = await tx<{ id: string }[]>`
+      INSERT INTO approvals.requests (app_id, action, approval_scope, requester_kind, requester_ref, requester_app_id,
+        requester_title, subject_id, approver_user_id, assurance, sentence, details, args_digest, review_digest, expires_at)
+      VALUES (${input.appId}, ${input.action}, ${input.approvalScope ?? null}, ${input.requester.kind}, ${input.requester.ref},
+        ${input.requester.appId}, ${input.requester.title ?? null}, ${input.subjectId}::uuid, ${input.approverUserId}::uuid,
+        ${input.assurance}, ${input.sentence}, ${JSON.stringify(input.review ?? null)}::text::jsonb,
+        ${approvalArgsDigest(input.input)}, ${approvalReviewDigest(input.review)}, now() + (${expiresInMs} * interval '1 millisecond'))
+      ON CONFLICT (requester_kind, requester_ref) DO NOTHING
+      RETURNING id
+    `;
+    if (row) return { ok: true, id: row.id };
+    const [open] = await tx<{ id: string }[]>`SELECT id FROM approvals.requests
+      WHERE requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref}
+        AND status='pending' AND expires_at > now() AND subject_id=${input.subjectId}::uuid
+        AND approver_user_id=${input.approverUserId}::uuid AND app_id=${input.appId} AND action=${input.action}`;
+    return open ? { ok: true, id: open.id } : { ok: false, code: "CONFLICT" };
+  });
+};
+
+export const get = async (id: string, db?: SQL): Promise<ApprovalRequest | null> =>
+  transaction(db, async (tx) => {
+    const [row] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests WHERE id=${id}::uuid`;
+    return row ?? null;
+  });
+
+export type ApprovalDecisionResult =
+  | { ok: true; status: ApprovalStatus; replay: boolean }
+  | { ok: false; code: "EXPIRED" | "NOT_FOUND" }
+  | { ok: false; code: "ALREADY_DECIDED"; status: ApprovalStatus };
+export const decide = async (
+  id: string,
+  decision: { approved: boolean },
+  actor: { userId: string; via: ApprovalDecisionChannel },
+  db?: SQL,
+): Promise<ApprovalDecisionResult> => {
+  const result = await transaction(db, async (tx): Promise<ApprovalDecisionResult> => {
+    const [row] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests
+      WHERE id=${id}::uuid AND approver_user_id=${actor.userId}::uuid FOR UPDATE`;
+    if (!row) return { ok: false, code: "NOT_FOUND" };
+    const status = decision.approved ? "approved" : "rejected";
+    const [won] = await tx<ApprovalRequest[]>`
+      UPDATE approvals.requests SET status=${status}, decided_via=${actor.via}, decided_at=now()
+      WHERE id=${id}::uuid AND approver_user_id=${actor.userId}::uuid AND status='pending' AND expires_at > now()
+      RETURNING ${columns()}
+    `;
+    if (won) {
+      await audit.record(
+        {
+          action: decision.approved ? "auth.action.approve" : "auth.action.deny",
+          outcome: "allowed",
+          actor: { userId: actor.userId },
+          target: { type: "approval_request", id, label: `${won.appId}.${won.action}` },
+          metadata: {
+            appId: won.appId,
+            action: won.action,
+            assurance: won.assurance,
+            decidedVia: actor.via,
+            requesterKind: won.requesterKind,
+            requesterAppId: won.requesterAppId,
+          },
+        },
+        tx,
+      );
+      return { ok: true, status, replay: false };
+    }
+    if (row.status === "pending") {
+      await tx`UPDATE approvals.requests SET status='expired' WHERE id=${id}::uuid AND status='pending' AND expires_at <= now()`;
+      return { ok: false, code: "EXPIRED" };
+    }
+    if (
+      (decision.approved && (row.status === "approved" || row.status === "consumed")) ||
+      (!decision.approved && row.status === "rejected")
+    )
+      return { ok: true, status: row.status, replay: true };
+    return { ok: false, code: "ALREADY_DECIDED", status: row.status };
+  });
+  // Publish a later NATS decision hint only after the owning transaction commits.
+  return result;
+};
+
+export type ApprovalConsumeResult =
+  | { ok: true }
+  | { ok: false; code: "NOT_FOUND" | "NOT_APPROVED" | "ALREADY_CONSUMED" | "INPUT_CHANGED" | "REVIEW_CHANGED" };
+export const consume = async (
+  id: string,
+  input: { input: unknown; review: CapabilityActionReview | null; requester: { kind: ApprovalRequesterKind; ref: string } },
+  db?: SQL,
+): Promise<ApprovalConsumeResult> => {
+  const argsDigest = approvalArgsDigest(input.input),
+    reviewDigest = approvalReviewDigest(input.review);
+  return transaction(db, async (tx): Promise<ApprovalConsumeResult> => {
+    const [row] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests
+      WHERE id=${id}::uuid AND requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref} FOR UPDATE`;
+    if (!row) return { ok: false, code: "NOT_FOUND" };
+    if (row.status === "consumed") return { ok: false, code: "ALREADY_CONSUMED" };
+    if (row.status !== "approved") return { ok: false, code: "NOT_APPROVED" };
+    if (row.argsDigest !== argsDigest || row.reviewDigest !== reviewDigest) {
+      await tx`UPDATE approvals.requests SET status='cancelled' WHERE id=${id}::uuid AND status='approved'`;
+      return { ok: false, code: row.argsDigest !== argsDigest ? "INPUT_CHANGED" : "REVIEW_CHANGED" };
+    }
+    await tx`UPDATE approvals.requests SET status='consumed', consumed_at=now() WHERE id=${id}::uuid AND status='approved'
+      AND requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref}
+      AND args_digest=${argsDigest} AND review_digest=${reviewDigest}`;
+    return { ok: true };
+  });
+};
+
+export const cancel = async (ids: string[], db?: SQL): Promise<void> => {
+  if (!ids.length) return;
+  await transaction(db, async (tx) => {
+    await tx`UPDATE approvals.requests SET status='cancelled' WHERE id=ANY(${toPgTextArray(ids)}::uuid[]) AND status IN ('pending','approved')`;
+  });
+};
+
+export const pruneApprovalRequests = async (before: Date): Promise<number> => {
+  let total = 0;
+  let deleted: number;
+  do {
+    const result = await sql`WITH expired AS (SELECT id FROM approvals.requests WHERE expires_at < ${before} LIMIT 5000)
+      DELETE FROM approvals.requests request USING expired WHERE request.id=expired.id`;
+    deleted = result.count;
+    total += deleted;
+  } while (deleted === 5000);
+  return total;
+};
+
+export const approvals = { request, get, decide, consume, cancel };

package/src/services/approvals/migrate.ts

@@ -0,0 +1,33 @@
+import { sql } from "bun";
+
+export const migrateApprovals = async (): Promise<void> => {
+  await sql`CREATE SCHEMA IF NOT EXISTS approvals`.simple();
+  await sql`
+    CREATE TABLE IF NOT EXISTS approvals.requests (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      app_id TEXT NOT NULL,
+      action TEXT NOT NULL,
+      approval_scope TEXT,
+      requester_kind TEXT NOT NULL CHECK (requester_kind IN ('assistant_turn','studio_app')),
+      requester_ref TEXT NOT NULL,
+      requester_app_id TEXT NOT NULL,
+      requester_title TEXT,
+      subject_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+      approver_user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+      assurance TEXT NOT NULL CHECK (assurance IN ('standard','confirm')),
+      sentence TEXT NOT NULL,
+      details JSONB,
+      args_digest TEXT NOT NULL,
+      review_digest TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','approved','rejected','expired','cancelled','consumed')),
+      decided_via TEXT CHECK (decided_via IS NULL OR decided_via IN ('web_session','app_session','oauth','api_key','invocation')),
+      decided_at TIMESTAMPTZ,
+      consumed_at TIMESTAMPTZ,
+      created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      expires_at TIMESTAMPTZ NOT NULL,
+      UNIQUE (requester_kind, requester_ref)
+    )
+  `.simple();
+  await sql`CREATE INDEX IF NOT EXISTS approvals_requests_pending ON approvals.requests(approver_user_id, created_at) WHERE status='pending'`.simple();
+  await sql`CREATE INDEX IF NOT EXISTS approvals_requests_expiry ON approvals.requests(expires_at)`.simple();
+};

package/src/shared/app-presentation.ts

@@ -23,6 +23,12 @@ const mergedTranslation = (catalog: AppPresentationCatalog, requestedLocale: str
       legalLinks: { ...current.legalLinks, ...next.legalLinks },
       searchLinks: { ...current.searchLinks, ...next.searchLinks },
       searchLinkDescriptions: { ...current.searchLinkDescriptions, ...next.searchLinkDescriptions },
+      widgets: Object.fromEntries(
+        [...new Set([...Object.keys(current.widgets ?? {}), ...Object.keys(next.widgets ?? {})])].map((id) => [
+          id,
+          { ...current.widgets?.[id], ...next.widgets?.[id] },
+        ]),
+      ),
     };
   }, {});
 };
@@ -55,6 +61,11 @@ export const resolveAppPresentation = <T extends AppMeta>(app: T, requestedLocal
       description: translation.searchLinkDescriptions?.[link.href] ?? link.description,
     })),
     legalLinks: app.legalLinks?.map((link) => ({ ...link, label: translation.legalLinks?.[link.href] ?? link.label })),
+    widgets: app.widgets?.map((widget) => ({
+      ...widget,
+      title: translation.widgets?.[widget.id]?.title ?? widget.title,
+      description: translation.widgets?.[widget.id]?.description ?? widget.description,
+    })),
   };
 };
 

package/src/shared/email-html.ts

@@ -44,11 +44,46 @@ export const EMAIL_HTML_ALLOWED_ATTRIBUTES: Record<string, string[]> = {
   ul: ["style"],
 };
 
-export const EMAIL_HTML_ALLOWED_SCHEMES = ["http", "https", "mailto"] as const;
-
-export const sanitizeEmailHtml = (html: string): string =>
-  sanitizeHtml(html, {
-    allowedTags: [...EMAIL_HTML_TAGS],
-    allowedAttributes: EMAIL_HTML_ALLOWED_ATTRIBUTES,
-    allowedSchemes: [...EMAIL_HTML_ALLOWED_SCHEMES],
-  });
+export const EMAIL_HTML_ALLOWED_SCHEMES = ["http", "https", "mailto", "tel"] as const;
+
+// An optional leading `+`, at least one digit, the visual separators of RFC 3966 and spaces, and an optional extension.
+const PHONE_NUMBER_HREF = /^tel:\+?(?=[^;]*\d)[\d\-.() ]+(?:;ext=\d+)?$/i;
+
+/** Whether a `tel:` link holds a phone number, such as `tel:+49 731 000000` or `tel:+49-731-000000;ext=12`. */
+const isPhoneNumberHref = (href: string): boolean => {
+  try {
+    return PHONE_NUMBER_HREF.test(decodeURI(href.trim()));
+  } catch {
+    return false;
+  }
+};
+
+// Like sanitize-html, ignore control characters and whitespace when reading the scheme.
+const hrefScheme = (href: string): string | undefined =>
+  href
+    .replace(/[\u0000-\u0020]+/g, "")
+    .match(/^([a-z][a-z\d+.-]*):/i)?.[1]
+    ?.toLowerCase();
+
+/**
+ * Drops a `tel:` link that holds no phone number; its text stays. sanitize-html removes HTML comments before
+ * it reads a scheme, so a link address with a comment, such as `te<!---->l:`, is dropped too.
+ */
+const keepPhoneNumberHref: sanitizeHtml.Transformer = (tagName, attribs) => {
+  const href = attribs.href;
+  if (href === undefined || (!href.includes("<!--") && (hrefScheme(href) !== "tel" || isPhoneNumberHref(href)))) {
+    return { tagName, attribs };
+  }
+  const { href: _dropped, ...kept } = attribs;
+  return { tagName, attribs: kept };
+};
+
+/** The sanitize-html options of the email sanitizer. Extend them instead of repeating the allowlists. */
+export const EMAIL_HTML_SANITIZE_OPTIONS = {
+  allowedTags: [...EMAIL_HTML_TAGS],
+  allowedAttributes: EMAIL_HTML_ALLOWED_ATTRIBUTES,
+  allowedSchemes: [...EMAIL_HTML_ALLOWED_SCHEMES],
+  transformTags: { a: keepPhoneNumberHref },
+} satisfies sanitizeHtml.IOptions;
+
+export const sanitizeEmailHtml = (html: string): string => sanitizeHtml(html, EMAIL_HTML_SANITIZE_OPTIONS);