@k2b/cloud 0.29.1 → 0.30.0

package/src/api/widgets.ts

@@ -1,14 +1,22 @@
-import { Hono, type MiddlewareHandler } from "hono";
+import { type Context, Hono, type MiddlewareHandler } from "hono";
 import { readBoundedJson } from "../_internal/bounded-json";
-import { listWidgets } from "../_internal/registry";
-import { WIDGET_MAX_RESPONSE_BYTES, WidgetResponseSchema } from "../contracts/widgets";
+import { type DashboardWidget, listWidgets } from "../_internal/registry";
+import {
+  WIDGET_MAX_RESPONSE_BYTES,
+  type WidgetResponse,
+  WidgetResponseSchema,
+  type WidgetStreamLine,
+  widgetKey,
+} from "../contracts/widgets";
 import { type AuthContext, auth, preferredLocale, rejectReservedWorkloadCredential } from "../server";
+import { CLOUD_INVOCATION_TOKEN_TTL_SECONDS } from "../services/identity/constants";
 import { invocationAuthorityFromRequest } from "../services/identity/invocation-authority";
 import { widgetInvocationOperation } from "../services/identity/invocation-operations";
 import { normalizeInvocationRequestId, signInvocationToken } from "../services/identity/invocation-token";
 import { withActiveIdentitySigner } from "../services/identity/key-ring";
 import { logger } from "../services/logging";
 import { LOCALE_HEADER } from "../shared/locale";
+import { ndjsonStream, startBounded, waitWithin } from "./fanout";
 
 type WidgetRouteDependencies = {
   listWidgets?: typeof listWidgets;
@@ -19,7 +27,19 @@ type WidgetRouteDependencies = {
   timeoutMs?: number;
 };
 
-export const WIDGET_PROXY_TIMEOUT_MS = 500;
+/**
+ * Each widget's own budget, counted from the moment Core starts it: the same interactive budget Universal Search
+ * gives its providers. Widgets stream in as they finish, so a slow one delays only itself.
+ */
+export const WIDGET_TIMEOUT_MS = 8_000;
+/** Widgets Core asks at the same time for one dashboard, as many as Universal Search asks providers. */
+export const WIDGET_CONCURRENCY = 8;
+/**
+ * A stream signs every invocation up front; no widget may still start after those invocations expire. Widgets that
+ * have not answered by then end as `timeout`.
+ */
+const WIDGET_STREAM_DEADLINE_MS = CLOUD_INVOCATION_TOKEN_TTL_SECONDS * 1_000;
+
 const log = logger("widgets");
 type WidgetRejectionReason =
   | "upstream_timeout"
@@ -30,114 +50,253 @@ type WidgetRejectionReason =
   | "deadline_exceeded"
   | "request_cancelled"
   | "operation_failed";
+type WidgetPhase = "registry" | "signing" | "provider" | "response";
 
-const jsonError = (message: string, status: 502 | 504): Response =>
-  Response.json({ message }, { status, headers: { "content-type": "application/json" } });
-
-const waitWithin = <T>(value: Promise<T>, signal: AbortSignal): Promise<T> =>
-  new Promise<T>((resolve, reject) => {
-    const aborted = () => reject(signal.reason);
-    if (signal.aborted) return aborted();
-    signal.addEventListener("abort", aborted, { once: true });
-    value.then(
-      (result) => {
-        signal.removeEventListener("abort", aborted);
-        resolve(result);
-      },
-      (error) => {
-        signal.removeEventListener("abort", aborted);
-        reject(error);
-      },
-    );
+const logRejection = (
+  widget: { appId: string; widgetId: string },
+  phase: WidgetPhase,
+  reason: WidgetRejectionReason,
+  upstreamStatus?: number,
+) =>
+  log.warn("Widget proxy rejected response", {
+    appId: widget.appId.slice(0, 80),
+    widgetId: widget.widgetId.slice(0, 100),
+    phase,
+    reason,
+    ...(upstreamStatus === undefined ? {} : { upstreamStatus }),
   });
 
+type ProviderOutcome =
+  | { status: "ok"; widget: WidgetResponse }
+  | { status: "empty" | "forbidden" }
+  | { status: "timeout" | "error"; phase: WidgetPhase; reason: WidgetRejectionReason; upstreamStatus?: number };
+
+/**
+ * Calls one provider with its exact invocation and validates the answer. Never throws: every failure becomes a
+ * bounded outcome that the caller logs and reports.
+ */
+const callProvider = async (options: {
+  c: Context<AuthContext>;
+  widget: DashboardWidget;
+  token: string;
+  requestId: string | undefined;
+  signal: AbortSignal;
+  timeout: AbortSignal;
+  fetch: NonNullable<WidgetRouteDependencies["fetch"]>;
+}): Promise<ProviderOutcome> => {
+  const { c, widget, signal, timeout } = options;
+  let phase: WidgetPhase = "provider";
+  try {
+    const headers = new Headers({ authorization: `Bearer ${options.token}` });
+    if (options.requestId) headers.set("x-request-id", options.requestId);
+    for (const name of ["traceparent", "tracestate"] as const) {
+      const value = c.req.header(name);
+      if (value) headers.set(name, value);
+    }
+    const locale = preferredLocale(c.req.raw.headers);
+    if (locale) headers.set(LOCALE_HEADER, locale);
+    headers.set("x-cloud-invocation-operation", widgetInvocationOperation(widget.widgetId));
+
+    const targetUrl = new URL(`/api/_internal/widgets/v1/${encodeURIComponent(widget.widgetId)}`, widget.url);
+    signal.throwIfAborted();
+    const response = await options.fetch(targetUrl, { headers, signal });
+    if (response.status === 204 || response.status === 403) {
+      await response.body?.cancel();
+      return { status: response.status === 204 ? "empty" : "forbidden" };
+    }
+    if (!response.ok) {
+      await response.body?.cancel();
+      return response.status === 504
+        ? { status: "timeout", phase, reason: "upstream_timeout", upstreamStatus: response.status }
+        : { status: "error", phase, reason: "upstream_status", upstreamStatus: response.status };
+    }
+    phase = "response";
+    const body = await readBoundedJson(response, WIDGET_MAX_RESPONSE_BYTES);
+    signal.throwIfAborted();
+    if (!body.ok) return { status: "error", phase, reason: body.reason };
+    const parsed = WidgetResponseSchema.safeParse(body.data);
+    if (!parsed.success) return { status: "error", phase, reason: "invalid_schema" };
+    return { status: "ok", widget: parsed.data };
+  } catch (error) {
+    const isTimeout = timeout.aborted || (error instanceof Error && error.name === "TimeoutError");
+    return isTimeout
+      ? { status: "timeout", phase, reason: "deadline_exceeded" }
+      : { status: "error", phase, reason: signal.aborted ? "request_cancelled" : "operation_failed" };
+  }
+};
+
 export const createWidgetRoutes = (dependencies: WidgetRouteDependencies = {}) => {
   const registry = dependencies.listWidgets ?? listWidgets;
   const fetchWidget = dependencies.fetch ?? globalThis.fetch;
+  const timeoutMs = dependencies.timeoutMs ?? WIDGET_TIMEOUT_MS;
+  const withActiveSigner = dependencies.withActiveSigner ?? withActiveIdentitySigner;
+  const signInvocation = dependencies.signInvocation ?? signInvocationToken;
+
+  const sign = (
+    c: Context<AuthContext>,
+    widget: DashboardWidget,
+    requestId: string | undefined,
+    signer: Parameters<Parameters<typeof withActiveIdentitySigner>[1]>[0],
+  ) =>
+    signInvocation({
+      targetAppId: widget.appId,
+      callingAppId: "core",
+      operation: widgetInvocationOperation(widget.widgetId),
+      schemaHash: null,
+      authority: invocationAuthorityFromRequest(auth.getAuthority(c)),
+      requestId,
+      signer,
+      issuer: signer.issuer,
+    });
 
-  return new Hono<AuthContext>()
-    .use(dependencies.authenticate ?? auth.requireRole("authenticated"))
-    .use(rejectReservedWorkloadCredential)
-    .use(auth.requireOAuthScope("read", "admin"))
-    .get("/widgets/v1/:appId/:widgetId", async (c) => {
-      const timeout = AbortSignal.timeout(dependencies.timeoutMs ?? WIDGET_PROXY_TIMEOUT_MS);
-      const signal = AbortSignal.any([c.req.raw.signal, timeout]);
-      const appId = c.req.param("appId");
-      const widgetId = c.req.param("widgetId");
-      const requestId = normalizeInvocationRequestId(c.req.header("x-request-id"));
-      let phase: "registry" | "signing" | "provider" | "response" = "registry";
-      const reject = (reason: WidgetRejectionReason, message: string, status: 502 | 504, upstreamStatus?: number): Response => {
-        log.warn("Widget proxy rejected response", {
-          appId: appId.slice(0, 80),
-          widgetId: widgetId.slice(0, 100),
-          phase,
-          reason,
-          ...(upstreamStatus === undefined ? {} : { upstreamStatus }),
+  return (
+    new Hono<AuthContext>()
+      .use(dependencies.authenticate ?? auth.requireRole("authenticated"))
+      .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.
+       */
+      .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[];
+        try {
+          const keys = new Set<string>();
+          widgets = (await waitWithin(registry(), setup)).filter((widget) => {
+            const key = widgetKey(widget.appId, widget.widgetId);
+            if (keys.has(key) || (requested.size > 0 && !requested.has(key))) return false;
+            keys.add(key);
+            return true;
+          });
+        } catch {
+          log.warn("Widget registry unavailable", { reason: setup.aborted ? "deadline_exceeded" : "operation_failed" });
+          return c.json({ message: "Widget registry is currently unavailable" }, 503);
+        }
+
+        const streamDeadline = AbortSignal.timeout(WIDGET_STREAM_DEADLINE_MS);
+        // A client that stops reading, such as a browser leaving the dashboard, ends every widget it still waits for.
+        const streamCancelled = new AbortController();
+        const fanoutSignal = AbortSignal.any([c.req.raw.signal, streamDeadline, streamCancelled.signal]);
+        // One signing guard for the whole dashboard, not one Postgres check per widget.
+        let tokens: PromiseSettledResult<Awaited<ReturnType<typeof signInvocationToken>>>[] = [];
+        try {
+          if (widgets.length > 0) {
+            const signing = AbortSignal.any([fanoutSignal, AbortSignal.timeout(timeoutMs)]);
+            tokens = await waitWithin(
+              withActiveSigner(
+                "invocation",
+                (signer) =>
+                  Promise.all(startBounded(widgets, WIDGET_CONCURRENCY, async (widget) => sign(c, widget, requestId, signer), signing)),
+                { signal: signing, timeoutMs },
+              ),
+              signing,
+            );
+          }
+        } catch {
+          log.warn("Widget invocation authority unavailable", { reason: fanoutSignal.aborted ? "deadline_exceeded" : "operation_failed" });
+          return c.json({ message: "Widget invocation authority is currently unavailable" }, 503);
+        }
+
+        const fanoutStarted = performance.now();
+        const settled = startBounded(
+          widgets,
+          WIDGET_CONCURRENCY,
+          async (widget, index): Promise<WidgetStreamLine> => {
+            const key = widgetKey(widget.appId, widget.widgetId);
+            const started = performance.now();
+            const elapsed = () => Math.round(performance.now() - started);
+            const token = tokens[index];
+            if (token?.status !== "fulfilled") {
+              logRejection(widget, "signing", "operation_failed");
+              return { type: "widget", key, status: "error", ms: elapsed() };
+            }
+            const timeout = AbortSignal.timeout(timeoutMs);
+            const outcome = await callProvider({
+              c,
+              widget,
+              token: token.value.token,
+              requestId,
+              signal: AbortSignal.any([fanoutSignal, timeout]),
+              timeout,
+              fetch: fetchWidget,
+            });
+            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.
+            if ("reason" in outcome && !fanoutSignal.aborted) logRejection(widget, outcome.phase, outcome.reason, outcome.upstreamStatus);
+            return { type: "widget", key, status: outcome.status, ms: elapsed() };
+          },
+          fanoutSignal,
+        );
+
+        return ndjsonStream<WidgetStreamLine>({
+          first: { type: "start", widgets: widgets.map((widget) => widgetKey(widget.appId, widget.widgetId)) },
+          pending: settled.map((pending, index) =>
+            pending.then((result): WidgetStreamLine => {
+              if (result.status === "fulfilled") return result.value;
+              // Only the stream's own deadline or the browser leaving settles a widget this way. Leaving is not a
+              // failure of the widget, so only the deadline is logged.
+              const widget = widgets[index]!;
+              const status = streamDeadline.aborted ? "timeout" : "error";
+              if (streamDeadline.aborted) logRejection(widget, "provider", "deadline_exceeded");
+              return {
+                type: "widget",
+                key: widgetKey(widget.appId, widget.widgetId),
+                status,
+                ms: Math.round(performance.now() - fanoutStarted),
+              };
+            }),
+          ),
+          last: (lines) => ({
+            type: "done",
+            status: lines.some((line) => line.type === "widget" && (line.status === "timeout" || line.status === "error"))
+              ? "partial"
+              : "complete",
+          }),
+          onCancel: () => streamCancelled.abort(),
         });
-        return jsonError(message, status);
-      };
-      try {
-        const widget = (await waitWithin(registry(), signal)).find((entry) => entry.appId === appId && entry.widgetId === widgetId);
-        if (!widget) return c.json({ message: "Widget not found" }, 404);
+      })
+      .get("/widgets/v1/:appId/:widgetId", async (c) => {
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const signal = AbortSignal.any([c.req.raw.signal, timeout]);
+        const appId = c.req.param("appId");
+        const widgetId = c.req.param("widgetId");
+        const requestId = normalizeInvocationRequestId(c.req.header("x-request-id"));
+        let phase: WidgetPhase = "registry";
+        try {
+          const widget = (await waitWithin(registry(), signal)).find((entry) => entry.appId === appId && entry.widgetId === widgetId);
+          if (!widget) return c.json({ message: "Widget not found" }, 404);
 
-        phase = "signing";
-        const headers = await (async () => {
+          phase = "signing";
           const signed = await waitWithin(
-            (dependencies.withActiveSigner ?? withActiveIdentitySigner)(
-              "invocation",
-              (signer) =>
-                (dependencies.signInvocation ?? signInvocationToken)({
-                  targetAppId: widget.appId,
-                  callingAppId: "core",
-                  operation: widgetInvocationOperation(widget.widgetId),
-                  schemaHash: null,
-                  authority: invocationAuthorityFromRequest(auth.getAuthority(c)),
-                  requestId,
-                  signer,
-                  issuer: signer.issuer,
-                }),
-              { signal, timeoutMs: dependencies.timeoutMs ?? WIDGET_PROXY_TIMEOUT_MS },
-            ),
+            withActiveSigner("invocation", (signer) => sign(c, widget, requestId, signer), { signal, timeoutMs }),
             signal,
           );
-          return new Headers({ authorization: `Bearer ${signed.token}` });
-        })();
 
-        if (requestId) headers.set("x-request-id", requestId);
-        for (const name of ["traceparent", "tracestate"] as const) {
-          const value = c.req.header(name);
-          if (value) headers.set(name, value);
+          phase = "provider";
+          const outcome = await callProvider({ c, widget, 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" } });
+          logRejection(widget, outcome.phase, outcome.reason, outcome.upstreamStatus);
+          if (outcome.status === "timeout") return Response.json({ message: "Widget deadline exceeded" }, { status: 504 });
+          const message =
+            outcome.reason === "invalid_schema"
+              ? "Widget returned an invalid response"
+              : outcome.reason === "too_large" || outcome.reason === "invalid_json"
+                ? "Widget returned invalid or oversized JSON"
+                : "Widget is unavailable";
+          return Response.json({ message }, { status: 502 });
+        } catch (error) {
+          const isTimeout = timeout.aborted || (error instanceof Error && error.name === "TimeoutError");
+          const reason: WidgetRejectionReason = isTimeout ? "deadline_exceeded" : signal.aborted ? "request_cancelled" : "operation_failed";
+          logRejection({ appId, widgetId }, phase, reason);
+          return isTimeout
+            ? Response.json({ message: "Widget deadline exceeded" }, { status: 504 })
+            : Response.json({ message: "Widget is unavailable" }, { status: 502 });
         }
-        const locale = preferredLocale(c.req.raw.headers);
-        if (locale) headers.set(LOCALE_HEADER, locale);
-        headers.set("x-cloud-invocation-operation", widgetInvocationOperation(widget.widgetId));
-
-        const targetUrl = new URL(`/api/_internal/widgets/v1/${encodeURIComponent(widget.widgetId)}`, widget.url);
-        phase = "provider";
-        signal.throwIfAborted();
-        const response = await fetchWidget(targetUrl, { headers, signal });
-        if (response.status === 204 || response.status === 403) {
-          await response.body?.cancel();
-          return new Response(null, { status: response.status, headers: { "content-type": "application/json" } });
-        }
-        if (!response.ok) {
-          await response.body?.cancel();
-          return response.status === 504
-            ? reject("upstream_timeout", "Widget deadline exceeded", 504, response.status)
-            : reject("upstream_status", "Widget is unavailable", 502, response.status);
-        }
-        phase = "response";
-        const body = await readBoundedJson(response, WIDGET_MAX_RESPONSE_BYTES);
-        signal.throwIfAborted();
-        if (!body.ok) return reject(body.reason, "Widget returned invalid or oversized JSON", 502);
-        const parsed = WidgetResponseSchema.safeParse(body.data);
-        if (!parsed.success) return reject("invalid_schema", "Widget returned an invalid response", 502);
-        return Response.json(parsed.data, { headers: { "content-type": "application/json" } });
-      } catch (error) {
-        const isTimeout = timeout.aborted || (error instanceof Error && error.name === "TimeoutError");
-        return isTimeout
-          ? reject("deadline_exceeded", "Widget deadline exceeded", 504)
-          : reject(signal.aborted ? "request_cancelled" : "operation_failed", "Widget is unavailable", 502);
-      }
-    });
+      })
+  );
 };

package/src/browser/CloudResourceSearch.browser-harness.tsx

@@ -1,4 +1,4 @@
-import { createGlobalSearchHost } from "../ssr/GlobalSearchDialog";
+import { createGlobalSearchHost } from "../ssr/global-search-host";
 import { openCloudResourcePicker } from "./resource-picker";
 
 /**

package/src/browser/ndjson.ts

@@ -0,0 +1,34 @@
+/** Media type Core streams per-app results in; kept local so browser bundles do not load server schemas. */
+export const NDJSON_CONTENT_TYPE = "application/x-ndjson";
+
+/**
+ * Hands over each line of an NDJSON response as it arrives, until a line of type `done`. Rejects when the stream ends
+ * before that line, so the caller can tell a finished stream from one that broke off.
+ */
+export const readNdjsonLines = async <Line extends { type: string }>(
+  response: Response,
+  onLine: (line: Line) => void,
+  name: string,
+): Promise<void> => {
+  if (!response.body) throw new Error(`${name} returned no body`);
+  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+  let buffer = "";
+  let closed = false;
+  while (!closed) {
+    const chunk = await reader.read();
+    if (chunk.done) break;
+    buffer += chunk.value;
+    let end = buffer.indexOf("\n");
+    while (end >= 0) {
+      const text = buffer.slice(0, end).trim();
+      buffer = buffer.slice(end + 1);
+      if (text) {
+        const line: Line = JSON.parse(text);
+        onLine(line);
+        if (line.type === "done") closed = true;
+      }
+      end = buffer.indexOf("\n");
+    }
+  }
+  if (!closed) throw new Error(`${name} stream ended early`);
+};

package/src/browser/reload.ts

@@ -1,3 +1,6 @@
+import { i18n } from "@k2b/stdlib";
+import { type ToastHandle, toast } from "@k2b/ui";
+
 /**
  * Default window in which a second automatic reload for the same key is
  * suppressed. A page load, hydration, and the first live subscription finish
@@ -32,3 +35,46 @@ export const reloadOnce = (key: string, options: { windowMs?: number } = {}): bo
   window.location.reload();
   return true;
 };
+
+const reloadMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      codeUnavailable: "Part of this page could not load. Reload the page and try again.",
+      reload: "Reload",
+    },
+    de: {
+      codeUnavailable: "Ein Teil dieser Seite konnte nicht geladen werden. Lade die Seite neu und versuche es erneut.",
+      reload: "Neu laden",
+    },
+  },
+});
+
+/** One notice at a time: every failed load in the tab has the same remedy. */
+let codeUnavailable: ToastHandle | undefined;
+
+/**
+ * Loads code that one action needs when the action runs, for example
+ * `importOnDemand(() => import("./SettingsDialog"))`, so the page does not
+ * download it up front.
+ *
+ * Resolves `undefined` when the code cannot load. A release replaces the
+ * page's code files, so a page that was open before it cannot load code it
+ * has not loaded yet; a dropped connection fails the same way. The helper
+ * then shows a toast that offers a reload, and the caller only ends its
+ * action.
+ */
+export const importOnDemand = async <T>(load: () => Promise<T>): Promise<T | undefined> => {
+  try {
+    return await load();
+  } catch (error) {
+    console.warn("[cloud] Could not load code on demand", error);
+    const t = reloadMessages.resolve([document.documentElement.lang || "en"]).t;
+    codeUnavailable?.dismiss();
+    codeUnavailable = toast.error(t.codeUnavailable, {
+      duration: 0,
+      action: { label: t.reload, onClick: () => window.location.reload() },
+    });
+    return undefined;
+  }
+};

package/src/browser/search-stream.ts

@@ -1,8 +1,6 @@
 import type { SearchApp, SearchItem, SearchProviderStatus, SearchResponse, SearchStreamLine } from "../api/search/schemas";
 import { LOCALE_HEADER } from "../shared/locale";
-
-/** Kept local so the browser bundle does not load the server-side search schemas. */
-const STREAM_CONTENT_TYPE = "application/x-ndjson";
+import { NDJSON_CONTENT_TYPE, readNdjsonLines } from "./ndjson";
 
 export type SearchAppStatus = SearchProviderStatus | "searching";
 
@@ -119,33 +117,13 @@ export const streamCloudResourceSearch = async (
 ): Promise<void> => {
   const response = await fetch(url, {
     signal: options.signal,
-    headers: { accept: STREAM_CONTENT_TYPE, [LOCALE_HEADER]: options.locale },
+    headers: { accept: NDJSON_CONTENT_TYPE, [LOCALE_HEADER]: options.locale },
   });
   if (!response.ok) throw new Error(`Search failed with ${response.status}`);
-  if (!response.headers.get("content-type")?.startsWith(STREAM_CONTENT_TYPE)) {
+  if (!response.headers.get("content-type")?.startsWith(NDJSON_CONTENT_TYPE)) {
     const body: SearchResponse = await response.json();
     for (const line of linesFromResponse(body)) options.onLine(line);
     return;
   }
-  if (!response.body) throw new Error("Search returned no body");
-  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
-  let buffer = "";
-  let closed = false;
-  while (!closed) {
-    const chunk = await reader.read();
-    if (chunk.done) break;
-    buffer += chunk.value;
-    let end = buffer.indexOf("\n");
-    while (end >= 0) {
-      const text = buffer.slice(0, end).trim();
-      buffer = buffer.slice(end + 1);
-      if (text) {
-        const line: SearchStreamLine = JSON.parse(text);
-        options.onLine(line);
-        if (line.type === "done") closed = true;
-      }
-      end = buffer.indexOf("\n");
-    }
-  }
-  if (!closed) throw new Error("Search stream ended early");
+  await readNdjsonLines(response, options.onLine, "Search");
 };

package/src/browser/widgets.ts

@@ -0,0 +1,28 @@
+import type { 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";
+
+/**
+ * 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.
+ */
+export const streamWidgets = async (options: {
+  keys?: readonly string[];
+  signal: AbortSignal;
+  locale: string;
+  onLine: (line: WidgetStreamLine) => void;
+}): Promise<void> => {
+  const query = new URLSearchParams();
+  for (const key of options.keys ?? []) query.append("widget", key);
+  const search = query.toString();
+  const response = await fetch(`/api/widgets/v1${search ? `?${search}` : ""}`, {
+    signal: options.signal,
+    headers: { accept: NDJSON_CONTENT_TYPE, [LOCALE_HEADER]: options.locale },
+  });
+  if (!response.ok) throw new Error(`Widgets failed with ${response.status}`);
+  await readNdjsonLines(response, options.onLine, "Widgets");
+};

package/src/capabilities/server.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import { resolveCapabilityActionWording, resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import type { CapabilityActionWording } from "../_internal/capability-sentences";
 import { getApp, getCapability } from "../_internal/registry";
 import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabilities";
 import { env } from "../config/env";
@@ -14,7 +15,7 @@ import { get } from "../services/settings";
 import { resolveAppPresentation } from "../shared/app-presentation";
 import { publicCloudOrigin } from "../shared/app-url";
 import { capabilityMessages } from "../shared/capability-messages";
-import { LOCALE_HEADER } from "../shared/locale";
+import { DEFAULT_LOCALE, LOCALE_HEADER } from "../shared/locale";
 import { readCapabilityResponse } from "./response";
 import { combineCapabilitySignals } from "./signals";
 import type {
@@ -26,6 +27,7 @@ import type {
   CapabilityReviewClientResult,
 } from "./types";
 
+export type { CapabilityActionWording } from "../_internal/capability-sentences";
 export type {
   CapabilityCatalogApp,
   CapabilityCatalogAppClientResult,
@@ -225,6 +227,22 @@ export const getCapabilityCatalogApp = async (appId: string, locale?: string): P
   }
 };
 
+/**
+ * How people read calls of one Action in a locale, from the live registry like the Assistant's own calls: its title,
+ * the app's sentences, and the labelled fields of the generic sentence. Pass `sentences` and `fields` to the chat's
+ * approval card, so an approval a script or app asks for reads like the same call in a chat. `null` for an unknown
+ * app or Action.
+ */
+export const getCapabilityActionWording = async (
+  appId: string,
+  localId: string,
+  locale?: string,
+): Promise<CapabilityActionWording | null> => {
+  const capability = await getCapability(appId);
+  const action = capability?.manifest.actions.find((candidate) => candidate.localId === localId);
+  return capability && action ? resolveCapabilityActionWording(action, capability.presentation, locale ?? DEFAULT_LOCALE) : null;
+};
+
 export const reviewCapabilityAction = async <TInput = unknown>(
   invocation: Omit<CapabilityInvocation<TInput>, "kind" | "idempotencyKey">,
   caller: CapabilityCaller,