@k2b/cloud 0.30.0 → 0.31.0

package/src/ai/tools.ts

@@ -4,6 +4,7 @@ import type { z } from "zod";
 import type { RequestActor } from "../server";
 import { aiToolNeedsApproval } from "./approvals";
 import type {
+  AiApprovalTarget,
   AiDataBoundary,
   AiFrontendToolMode,
   AiProjectFileToolSource,
@@ -13,6 +14,7 @@ import type {
   AiToolApprovalPolicy,
   AiToolDefinition,
   AiToolRuntime,
+  AiWebsiteReceipt,
 } from "./types";
 
 export const defineAiTool = <TInput extends z.ZodType, TOutput extends z.ZodType>(config: {
@@ -60,6 +62,12 @@ export const defineAiTool = <TInput extends z.ZodType, TOutput extends z.ZodType
           timeZone?: string;
           /** Localized short status; never include payloads or secrets. */
           reportProgress?: (message: string) => Promise<void>;
+          /** Asks like `requestApproval`, and lets the person remember the approval of `target`. */
+          requestApprovalFor?: (message: string, target: AiApprovalTarget) => Promise<boolean>;
+          /** Relays a decision for an effect another platform component consumes and executes. */
+          requestRelayedApproval?: (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => Promise<boolean>;
+          /** Shows requests a website approval let through as they go out, so the chat keeps them whatever the outcome. */
+          reportWebsiteReceipts?: (receipts: AiWebsiteReceipt[]) => Promise<void>;
         },
       ) => Promise<z.infer<TOutput>>,
     ): AiToolRuntime<TInput, TOutput> {
@@ -106,15 +114,93 @@ export type AiToolPreparationContext = {
   locale?: string;
   timeZone?: string;
   reportToolProgress?: (callId: string, message: string) => Promise<void>;
+  /** Uses the approved snapshot immediately before the tool executes its effect. */
+  consumeApproval?: (approvalCallId: string, input: unknown) => Promise<AiApprovalUse>;
+  /** Links a relayed decision to the record the effect owner will consume. */
+  linkApproval?: (approvalCallId: string, approvalId: string) => void;
+  /** Hears what a nested approval asks for before the approval is requested. */
+  describeApproval?: (approvalCallId: string, target: AiApprovalTarget) => void;
+  reportWebsiteReceipts?: (callId: string, receipts: AiWebsiteReceipt[]) => Promise<void>;
 };
 
+/**
+ * What using an approval found: `approved` lets the effect run, `changed` means the approved snapshot no longer
+ * matches and asks again, and `used` means an earlier run of the call already used it, so the call must not run again.
+ */
+export type AiApprovalUse = "approved" | "changed" | "used";
+
+const approvalCallIdPattern = /^(.*)-approval-(\d+)$/;
+
+/**
+ * Whether `askedCallIds` holds a question of the same tool call that Nessi asked after `approvalCallId`, the call's
+ * own approval or one of its numbered questions. A turn that continues after such a question runs the tool from its
+ * start again, so the approvals before it are used again by the same call.
+ */
+export const aiApprovalAskedLater = (approvalCallId: string, askedCallIds: Iterable<string>): boolean => {
+  const own = approvalCallIdPattern.exec(approvalCallId);
+  const callId = own ? own[1] : approvalCallId,
+    index = own ? Number(own[2]) : -1;
+  for (const asked of askedCallIds) {
+    const later = approvalCallIdPattern.exec(asked);
+    if (later && later[1] === callId && Number(later[2]) > index) return true;
+  }
+  return false;
+};
+
+const approvalUsedError = () =>
+  new Error("This approval was already used, so Cloud does not run the call again. Check its outcome before you call again.");
+
 export const prepareAiTools = (input: AiToolPreparationContext & { tools?: AiRuntimeTool[] }): PreparedAiTools => {
   const canonicalNames = new Map<string, string>();
   const approvalPolicies = new Map<string, AiToolApprovalPolicy>();
   const frontendModes = new Map<string, AiFrontendToolMode>();
 
+  const approvalContext = async (toolInput: unknown, ctx: ToolContext, needsApproval: boolean) => {
+    const callId = ctx.callId;
+    const use = (approvalCallId: string): Promise<AiApprovalUse> =>
+      input.consumeApproval ? input.consumeApproval(approvalCallId, toolInput) : Promise.resolve("approved");
+    if (needsApproval && input.consumeApproval) {
+      const used = callId ? await use(callId) : "changed";
+      if (used === "used") throw approvalUsedError();
+      if (used === "changed") throw new Error("This approval no longer matches the call. Ask again.");
+    }
+    // Nessi numbers the approvals of one execution in request order; count them to name each one's call ID.
+    let approvals = 0;
+    const requestApproval = async (message: string, target?: AiApprovalTarget): Promise<boolean> => {
+      while (true) {
+        const approvalCallId = `${callId}-approval-${approvals++}`;
+        if (target) input.describeApproval?.(approvalCallId, target);
+        if (!(await ctx.requestApproval(message))) return false;
+        const used = await use(approvalCallId);
+        if (used === "approved") return true;
+        if (used === "used") throw approvalUsedError();
+        // A changed snapshot requires a new human decision under the next Nessi action ID.
+      }
+    };
+    return {
+      ...ctx,
+      requestApproval,
+      requestApprovalFor: (message: string, target: AiApprovalTarget) => requestApproval(message, target),
+      requestRelayedApproval: async (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => {
+        const approvalCallId = `${callId}-approval-${approvals++}`;
+        if (options.approvalId) input.linkApproval?.(approvalCallId, options.approvalId);
+        if (options.target) input.describeApproval?.(approvalCallId, options.target);
+        if (!(await ctx.requestApproval(message))) return false;
+        // The effect's own record is used where it runs. Without one, as for a website request from code, the relay
+        // that hands over the decision uses the chat's record; a decision it cannot use is not handed over as approval.
+        return options.approvalId !== undefined || (await use(approvalCallId)) === "approved";
+      },
+    };
+  };
+
   const tools = (input.tools ?? []).map((tool): Tool => {
-    if (!isCloudAiTool(tool)) return tool;
+    if (!isCloudAiTool(tool)) {
+      if (tool.kind !== "server") return tool;
+      return {
+        ...tool,
+        execute: async (toolInput, ctx) => tool.execute(toolInput, await approvalContext(toolInput, ctx, tool.def.needsApproval === true)),
+      };
+    }
 
     canonicalNames.set(tool.def.name, tool.def.canonicalName ?? tool.def.name);
     approvalPolicies.set(tool.def.name, tool.def.approval);
@@ -130,12 +216,12 @@ export const prepareAiTools = (input: AiToolPreparationContext & { tools?: AiRun
     });
 
     if (tool.location === "server") {
-      return nessiTool.server((toolInput, ctx) => {
+      return nessiTool.server(async (toolInput, ctx) => {
         if (!input.actor) throw new Error(`AI server tool "${tool.def.name}" requires a request actor.`);
         const report = input.reportToolProgress;
         const callId = ctx.callId;
         return tool.run(toolInput, {
-          ...ctx,
+          ...(await approvalContext(toolInput, ctx, aiToolNeedsApproval(tool.def.approval))),
           actor: input.actor,
           conversationId: input.conversationId,
           turnId: input.turnId,
@@ -147,6 +233,8 @@ export const prepareAiTools = (input: AiToolPreparationContext & { tools?: AiRun
           locale: input.locale,
           timeZone: input.timeZone,
           reportProgress: callId && report ? (message) => report(callId, message) : undefined,
+          reportWebsiteReceipts:
+            callId && input.reportWebsiteReceipts ? (receipts) => input.reportWebsiteReceipts!(callId, receipts) : undefined,
         });
       });
     }

package/src/ai/types.ts

@@ -303,6 +303,8 @@ export type AiStoredMessage = {
     toolPresentations?: Record<string, AiToolPresentation>;
     /** How the person decided an approval; `expired` when the turn ended while it still waited. */
     toolOutcomes?: Record<string, "rejected" | "approved" | "expired">;
+    /** Requests a website approval let through, by tool call and then by `AiWebsiteReceipt.index`. */
+    websiteReceipts?: Record<string, Record<string, { method: string; url: string }>>;
     /** Why the turn failed, on the last message of its loop. The chat words it in the reader's language. */
     turnError?: AiTurnError;
   } | null;
@@ -420,6 +422,10 @@ export type AiPendingTurnAction =
       message?: string;
       review?: CapabilityActionReview;
       allowAlways: boolean;
+      /** Whether the approval can be remembered for this chat. */
+      allowChat: boolean;
+      /** The website origin a chat approval would allow, for an HTTP request a code run makes. */
+      website?: string;
     }
   | {
       type: "frontend_tool";
@@ -441,6 +447,7 @@ export type AiTurnAbortRequest =
     };
 
 export type AiPendingTurnActionRecord = {
+  approvalId?: string;
   turnId: string;
   conversationId: string;
   callId: string;
@@ -452,6 +459,10 @@ export type AiPendingTurnActionRecord = {
   review?: CapabilityActionReview;
   approvalScope: string;
   allowAlways: boolean;
+  /** Whether the approval can be remembered for this chat; defaults to `allowAlways`. */
+  allowChat?: boolean;
+  /** Remembered-approval name when it differs from `name`: the website or Action a code run asks for. */
+  rememberToolName?: string;
   frontendMode?: AiFrontendToolMode;
   resolvedEvent: InboundEvent | null;
 };
@@ -607,6 +618,11 @@ export type AiChatTurnRunConfig = {
   selectedSkillIds?: string[];
   /** Server-owned marker: model grants apply only to interactive Assistant chat. */
   assistantChat?: true;
+  /**
+   * Server-owned marker: a person started this turn in a signed-in browser session, not through `cld`, an API key,
+   * a delegated account, or a schedule. Only such a turn uses website approvals.
+   */
+  signedInSession?: true;
   kind?: "chat";
   input: Input;
   /** Stable public ID exposed as runtime context, not instructions. */
@@ -1016,6 +1032,23 @@ export type AiAccessResult<TAccess = unknown> = {
 
 export type AiToolApprovalPolicy = "never" | "once" | "always" | { kind: "user-configurable"; default: "once" | "always"; scope?: string };
 
+/**
+ * What a server tool asks a person to approve when the approval can be remembered: a website or an Action, not the
+ * tool itself. A target can always be remembered for its chat.
+ */
+export type AiApprovalTarget = {
+  toolName: string;
+  approvalScope: string;
+  /** Whether the person may also remember it everywhere. */
+  always: boolean;
+};
+
+/**
+ * A request a remembered website approval let through without asking. The chat shows it with its full URL and a revoke
+ * action; `index` orders the receipts of one tool call, and a receipt reported again with the same index replaces it.
+ */
+export type AiWebsiteReceipt = { index: number; method: string; url: string };
+
 export type AiFrontendToolMode = "client" | "client_view" | "client_interaction";
 
 export type AiCapabilityToolPresentation = {
@@ -1071,6 +1104,12 @@ export type AiToolRuntime<TInput extends z.ZodType = z.ZodType, TOutput extends
           timeZone?: string;
           /** Localized short status; never include payloads or secrets. */
           reportProgress?: (message: string) => Promise<void>;
+          /** Asks like `requestApproval`, and lets the person remember the approval of `target`. */
+          requestApprovalFor?: (message: string, target: AiApprovalTarget) => Promise<boolean>;
+          /** Relays a decision for an effect another platform component consumes and executes. */
+          requestRelayedApproval?: (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => Promise<boolean>;
+          /** Shows requests a website approval let through as they go out, so the chat keeps them whatever the outcome. */
+          reportWebsiteReceipts?: (receipts: AiWebsiteReceipt[]) => Promise<void>;
         },
       ): Promise<z.infer<TOutput>>;
     }

package/src/ai/web-provenance.ts

@@ -0,0 +1,103 @@
+import { domainToUnicode } from "node:url";
+import { sql } from "bun";
+import { toPgTextArray } from "../services/postgres";
+
+/** The longest address web_extract and fetch_file accept; a longer one can never be read, so it is never recorded. */
+const WEB_ADDRESS_MAX_CHARS = 2_000;
+
+const URL_TOKEN = /https?:\/\/[^\s<>"'`\\^{}|[\]]+/gi;
+/**
+ * An address typed without its scheme, such as `example.org/news`. It must start the word: a host inside another
+ * address, an email address, or a longer host name is not a typed address of its own.
+ */
+const BARE_TOKEN =
+  /(?<![\w@.\-/:%+~#=?&])(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z][a-z0-9-]*[a-z0-9](?::\d{1,5})?(?:\/[^\s<>"'`\\^{}|[\]]*)?/gi;
+
+/** Drops punctuation that ends the sentence around an address, and a closing bracket the address did not open. */
+const trimToken = (token: string): string => {
+  let end = token.length;
+  while (end > 0) {
+    const last = token[end - 1]!;
+    if (".,;:!?*'\"".includes(last)) end--;
+    else if (last === ")" && token.slice(0, end).split("(").length <= token.slice(0, end).split(")").length - 1) end--;
+    else break;
+  }
+  return token.slice(0, end);
+};
+
+/** The forms of one address that count as the same read: as written, without its fragment, and over HTTPS. */
+const addressForms = (raw: string, add: (address: string) => void) => {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return;
+  const forms = [url.href];
+  if (url.hash) forms.push(url.href.slice(0, -url.hash.length));
+  // Upgrading to HTTPS carries no data the address did not already carry.
+  if (url.protocol === "http:") forms.push(...forms.map((form) => `https:${form.slice("http:".length)}`));
+  for (const form of forms) if (form.length <= WEB_ADDRESS_MAX_CHARS) add(form);
+};
+
+/**
+ * Every whole address in a text, normalized like a URL the tools read. Only complete tokens count, never a part of a
+ * longer address; with `typed`, an address written without its scheme counts too, as a person often types it.
+ */
+export const webAddressesIn = (text: string, options: { typed?: boolean } = {}): Set<string> => {
+  const addresses = new Set<string>();
+  const add = (address: string) => addresses.add(address);
+  const rest = text.replace(URL_TOKEN, (token) => {
+    addressForms(trimToken(token), add);
+    return " ";
+  });
+  if (options.typed)
+    for (const [token] of rest.matchAll(BARE_TOKEN)) {
+      const bare = trimToken(token);
+      addressForms(`https://${bare}`, add);
+      addressForms(`http://${bare}`, add);
+    }
+  return addresses;
+};
+
+/** Records addresses a web search returned or a page read in this chat links to; later reads of them do not ask. */
+export const recordWebAddresses = async (conversationId: string, addresses: Iterable<string>): Promise<void> => {
+  const list = [...addresses];
+  if (!list.length) return;
+  await sql`
+    INSERT INTO ai.web_addresses (conversation_id, address)
+    SELECT ${conversationId}::uuid, address FROM unnest(${toPgTextArray(list)}::text[]) address
+    ON CONFLICT DO NOTHING
+  `;
+};
+
+/**
+ * Whether the chat itself supplied this address: the person wrote it, a web search returned it, or a page read
+ * earlier links to it. A message another chat sent counts as neither. Anything else, such as an address the model
+ * assembled from other data, has no provenance. `url` is the normalized address the tool reads.
+ */
+export const hasWebAddressProvenance = async (conversationId: string, url: string): Promise<boolean> => {
+  const [recorded] = await sql<{ found: boolean }[]>`
+    SELECT EXISTS (SELECT 1 FROM ai.web_addresses WHERE conversation_id = ${conversationId}::uuid AND address = ${url}) AS found
+  `;
+  if (recorded?.found) return true;
+  // Only the person's own messages that name the host are read, never tool results.
+  const { hostname } = new URL(url);
+  const hosts = [...new Set([hostname, domainToUnicode(hostname) || hostname])];
+  const rows = await sql<{ text: string }[]>`
+    SELECT text FROM (
+      SELECT message, meta FROM ai.messages WHERE conversation_id = ${conversationId}::uuid AND kind = 'message' AND role = 'user'
+      UNION ALL
+      SELECT message, meta FROM ai.task_messages WHERE conversation_id = ${conversationId}::uuid AND kind = 'message' AND role = 'user'
+    ) entry
+    CROSS JOIN LATERAL (
+      SELECT string_agg(CASE WHEN jsonb_typeof(part) = 'string' THEN part #>> '{}' ELSE part->>'text' END, chr(10)) AS text
+      FROM jsonb_array_elements(CASE WHEN jsonb_typeof(entry.message->'content') = 'array' THEN entry.message->'content' ELSE '[]'::jsonb END) part
+      WHERE jsonb_typeof(part) = 'string' OR part->>'type' = 'text'
+    ) content
+    WHERE NOT COALESCE(entry.meta ? 'agentMessage', false)
+      AND EXISTS (SELECT 1 FROM unnest(${toPgTextArray(hosts)}::text[]) host WHERE strpos(lower(content.text), host) > 0)
+  `;
+  return rows.some((row) => webAddressesIn(row.text, { typed: true }).has(url));
+};

package/src/api/capabilities.ts

@@ -613,11 +613,12 @@ const runCapabilityDispatch = async (
     : schemaValidator(`${operation.schemaHash}:result`, capabilityResultJsonSchema(operation.dataSchema));
   const parsedResult = resultValidator?.safeParse(upstreamBody.data);
   const parsedReview = params.review ? CapabilityActionReviewSchema.safeParse(upstreamBody.data) : null;
+  // A rememberable Action may leave out its scope for arguments that should ask every time; any other Action has none.
   const reviewApprovalScopeIsValid =
     !params.review ||
-    !("approval" in operation) ||
     !parsedReview?.success ||
-    (operation.approval === "rememberable" ? parsedReview.data.approvalScope !== undefined : parsedReview.data.approvalScope === undefined);
+    ("approval" in operation && operation.approval === "rememberable") ||
+    parsedReview.data.approvalScope === undefined;
   if (!resultValidator || !parsedResult?.success || !reviewApprovalScopeIsValid) {
     if (actionWithoutRetrySafety) return settle(outcomeUnknown(), "uncertain");
     const invalid = errorResponse("INVALID_APP_RESPONSE", messages.outsideResultSchema({ appId: params.appId }), 502);

package/src/api/widgets.ts

@@ -2,6 +2,9 @@ import { type Context, Hono, type MiddlewareHandler } from "hono";
 import { readBoundedJson } from "../_internal/bounded-json";
 import { type DashboardWidget, listWidgets } from "../_internal/registry";
 import {
+  type DashboardWidgetSize,
+  fitWidgetSize,
+  isDashboardWidgetSize,
   WIDGET_MAX_RESPONSE_BYTES,
   type WidgetResponse,
   WidgetResponseSchema,
@@ -9,6 +12,7 @@ import {
   widgetKey,
 } from "../contracts/widgets";
 import { type AuthContext, auth, preferredLocale, rejectReservedWorkloadCredential } from "../server";
+import { WIDGET_SIZE_PARAM } from "../server/widget-request";
 import { CLOUD_INVOCATION_TOKEN_TTL_SECONDS } from "../services/identity/constants";
 import { invocationAuthorityFromRequest } from "../services/identity/invocation-authority";
 import { widgetInvocationOperation } from "../services/identity/invocation-operations";
@@ -78,6 +82,8 @@ type ProviderOutcome =
 const callProvider = async (options: {
   c: Context<AuthContext>;
   widget: DashboardWidget;
+  /** What the browser asked for, fitted to the widget's declared sizes before it reaches the app. */
+  size: unknown;
   token: string;
   requestId: string | undefined;
   signal: AbortSignal;
@@ -98,6 +104,7 @@ const callProvider = async (options: {
     headers.set("x-cloud-invocation-operation", widgetInvocationOperation(widget.widgetId));
 
     const targetUrl = new URL(`/api/_internal/widgets/v1/${encodeURIComponent(widget.widgetId)}`, widget.url);
+    targetUrl.searchParams.set(WIDGET_SIZE_PARAM, fitWidgetSize(options.size, widget));
     signal.throwIfAborted();
     const response = await options.fetch(targetUrl, { headers, signal });
     if (response.status === 204 || response.status === 403) {
@@ -125,6 +132,17 @@ const callProvider = async (options: {
   }
 };
 
+/**
+ * `<appId>/<widgetId>` with an optional `@small`, `@medium`, or `@large`, as the key and the size it asks for. The
+ * suffix is a size whenever the key before it is declared; `defineApp()` rejects `@` in widget IDs, so only an app
+ * built before sizes existed can declare an ID that ends in such a suffix, and it is still asked by that whole ID.
+ */
+const parseRequestedWidget = (value: string, declared: ReadonlySet<string>): [string, DashboardWidgetSize | undefined] => {
+  const at = value.lastIndexOf("@");
+  const size = at < 0 ? undefined : value.slice(at + 1);
+  return isDashboardWidgetSize(size) && declared.has(value.slice(0, at)) ? [value.slice(0, at), size] : [value, undefined];
+};
+
 export const createWidgetRoutes = (dependencies: WidgetRouteDependencies = {}) => {
   const registry = dependencies.listWidgets ?? listWidgets;
   const fetchWidget = dependencies.fetch ?? globalThis.fetch;
@@ -155,17 +173,20 @@ export const createWidgetRoutes = (dependencies: WidgetRouteDependencies = {}) =
       .use(rejectReservedWorkloadCredential)
       .use(auth.requireOAuthScope("read", "admin"))
       /**
-       * Every requested widget (`?widget=<appId>/<widgetId>`, repeatable; all declared widgets without one) as an
-       * NDJSON stream: one line per widget as soon as it answers, each within its own budget.
+       * Every requested widget (`?widget=<appId>/<widgetId>`, repeatable, optionally with `@<size>`; all declared
+       * widgets without one) as an NDJSON stream: one line per widget as soon as it answers, each within its own budget.
        */
       .get("/widgets/v1", async (c) => {
         const requestId = normalizeInvocationRequestId(c.req.header("x-request-id"));
-        const requested = new Set(c.req.queries("widget") ?? []);
         const setup = AbortSignal.any([c.req.raw.signal, AbortSignal.timeout(timeoutMs)]);
         let widgets: DashboardWidget[];
+        let requested = new Map<string, DashboardWidgetSize | undefined>();
         try {
           const keys = new Set<string>();
-          widgets = (await waitWithin(registry(), setup)).filter((widget) => {
+          const declared = await waitWithin(registry(), setup);
+          const declaredKeys = new Set(declared.map((widget) => widgetKey(widget.appId, widget.widgetId)));
+          requested = new Map((c.req.queries("widget") ?? []).map((value) => parseRequestedWidget(value, declaredKeys)));
+          widgets = declared.filter((widget) => {
             const key = widgetKey(widget.appId, widget.widgetId);
             if (keys.has(key) || (requested.size > 0 && !requested.has(key))) return false;
             keys.add(key);
@@ -222,6 +243,7 @@ export const createWidgetRoutes = (dependencies: WidgetRouteDependencies = {}) =
               signal: AbortSignal.any([fanoutSignal, timeout]),
               timeout,
               fetch: fetchWidget,
+              size: requested.get(key),
             });
             if (outcome.status === "ok") return { type: "widget", key, status: "ok", widget: outcome.widget, ms: elapsed() };
             // A widget the stream itself stopped has already been settled, and is logged once, below.
@@ -276,7 +298,16 @@ export const createWidgetRoutes = (dependencies: WidgetRouteDependencies = {}) =
           );
 
           phase = "provider";
-          const outcome = await callProvider({ c, widget, token: signed.token, requestId, signal, timeout, fetch: fetchWidget });
+          const outcome = await callProvider({
+            c,
+            widget,
+            size: c.req.query(WIDGET_SIZE_PARAM),
+            token: signed.token,
+            requestId,
+            signal,
+            timeout,
+            fetch: fetchWidget,
+          });
           if (outcome.status === "ok") return Response.json(outcome.widget, { headers: { "content-type": "application/json" } });
           if (!("reason" in outcome))
             return new Response(null, { status: outcome.status === "empty" ? 204 : 403, headers: { "content-type": "application/json" } });

package/src/browser/CloudResourceSearch.tsx

@@ -824,7 +824,7 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
                 focusInput();
               }}
             >
-              ← {t().back}
+              <i class="ti ti-arrow-left" aria-hidden="true" /> {t().back}
             </Button>
             <div class="cloud-resource-search__preview-app">
               <i class={item().icon ?? item().appIcon} aria-hidden="true" />

package/src/browser/command-shortcuts.ts

@@ -31,12 +31,21 @@ export const shortcutLabel = (shortcut: string): string => {
   if (!combination) return "";
   const mac = isMac();
   const names = { ctrl: mac ? "⌃" : "Ctrl", alt: mac ? "⌥" : "Alt", shift: mac ? "⇧" : "Shift", meta: mac ? "⌘" : "Meta" };
-  return [...modifiers.filter((key) => combination[key]).map((key) => names[key]), combination.key.toUpperCase()].join(mac ? "" : "+");
+  const arrows: Record<string, string> = { arrowup: "↑", arrowdown: "↓", arrowleft: "←", arrowright: "→" };
+  const key = arrows[combination.key] ?? combination.key.toUpperCase();
+  return [...modifiers.filter((name) => combination[name]).map((name) => names[name]), key].join(mac ? "" : "+");
 };
 
-/** One owner in the Cloud layout; app islands only publish commands. */
+const ARROWS = new Set(["arrowup", "arrowdown", "arrowleft", "arrowright"]);
+
+/**
+ * One owner in the Cloud layout; app islands only publish commands. A command
+ * on an arrow key comes last: the focused element sees the key first, and a
+ * widget that moves with arrow keys, such as a tree that reorders on Alt+↑ or
+ * an open list, keeps it by handling it.
+ */
 export const attachCommandShortcuts = (run: (command: ContextAwareCommand) => void): (() => void) => {
-  const listener = (event: KeyboardEvent) => {
+  const listener = (event: KeyboardEvent, arrows: boolean) => {
     if (event.defaultPrevented || event.repeat || event.isComposing || (!isMac() && event.getModifierState("AltGraph"))) return;
     const target = event.target;
     const editing =
@@ -47,7 +56,7 @@ export const attachCommandShortcuts = (run: (command: ContextAwareCommand) => vo
       if (!command.shortcut) return false;
       if (command.id !== "cloud.search" && dialogOpen) return false;
       const combo = parse(command.shortcut);
-      if (!combo || (editing && !combo.ctrl && !combo.meta)) return false;
+      if (!combo || ARROWS.has(combo.key) !== arrows || (editing && !combo.ctrl && !combo.meta)) return false;
       // Shift+/ reports '?' on common keyboard layouts.
       const key = event.key === "?" && combo.key === "/" ? "/" : event.key.toLowerCase();
       const physicalLetter =
@@ -69,8 +78,14 @@ export const attachCommandShortcuts = (run: (command: ContextAwareCommand) => vo
     run(matches[0]!);
   };
   // Registered app combinations must win over editor bindings such as Mod+Shift+K.
-  window.addEventListener("keydown", listener, true);
-  return () => window.removeEventListener("keydown", listener, true);
+  const first = (event: KeyboardEvent) => listener(event, false);
+  const last = (event: KeyboardEvent) => listener(event, true);
+  window.addEventListener("keydown", first, true);
+  window.addEventListener("keydown", last);
+  return () => {
+    window.removeEventListener("keydown", first, true);
+    window.removeEventListener("keydown", last);
+  };
 };
 
 export { COMMANDS_CHANGED };

package/src/browser/spotlight-position.ts

@@ -1,4 +1,4 @@
-import type { DialogRender } from "@k2b/ui";
+import { type DialogRender, suppressTextSelection } from "@k2b/ui";
 
 export type SpotlightPosition = { x: number; y: number };
 const STORAGE_KEY = "cloud.spotlight.position.v1";
@@ -42,6 +42,7 @@ export const attachSpotlightPosition = (
     origin: SpotlightPosition;
     previous: SpotlightPosition | null;
     handle: HTMLElement;
+    releaseTextSelection: () => void;
   } | null = null;
 
   const home = document.createElement("div");
@@ -108,6 +109,7 @@ export const attachSpotlightPosition = (
     if (!drag) return;
     const handle = drag.handle;
     const id = drag.id;
+    drag.releaseTextSelection();
     drag = null;
     if (handle.hasPointerCapture(id)) handle.releasePointerCapture(id);
     delete host.dataset.dragging;
@@ -132,6 +134,7 @@ export const attachSpotlightPosition = (
       origin: { x: rect.x, y: rect.y },
       previous: position,
       handle,
+      releaseTextSelection: suppressTextSelection(event.pointerId),
     };
     handle.setPointerCapture(event.pointerId);
   };

package/src/browser/widgets.ts

@@ -1,23 +1,25 @@
-import type { WidgetStreamLine } from "../contracts/widgets";
+import type { DashboardWidgetSize, WidgetStreamLine } from "../contracts/widgets";
 import { LOCALE_HEADER } from "../shared/locale";
 import { NDJSON_CONTENT_TYPE, readNdjsonLines } from "./ndjson";
 
-export type { WidgetResponse, WidgetStreamLine, WidgetStreamStatus } from "../contracts/widgets";
+export type { DashboardWidgetSize, WidgetResponse, WidgetStreamLine, WidgetStreamStatus } from "../contracts/widgets";
 
 /**
  * Asks Core for dashboard widgets and hands over each one as soon as it answers: `start` names the widgets, one
  * `widget` line follows per widget in the order they finish, then `done`. `keys` (`<appId>/<widgetId>`) limits the
- * request, for example to retry one widget; without it Core asks every declared widget. Aborting `signal` stops every
- * widget Core still waits for. Rejects when the request fails or the stream breaks off.
+ * request, for example to retry one widget; without it Core asks every declared widget. `sizes` names the size to ask
+ * a widget for; a widget without one, or with a size it does not offer, answers in its default size. Aborting `signal`
+ * stops every widget Core still waits for. Rejects when the request fails or the stream breaks off.
  */
 export const streamWidgets = async (options: {
   keys?: readonly string[];
+  sizes?: Readonly<Record<string, DashboardWidgetSize>>;
   signal: AbortSignal;
   locale: string;
   onLine: (line: WidgetStreamLine) => void;
 }): Promise<void> => {
   const query = new URLSearchParams();
-  for (const key of options.keys ?? []) query.append("widget", key);
+  for (const key of options.keys ?? []) query.append("widget", options.sizes?.[key] ? `${key}@${options.sizes[key]}` : key);
   const search = query.toString();
   const response = await fetch(`/api/widgets/v1${search ? `?${search}` : ""}`, {
     signal: options.signal,

package/src/capabilities/executions.ts

@@ -1,5 +1,6 @@
 import { sql } from "bun";
 import type { CapabilityOrigin } from "../contracts/capabilities";
+import { pruneApprovalRequests } from "../services/approvals";
 import { logger } from "../services/logging";
 import { CAPABILITY_CLAIM_RETENTION_HOURS, pruneCapabilityIdempotencyClaims } from "./claims";
 
@@ -280,6 +281,8 @@ export const startCapabilityExecutionMaintenance = (): (() => void) => {
     try {
       const removed = await pruneCapabilityExecutions(new Date(Date.now() - CAPABILITY_EXECUTION_RETENTION_DAYS * 86_400_000));
       if (removed > 0) log.info("Pruned expired capability executions", { removed });
+      const requests = await pruneApprovalRequests(new Date(Date.now() - CAPABILITY_EXECUTION_RETENTION_DAYS * 86_400_000));
+      if (requests > 0) log.info("Pruned expired approval requests", { removed: requests });
       const claims = await pruneCapabilityIdempotencyClaims(new Date(Date.now() - CAPABILITY_CLAIM_RETENTION_HOURS * 3_600_000));
       if (claims > 0) log.info("Pruned expired capability idempotency claims", { removed: claims });
     } catch (error) {

package/src/cli/commands.ts

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import type { CloudCliContext, CloudCliFlagValue, CloudCliModule } from "./index";
+import { isCloudCliAlias, isCloudCliShortcuts } from "./plugin";
 
 type FlagKind = "string" | "boolean" | "int" | "enum" | "stringList" | "input";
 type ArgKind = "required" | "optional" | "rest";
@@ -155,6 +156,8 @@ type CommandNode = {
 type CliCommandsConfig = {
   name: string;
   summary: string;
+  alias?: string;
+  shortcuts?: Readonly<Record<string, string>>;
   requiresCloud?: boolean;
   groupSummaries?: Readonly<Record<string, string>>;
   commands: readonly CliCommandDefinition[];
@@ -241,10 +244,27 @@ export const readCliInput = async (input: CliInputFlagValue, options: ReadCliInp
 
 export const defineCliCommands = (config: CliCommandsConfig): CloudCliModule => {
   const root = buildCommandTree(config.commands, config.groupSummaries);
+  if (config.alias !== undefined && !isCloudCliAlias(config.alias, config.name)) {
+    throw new Error("CLI alias must be a lowercase kebab-case name different from the module name");
+  }
+  let shortcuts: Record<string, string> | undefined;
+  if (config.shortcuts !== undefined) {
+    if (!isCloudCliShortcuts(config.shortcuts, config.name, config.alias)) {
+      throw new Error("CLI shortcuts require unique kebab-case names and non-empty command paths without flags");
+    }
+    shortcuts = {};
+    for (const [name, target] of Object.entries(config.shortcuts)) {
+      const segments = target.trim().split(/\s+/);
+      if (!findNode(root, segments)?.command) throw new Error(`Unknown CLI shortcut command path: ${target}`);
+      shortcuts[name] = segments.join(" ");
+    }
+  }
 
   return {
     name: config.name,
     summary: config.summary,
+    ...(config.alias !== undefined ? { alias: config.alias } : {}),
+    ...(shortcuts !== undefined ? { shortcuts } : {}),
     requiresCloud: config.requiresCloud,
     requiresCloudFor: (args) => {
       const helpRequest = normalizeHelpRequest(args, {});