@k2b/cloud 0.30.0 → 0.32.0

package/src/ai/vision-tool.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
+import { aiMissingChatFileError } from "./file-error";
 import { aiProjectFilePathFromMount } from "./file-mount";
 import { aiFileStore, normalizeAiFilePath } from "./files-store";
 import { PdfPages, renderPdfPages } from "./pdf-render";
@@ -53,7 +54,7 @@ export const createCloudAiViewImageTool = (options: { resolveModel?: () => Promi
     if (snapshotRequired && !snapshot) throw new Error(`Attached image snapshot is unavailable: ${path}`);
     const stored =
       projectFile ?? snapshot ?? (projectPath === null ? await aiFileStore.read({ conversationId: ctx.conversationId, path }) : null);
-    if (!stored) throw new Error(`No such file: ${path}`);
+    if (!stored) throw aiMissingChatFileError(path, ctx.localToolsEnabled);
     const pdf = stored.mediaType === "application/pdf";
     if (!pdf && !isAiImageMediaType(stored.mediaType)) throw new Error(`${path} is not a supported image or PDF (${stored.mediaType}).`);
     if (!pdf && input.pages !== undefined) throw new Error("pages can only be used with a PDF.");

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/admin-identity.ts

@@ -5,6 +5,7 @@ import { describeRoute } from "hono-openapi";
 import { z } from "zod";
 import { listApps } from "../_internal/registry";
 import { CapabilityAppIdSchema } from "../contracts/capabilities";
+import { AI_INFERENCE_SCOPE } from "../contracts/shared";
 import { type AuthContext, auth, err, respond, v } from "../server";
 import { audit } from "../services/audit";
 import { getIdentitySigningKeyStatus, identityMetrics, revokeIdentitySigningKey, rewrapIdentitySigningKeys } from "../services/identity";
@@ -63,7 +64,11 @@ const ServiceAccountStatusInputSchema = z.object({ status: z.enum(["active", "di
 const ServiceAccountApiKeyInputSchema = z
   .object({
     name: z.string().trim().min(1).max(120),
-    scopes: z.array(z.string().trim().min(1).max(64)).max(20).default([]),
+    scopes: z
+      .array(z.string().trim().min(1).max(64))
+      .max(20)
+      .default([])
+      .refine((scopes) => !scopes.includes(AI_INFERENCE_SCOPE), "ai:inference is reserved for models-only personal API keys"),
     expiresAt: z.iso.datetime().nullable().optional(),
   })
   .strict();

package/src/api/app-approval-actions.ts

@@ -0,0 +1,36 @@
+import { submitAiTurnAction } from "../ai/runtime";
+import { aiConversations } from "../ai/store";
+import { APP_ACTION_LIMITS } from "../contracts/app-approval";
+import type { AppDeviceActions } from "../services/app-approval";
+import { listPending } from "../services/approvals";
+import { appActionSummary, appActionView } from "../services/approvals/device";
+
+export const createDeviceActions = (appName: (appId: string, locale: string) => string): AppDeviceActions => {
+  const view: AppDeviceActions["view"] = async ({ userId, issuer, actionId }) => {
+    const { items } = await listPending({ approverUserId: userId, id: actionId, limit: 1 });
+    return items[0] ? appActionView(items[0], { issuer, appName }) : null;
+  };
+  return {
+    inbox: async ({ userId, issuer }) => {
+      const { items, count } = await listPending({ approverUserId: userId, limit: APP_ACTION_LIMITS.inboxActions });
+      const views = await Promise.all(items.map((row) => appActionView(row, { issuer, appName })));
+      return { actions: views.map(appActionSummary), moreActions: Math.max(0, count - items.length) };
+    },
+    view,
+    decide: async ({ userId, deviceId, issuer, actionId, digest, approved }) => {
+      const current = await view({ userId, issuer, actionId });
+      if (!current || current.digest !== digest) return false;
+      const pending = await aiConversations.findPendingTurnActionByApproval({ approvalId: actionId, ownerUserId: userId });
+      if (!pending) return false;
+      const result = await submitAiTurnAction({
+        conversationId: pending.conversationId,
+        turnId: pending.turnId,
+        callId: pending.callId,
+        action: { type: "approval_response", approved },
+        decidedBy: { userId, via: "cloud_login", deviceId },
+        signedInSession: false,
+      });
+      return result.ok;
+    },
+  };
+};

package/src/api/app-approval.ts

@@ -16,13 +16,15 @@ import {
 } from "../contracts/app-approval";
 import { type AuthContext, auth, rateLimit, v } from "../server";
 import { type AppApprovalActor, AppApprovalError, appApproval, type createAppApprovalService } from "../services/app-approval";
+import { appNameIn } from "../ssr/runtime";
+import { createDeviceActions } from "./app-approval-actions";
 
 const PairingIdSchema = z.object({ pairingId: z.string().uuid() }).strict();
 const DevicePageSchema = z.object({ after: z.string().uuid().optional() }).strict();
 type Service = ReturnType<typeof createAppApprovalService>;
 
 /** This is a separate credential surface, never a user API-key or OAuth scope. */
-export const createAppApprovalRoutes = (service: Service = appApproval) => {
+export const createAppApprovalRoutes = (service: Service = appApproval, actions = createDeviceActions) => {
   const actor = async (c: Parameters<typeof auth.session.getToken>[0]): Promise<AppApprovalActor> => {
     // The web session (or an explicit bearer session), never the mobile app's session: a phone
     // that pairs sign-in devices would hand out authority that outlives its removal.
@@ -104,7 +106,13 @@ export const createAppApprovalRoutes = (service: Service = appApproval) => {
       "/device",
       describeRoute({ tags: ["App approval"], summary: "Execute a one-use signed device command" }),
       v("json", AppDeviceRequestSchema),
-      async (c) => c.json(await service.deviceCommand(c.req.valid("json"))),
+      async (c) =>
+        c.json(
+          await service.deviceCommand(
+            c.req.valid("json"),
+            actions((appId, locale) => appNameIn(c, appId, locale, appId)),
+          ),
+        ),
     )
     .post(
       "/login/start",

package/src/api/approvals-loader.ts

@@ -0,0 +1,15 @@
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { resolveAiChatRequestContext } from "../ai/request-context";
+import type { ApprovalListQuery, ApprovalPage } from "../contracts/approvals";
+import type { AuthContext } from "../server/middleware/auth";
+import { listPending, presentPendingApproval } from "../services/approvals/list";
+import { getLocalizedRuntimeContext } from "../ssr/runtime";
+
+export const loadPendingApprovals = async <T extends AuthContext>(c: Context<T>, query: ApprovalListQuery): Promise<ApprovalPage> => {
+  const ctx = await resolveAiChatRequestContext(c);
+  if (ctx instanceof Response) throw new HTTPException(403, { res: ctx });
+  const page = await listPending({ approverUserId: ctx.ownerUserId, appId: query.app, link: query.link, cursor: query.cursor });
+  const apps = getLocalizedRuntimeContext(c).apps;
+  return { ...page, items: page.items.map((row) => presentPendingApproval(row, apps)) };
+};

package/src/api/approvals.ts

@@ -0,0 +1,120 @@
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import { toAiActionFailureResponse } from "../ai/http";
+import { resolveAiChatRequestContext } from "../ai/request-context";
+import { submitAiTurnAction } from "../ai/runtime";
+import { aiConversations } from "../ai/store";
+import {
+  APPROVAL_CLIENT_HEADER,
+  ApprovalCountsSchema,
+  ApprovalDecisionInputSchema,
+  ApprovalDecisionResultSchema,
+  ApprovalListQuerySchema,
+  ApprovalPageSchema,
+} from "../contracts/approvals";
+import { ErrorResponseSchema } from "../contracts/shared";
+import { rateLimit } from "../server";
+import { respond } from "../server/api";
+import { type AuthContext, auth } from "../server/middleware/auth";
+import { jsonResponse, requiresAuth } from "../server/middleware/openapi";
+import { v } from "../server/middleware/validator";
+import { ok } from "../server/services";
+import { approvalDecisionChannel, countPending } from "../services/approvals";
+import { decodeApprovalCursor } from "../services/approvals/cursor";
+import { loadPendingApprovals } from "./approvals-loader";
+
+export const approvalRoutes = new Hono<AuthContext>()
+  .use(rateLimit())
+  .use(auth.requireRole("authenticated"))
+  .get(
+    "/",
+    describeRoute({
+      tags: ["Approvals"],
+      summary: "List pending Action approvals",
+      ...requiresAuth,
+      responses: {
+        200: jsonResponse(ApprovalPageSchema, "Pending approvals"),
+        400: jsonResponse(ErrorResponseSchema, "Invalid query"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "User-backed actor required"),
+      },
+    }),
+    v(
+      "query",
+      ApprovalListQuerySchema.refine((query) => !query.cursor || decodeApprovalCursor(query.cursor) !== null, "Invalid approval cursor."),
+    ),
+    async (c) => respond(c, ok(await loadPendingApprovals(c, c.req.valid("query")))),
+  )
+  .get(
+    "/counts",
+    describeRoute({
+      tags: ["Approvals"],
+      summary: "Count pending Action approvals",
+      ...requiresAuth,
+      responses: {
+        200: jsonResponse(ApprovalCountsSchema, "Approval counts"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "User-backed actor required"),
+      },
+    }),
+    async (c) => {
+      const ctx = await resolveAiChatRequestContext(c);
+      if (ctx instanceof Response) return ctx;
+      return respond(c, ok(await countPending({ approverUserId: ctx.ownerUserId })));
+    },
+  )
+  .post(
+    "/:id/decision",
+    bodyLimit({ maxSize: 1024 }),
+    describeRoute({
+      tags: ["Approvals"],
+      summary: "Decide an Action approval and continue its chat",
+      ...requiresAuth,
+      responses: {
+        200: jsonResponse(ApprovalDecisionResultSchema, "Approval decision"),
+        400: jsonResponse(ErrorResponseSchema, "Invalid decision"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Decision refused"),
+        404: jsonResponse(ErrorResponseSchema, "Open approval not found"),
+        409: jsonResponse(ErrorResponseSchema, "Already decided differently"),
+        413: jsonResponse(ErrorResponseSchema, "Request body too large"),
+      },
+    }),
+    v("param", z.object({ id: z.uuid() })),
+    v("json", ApprovalDecisionInputSchema),
+    async (c) => {
+      const ctx = await resolveAiChatRequestContext(c);
+      if (ctx instanceof Response) return ctx;
+      const pending = await aiConversations.findPendingTurnActionByApproval({
+        approvalId: c.req.valid("param").id,
+        ownerUserId: ctx.ownerUserId,
+      });
+      if (!pending)
+        return toAiActionFailureResponse(c, {
+          ok: false,
+          status: 404,
+          message: "This request has expired — the assistant already moved on.",
+        });
+      const decision = c.req.valid("json");
+      const result = await submitAiTurnAction({
+        conversationId: pending.conversationId,
+        turnId: pending.turnId,
+        callId: pending.callId,
+        action: { type: "approval_response", ...decision },
+        decidedBy: {
+          userId: ctx.ownerUserId,
+          via: approvalDecisionChannel({
+            credentialKind: c.get("credentialKind"),
+            actor: ctx.actor,
+            client: c.req.header(APPROVAL_CLIENT_HEADER),
+          }),
+        },
+        toolApprovalContext: ctx.toolApprovalContext,
+        signedInSession: ctx.signedInSession,
+      });
+      if (!result.ok) return toAiActionFailureResponse(c, result);
+      return respond(c, ok({ status: decision.approved ? ("approved" as const) : ("rejected" as const) }));
+    },
+  );

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/index.ts

@@ -33,6 +33,7 @@ import adminOutgoingMailRoutes from "./admin-outgoing-mail";
 import adminRailRoutes from "./admin-rail";
 import { adminAnnouncementRoutes, announcementRoutes } from "./announcements";
 import { createAppApprovalRoutes } from "./app-approval";
+import { approvalRoutes } from "./approvals";
 import { appDiscoveryRoutes } from "./apps";
 import { createAuthRoutes } from "./auth";
 import { createCapabilityRoutes } from "./capabilities";
@@ -44,6 +45,7 @@ import { createSearchRoutes } from "./search";
 import { createSyncOpsProxyRoutes } from "./sync-ops";
 import { createWidgetRoutes } from "./widgets";
 
+export { createAiOpenAiRoutes } from "../ai/openai-api";
 export { type CapabilityDispatchDependencies, dispatchCapability } from "./capabilities";
 export { cliPluginListRoutes } from "./cli-plugins";
 export { createPwaPhoneRoutes } from "./pwa-phone";
@@ -72,6 +74,7 @@ const buildCoreApi = (options: CoreApiOptions) => {
     .route("/me", meRoutes)
     .route("/accounts", accountsEntitiesRoutes)
     .route("/apps", appDiscoveryRoutes)
+    .route("/approvals", approvalRoutes)
     .route("/announcements", announcementRoutes)
     .route("/admin/core/ai-usage", adminAiUsageRoutes)
     .route("/admin/core/ai-quotas", adminAiQuotaRoutes)

package/src/api/me.ts

@@ -4,7 +4,7 @@
  * third-party management lives in the accounts admin app.
  */
 
-import { ok } from "@k2b/stdlib";
+import { err, fail, ok } from "@k2b/stdlib";
 import { type Context, Hono, type MiddlewareHandler } from "hono";
 import { createMiddleware } from "hono/factory";
 import { describeRoute } from "hono-openapi";
@@ -51,6 +51,7 @@ import {
   webauthn,
 } from "../services";
 import { MandatePolicyV1Schema } from "../services/mandates";
+import { coreSettings } from "../services/settings/api";
 
 import { createMeRailRoutes } from "./me-rail";
 import { createMeWebVitalsRoutes } from "./me-web-vitals";
@@ -614,13 +615,14 @@ const app = new Hono<AuthContext>()
     describeRoute({
       tags: ["Me"],
       summary: "Create current user API key",
-      description: "Create a user-bound API key for the authenticated account. The raw token is returned once.",
+      description:
+        "Create a personal API key with full access (default) or models-only access to the OpenAI-compatible API when enabled. The raw token is returned once.",
       ...requiresAuth,
       responses: {
         201: jsonResponse(CreateUserApiKeyResponseSchema, "API key created"),
         400: jsonResponse(ErrorResponseSchema, "Failed to create API key"),
         401: jsonResponse(ErrorResponseSchema, "Authentication required"),
-        403: jsonResponse(ErrorResponseSchema, "Not permitted for API keys or other credentials"),
+        403: jsonResponse(ErrorResponseSchema, "Credential not permitted or models-only API turned off"),
       },
     }),
     v("json", CreateUserApiKeySchema),
@@ -630,7 +632,14 @@ const app = new Hono<AuthContext>()
         async () => {
           const user = c.get("user");
           const data = c.req.valid("json");
+          if (data.access === "models" && !(await coreSettings.get<boolean>("ai.openai_api_enabled")))
+            return fail(
+              err.forbidden(
+                "Models-only API keys are turned off. An administrator can turn on the OpenAI-compatible API in the AI settings.",
+              ),
+            );
           return serviceAccountCredentials.createUserApiToken({
+            access: data.access,
             user,
             name: data.name,
             expiresAt: data.expiresAt ?? null,

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/approvals/Approvals.browser-harness.tsx

@@ -0,0 +1,16 @@
+import { LocaleProvider } from "@k2b/ui";
+import { render } from "solid-js/web";
+import Approvals from "./Approvals";
+
+/** Renders the real list for a browser test, which answers the approvals API with invented requests. */
+const host = document.getElementById("root");
+if (!host) throw new Error("Missing harness root");
+const layout = new URLSearchParams(location.search).get("layout") === "band" ? "band" : "list";
+render(
+  () => (
+    <LocaleProvider locale={document.documentElement.lang || "en"}>
+      <Approvals app="assistant" layout={layout} />
+    </LocaleProvider>
+  ),
+  host,
+);