@k2b/cloud 0.33.0 → 0.35.0

package/src/ai/system-prompt.ts

@@ -171,6 +171,7 @@ export const composeAiSystemPrompt = (input: AiSystemPromptInput): string => {
       ? [
           "# Local client",
           'This turn comes from a local client. Where this section describes what the user sees, it replaces "What the user sees" above; it cannot override the other platform rules.',
+          "Offer the supplied link for every Cloud resource you create, change, or name, because cld and editors show these links as full Cloud addresses.",
           `Client: ${input.localClient.client.kind === "cli" ? "terminal (cld)" : `editor via ACP${input.localClient.client.name ? ` (${input.localClient.client.name})` : ""}`}`,
           input.localClient.cloudUrl.trim() ? `Cloud: ${withoutTrailingSlashes(input.localClient.cloudUrl.trim())}` : undefined,
           `Workspace: ${input.localClient.client.cwd}`,
@@ -244,8 +245,8 @@ export const composeAiSystemPrompt = (input: AiSystemPromptInput): string => {
     ].join("\n"),
     [
       "# Cloud resource links",
-      "When the answer mentions a Cloud resource and its result or supplied context includes an open or edit href, make the resource's human-readable title a Markdown link using that exact href. Use the title exactly as supplied, even when answering in another language. Apply this to every mentioned resource, including list items and headings. Prefer open over edit. Without a supplied href, use plain text. Never construct a Cloud URL.",
-      "Example: [Urgent invoice review 001](/app/mail/5guDsC?conversation=nTf34n) — payment deadline approaching.",
+      "Cloud adds an href to resource refs it can open. When the answer mentions a Cloud resource, use its ref's href or the result's open or edit link to make the resource's human-readable title a Markdown link using that exact href. Use the title exactly as supplied, even when answering in another language. Apply this to every mentioned resource, including list items and headings. Prefer open over edit. Without a supplied href, use plain text. Never construct a Cloud URL.",
+      "Example: [Urgent invoice review 001](/open/mail.draft/~AbC123) — payment deadline approaching.",
     ].join("\n"),
   ];
 

package/src/api/index.ts

@@ -121,3 +121,5 @@ export {
   createMcpRoutes,
   publicCloudOrigin,
 } from "./mcp";
+
+export { resolveCloudResourceHref } from "./resource-links";

package/src/api/mcp.ts

@@ -17,6 +17,7 @@ import { z } from "zod";
 import { readBoundedJson } from "../_internal/bounded-json";
 import { HELP_SEARCH_MAX_LIMIT, helpResourceUri, parseHelpResourceUri, readHelpArticle } from "../_internal/help-catalog";
 import { getCapability, listApps } from "../_internal/registry";
+import { addCloudResourceHrefs } from "../ai/resource-refs";
 import { capabilityValueMeta, recordCapabilityExecution } from "../capabilities/executions";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
@@ -26,9 +27,11 @@ import {
   type CapabilityActionManifest,
   type CapabilityQueryManifest,
   CapabilitySemanticLinkSchema,
-  CloudResourceRefSchema,
+  type CloudResourceRef,
   capabilityResultJsonSchema,
+  capabilityResultSchema,
   cloudResourceRefAppId,
+  LinkedCloudResourceReferenceSchema,
   resolveCapabilityResourceReader,
 } from "../contracts/capabilities";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
@@ -121,7 +124,7 @@ const platformTools: Tool[] = [
     title: "Read Cloud resource",
     description:
       "Read one Cloud resource through its current canonical reader. Pass a typed ref returned by search, list, lookup, or another capability unchanged; never guess a reader name or substitute an id from another resource type.",
-    inputSchema: structuredClone(z.toJSONSchema(CloudResourceRefSchema)) as Tool["inputSchema"],
+    inputSchema: structuredClone(z.toJSONSchema(LinkedCloudResourceReferenceSchema)) as Tool["inputSchema"],
     annotations: { title: "Read Cloud resource", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { "cloud/kind": "resource-read" },
   },
@@ -206,7 +209,7 @@ const projectTool = (
       title: `${app.appName}: ${operation.title}`,
       description: operation.description,
       inputSchema: action ? actionInputSchema(action) : cloneObjectSchema(operation.inputSchema),
-      outputSchema: cloneObjectSchema(capabilityResultJsonSchema(operation.dataSchema)),
+      outputSchema: cloneObjectSchema(capabilityResultJsonSchema(operation.dataSchema, { consumer: true })),
       annotations: {
         title: operation.title,
         readOnlyHint: !isAction,
@@ -300,7 +303,7 @@ const findCapabilityTool = async (
 };
 
 const findResourceReaderTool = async (
-  ref: z.infer<typeof CloudResourceRefSchema>,
+  ref: CloudResourceRef,
   lookup: (appId: string) => Promise<CapabilityRegistryEntry | null>,
   registry: () => Promise<AppRegistryEntry[]>,
 ): Promise<CapabilityTool | null> => {
@@ -333,15 +336,20 @@ const responseTooLargeToolResult = (): CallToolResult => {
   return { isError: true, structuredContent: error, content: [{ type: "text", text: JSON.stringify(error) }] };
 };
 
+const toolResult = (body: Record<string, unknown>, isError: boolean): CallToolResult => ({
+  ...(isError ? { isError: true } : {}),
+  structuredContent: body,
+  content: [{ type: "text", text: JSON.stringify(body) }],
+});
+
+const fitsToolResult = (result: CallToolResult): boolean =>
+  new TextEncoder().encode(JSON.stringify(result)).byteLength <= CAPABILITY_MAX_RESULT_BYTES;
+
 const ensureBoundedToolResult = (result: CallToolResult): CallToolResult =>
-  new TextEncoder().encode(JSON.stringify(result)).byteLength > CAPABILITY_MAX_RESULT_BYTES ? responseTooLargeToolResult() : result;
+  fitsToolResult(result) ? result : responseTooLargeToolResult();
 
 const boundedToolResult = (body: Record<string, unknown>, isError: boolean): CallToolResult =>
-  ensureBoundedToolResult({
-    ...(isError ? { isError: true } : {}),
-    structuredContent: body,
-    content: [{ type: "text", text: JSON.stringify(body) }],
-  });
+  ensureBoundedToolResult(toolResult(body, isError));
 
 const semanticResourceLinks = (body: Record<string, unknown>, origin: string): CallToolResult["content"] => {
   const found = new Map<string, z.infer<typeof CapabilitySemanticLinkSchema>>();
@@ -573,14 +581,14 @@ const createMcpServer = (
     let args: Record<string, unknown>;
     try {
       if (message.params.name === RESOURCE_READ_TOOL) {
-        const parsed = CloudResourceRefSchema.safeParse(message.params.arguments);
+        const parsed = LinkedCloudResourceReferenceSchema.safeParse(message.params.arguments);
         if (!parsed.success) {
           const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ");
           return validationToolError(
             `cloud__resource__read requires one exact typed ref returned by a current Cloud capability (${issues})`,
           );
         }
-        selected = await findResourceReaderTool(parsed.data, capabilityLookup, registry);
+        selected = await findResourceReaderTool({ type: parsed.data.type, id: parsed.data.id }, capabilityLookup, registry);
         args = { id: parsed.data.id };
         if (!selected) {
           return boundedToolResult(
@@ -646,12 +654,35 @@ const createMcpServer = (
       authority,
       dependencies,
     });
-    const body = await parseResponse(response);
-    const result = boundedToolResult(body, !response.ok);
-    if (response.ok) {
-      result.content.push(...semanticResourceLinks(body, publicCloudOrigin(await (dependencies.getAppUrl ?? defaultAppUrl)())));
+    const providerBody = await parseResponse(response);
+    let body = providerBody;
+    const origin = response.ok ? publicCloudOrigin(await (dependencies.getAppUrl ?? defaultAppUrl)()) : undefined;
+    if (origin) {
+      const parsed = capabilityResultSchema(z.unknown()).safeParse(body);
+      const appIds = new Set(parsed.success ? parsed.data.refs?.map(cloudResourceRefAppId) : []);
+      const apps = appIds.size ? await registry().catch(() => []) : [];
+      const capabilities = await Promise.all(
+        apps
+          .filter((app) => appIds.has(app.id) && app.capabilities?.protocolVersion === CAPABILITY_PROTOCOL_VERSION)
+          .map(async (app) => {
+            const entry = await capabilityLookup(app.id).catch(() => null);
+            return entry?.appId === app.id && entry.manifest.manifestHash === app.capabilities?.manifestHash ? entry : null;
+          }),
+      );
+      body = addCloudResourceHrefs(
+        body,
+        capabilities.filter((entry) => entry !== null),
+        origin,
+      );
     }
-    return ensureBoundedToolResult(result);
+    const resultFor = (value: Record<string, unknown>): CallToolResult => {
+      const result = toolResult(value, !response.ok);
+      if (origin) result.content.push(...semanticResourceLinks(value, origin));
+      return result;
+    };
+    // Added hrefs are optional: they never turn a result that fits into RESPONSE_TOO_LARGE.
+    const result = resultFor(body);
+    return ensureBoundedToolResult(fitsToolResult(result) || body === providerBody ? result : resultFor(providerBody));
   });
 
   return server;

package/src/api/pwa.ts

@@ -134,11 +134,16 @@ export const createPwaRoutes = (options: PwaRouteOptions = {}) => {
       describeRoute({
         tags,
         summary: "Read a pairing",
-        description: "Only for the web session that started it. Never returns the code.",
+        description:
+          "Only for the web session that started it. Never returns the code. A pending read is held for up to one poll interval and answers as soon as the phone claims the link.",
         responses: { 200: jsonResponse(PwaPairingStatusSchema, "Pairing state") },
       }),
       v("param", IdParamSchema, pwaInvalidRequest),
-      async (c) => c.json(await service.inspectPairing(await webActor(c), c.req.valid("param").id)),
+      async (c) => {
+        const actor = await webActor(c);
+        const hold = { ms: PWA_LIMITS.pollSeconds * 1000, signal: c.req.raw.signal };
+        return c.json(await service.inspectPairing(actor, c.req.valid("param").id, hold));
+      },
     )
     .post(
       "/pairings/:id/confirm",

package/src/api/resource-links.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { getCapability } from "../_internal/registry";
+import {
+  CapabilitySemanticLinkSchema,
+  type CloudResourceRef,
+  CloudResourceRefSchema,
+  capabilityResultSchema,
+  cloudResourceRefAppId,
+  resolveCapabilityResourceReader,
+} from "../contracts/capabilities";
+import type { RequestAuthority } from "../server";
+import { dispatchCapability } from "./capabilities";
+
+export const resolveCloudResourceHref = async (
+  params: { ref: CloudResourceRef; request: Request; authority: RequestAuthority; locale?: string },
+  dependencies: { getCapability?: typeof getCapability; dispatch?: typeof dispatchCapability } = {},
+): Promise<string | null> => {
+  const parsed = CloudResourceRefSchema.safeParse(params.ref);
+  if (!parsed.success) return null;
+  const ref = parsed.data;
+  const appId = cloudResourceRefAppId(ref);
+  const app = await (dependencies.getCapability ?? getCapability)(appId);
+  if (!app || app.appId !== appId) return null;
+  const reader = resolveCapabilityResourceReader(app.manifest, ref);
+  if (!reader) return null;
+  const response = await (dependencies.dispatch ?? dispatchCapability)({
+    request: params.request,
+    authority: params.authority,
+    locale: params.locale,
+    origin: "http",
+    kind: "queries",
+    appId,
+    capabilityId: reader.localId,
+    input: { id: ref.id },
+  });
+  if (!response.ok) return null;
+  const result = capabilityResultSchema(z.unknown(), { consumer: true }).safeParse(await response.json());
+  if (!result.success) return null;
+  const link = CapabilitySemanticLinkSchema.safeParse(
+    result.data.links?.find((link) => link.rel === "open") ?? result.data.links?.find((link) => link.rel === "edit"),
+  );
+  return link.success ? link.data.href : null;
+};

package/src/api/widgets.ts

@@ -1,18 +1,26 @@
 import { type Context, Hono, type MiddlewareHandler } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { z } from "zod";
 import { readBoundedJson } from "../_internal/bounded-json";
 import { type DashboardWidget, listWidgets } from "../_internal/registry";
+import { parseWidgetSettings } from "../_internal/widget-settings";
 import {
   type DashboardWidgetSize,
   fitWidgetSize,
   isDashboardWidgetSize,
+  WIDGET_KEY_MAX_LENGTH,
   WIDGET_MAX_RESPONSE_BYTES,
+  WIDGET_REQUEST_MAX_BYTES,
+  WIDGET_REQUEST_MAX_ENTRIES,
+  WIDGET_REQUEST_MAX_ID_LENGTH,
+  WIDGET_SETTINGS_MAX_FIELDS,
   type WidgetResponse,
   WidgetResponseSchema,
   type WidgetStreamLine,
   widgetKey,
 } from "../contracts/widgets";
 import { type AuthContext, auth, preferredLocale, rejectReservedWorkloadCredential } from "../server";
-import { WIDGET_SIZE_PARAM } from "../server/widget-request";
+import { WIDGET_SETTINGS_PARAM, WIDGET_SETTINGS_PARAM_MAX_LENGTH, 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";
@@ -49,6 +57,7 @@ type WidgetRejectionReason =
   | "upstream_timeout"
   | "upstream_status"
   | "too_large"
+  | "settings_too_large"
   | "invalid_json"
   | "invalid_schema"
   | "deadline_exceeded"
@@ -84,6 +93,7 @@ const callProvider = async (options: {
   widget: DashboardWidget;
   /** What the browser asked for, fitted to the widget's declared sizes before it reaches the app. */
   size: unknown;
+  settings?: unknown;
   token: string;
   requestId: string | undefined;
   signal: AbortSignal;
@@ -105,6 +115,12 @@ const callProvider = async (options: {
 
     const targetUrl = new URL(`/api/_internal/widgets/v1/${encodeURIComponent(widget.widgetId)}`, widget.url);
     targetUrl.searchParams.set(WIDGET_SIZE_PARAM, fitWidgetSize(options.size, widget));
+    if (widget.settings) {
+      const json = JSON.stringify(parseWidgetSettings(widget.settings, options.settings));
+      const encodedLength = new URLSearchParams([[WIDGET_SETTINGS_PARAM, json]]).toString().length - WIDGET_SETTINGS_PARAM.length - 1;
+      if (encodedLength > WIDGET_SETTINGS_PARAM_MAX_LENGTH) return { status: "error", phase: "provider", reason: "settings_too_large" };
+      targetUrl.searchParams.set(WIDGET_SETTINGS_PARAM, json);
+    }
     signal.throwIfAborted();
     const response = await options.fetch(targetUrl, { headers, signal });
     if (response.status === 204 || response.status === 403) {
@@ -143,6 +159,30 @@ const parseRequestedWidget = (value: string, declared: ReadonlySet<string>): [st
   return isDashboardWidgetSize(size) && declared.has(value.slice(0, at)) ? [value.slice(0, at), size] : [value, undefined];
 };
 
+const WidgetEntriesSchema = z
+  .object({
+    widgets: z
+      .array(
+        z
+          .object({
+            id: z.string().min(1).max(WIDGET_REQUEST_MAX_ID_LENGTH),
+            key: z.string().min(1).max(WIDGET_KEY_MAX_LENGTH),
+            size: z.string().optional(),
+            settings: z
+              .record(z.string(), z.unknown())
+              .refine((values) => Object.keys(values).length <= WIDGET_SETTINGS_MAX_FIELDS)
+              .optional(),
+          })
+          .strict(),
+      )
+      .min(1)
+      .max(WIDGET_REQUEST_MAX_ENTRIES)
+      .refine((entries) => new Set(entries.map((entry) => entry.id)).size === entries.length, "Widget entry ids must be unique"),
+  })
+  .strict();
+
+type WidgetEntry = { widget: DashboardWidget; id?: string; size?: string; settings?: unknown };
+
 export const createWidgetRoutes = (dependencies: WidgetRouteDependencies = {}) => {
   const registry = dependencies.listWidgets ?? listWidgets;
   const fetchWidget = dependencies.fetch ?? globalThis.fetch;
@@ -167,6 +207,96 @@ export const createWidgetRoutes = (dependencies: WidgetRouteDependencies = {}) =
       issuer: signer.issuer,
     });
 
+  const stream = async (c: Context<AuthContext>, entries: WidgetEntry[], requestId: string | undefined) => {
+    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 (entries.length > 0) {
+        const signing = AbortSignal.any([fanoutSignal, AbortSignal.timeout(timeoutMs)]);
+        tokens = await waitWithin(
+          withActiveSigner(
+            "invocation",
+            (signer) =>
+              Promise.all(startBounded(entries, WIDGET_CONCURRENCY, async (entry) => sign(c, entry.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(
+      entries,
+      WIDGET_CONCURRENCY,
+      async (entry, index): Promise<WidgetStreamLine> => {
+        const { widget } = entry;
+        const identity = entry.id === undefined ? {} : { id: entry.id };
+        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", ...identity, 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,
+          size: entry.size,
+          settings: entry.settings,
+        });
+        if (outcome.status === "ok") return { type: "widget", ...identity, 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", ...identity, key, status: outcome.status, ms: elapsed() };
+      },
+      fanoutSignal,
+    );
+
+    return ndjsonStream<WidgetStreamLine>({
+      first: { type: "start", widgets: entries.map((entry) => entry.id ?? widgetKey(entry.widget.appId, entry.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 entry = entries[index]!;
+          const { widget } = entry;
+          const status = streamDeadline.aborted ? "timeout" : "error";
+          if (streamDeadline.aborted) logRejection(widget, "provider", "deadline_exceeded");
+          return {
+            type: "widget",
+            ...(entry.id === undefined ? {} : { id: entry.id }),
+            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 (
     new Hono<AuthContext>()
       .use(dependencies.authenticate ?? auth.requireRole("authenticated"))
@@ -197,89 +327,40 @@ export const createWidgetRoutes = (dependencies: WidgetRouteDependencies = {}) =
           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,
-              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.
-            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 stream(
+          c,
+          widgets.map((widget) => ({ widget, size: requested.get(widgetKey(widget.appId, widget.widgetId)) })),
+          requestId,
         );
-
-        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(),
-        });
       })
+      .post(
+        "/widgets/v1",
+        bodyLimit({ maxSize: WIDGET_REQUEST_MAX_BYTES, onError: (c) => c.json({ message: "Widget request is too large" }, 400) }),
+        async (c) => {
+          let raw: unknown;
+          try {
+            raw = await c.req.json();
+          } catch {
+            return c.json({ message: "Invalid widget request JSON" }, 400);
+          }
+          const parsed = WidgetEntriesSchema.safeParse(raw);
+          if (!parsed.success) return c.json({ message: "Invalid widget request" }, 400);
+          const setup = AbortSignal.any([c.req.raw.signal, AbortSignal.timeout(timeoutMs)]);
+          let declared: DashboardWidget[];
+          try {
+            declared = await waitWithin(registry(), setup);
+          } catch {
+            log.warn("Widget registry unavailable", { reason: setup.aborted ? "deadline_exceeded" : "operation_failed" });
+            return c.json({ message: "Widget registry is currently unavailable" }, 503);
+          }
+          const byKey = new Map(declared.map((widget) => [widgetKey(widget.appId, widget.widgetId), widget]));
+          const entries = parsed.data.widgets.flatMap((entry) => {
+            const widget = byKey.get(entry.key);
+            return widget ? [{ ...entry, widget }] : [];
+          });
+          return stream(c, entries, normalizeInvocationRequestId(c.req.header("x-request-id")));
+        },
+      )
       .get("/widgets/v1/:appId/:widgetId", async (c) => {
         const timeout = AbortSignal.timeout(timeoutMs);
         const signal = AbortSignal.any([c.req.raw.signal, timeout]);

package/src/browser/CloudResourceSearch.tsx

@@ -1,9 +1,8 @@
 import { timed } from "@k2b/stdlib/solid";
-import { announce, Button, IconButton, ScrollArea, useLocale } from "@k2b/ui";
+import { announce, Button, IconButton, Kbd, ScrollArea, useLocale } from "@k2b/ui";
 import { createEffect, createMemo, createSignal, createUniqueId, For, on, onCleanup, onMount, Show } from "solid-js";
 import type { SearchApp, SearchItem } from "../api/search/schemas";
 import type { CloudResourceRef } from "../contracts";
-import { shortcutLabel } from "./command-shortcuts";
 import { matchNavigationSearchItems, type NavigationSearchItem } from "./navigation-search";
 import { cloudResourceSearchUrl, filterCloudResourceSearchItems } from "./resource-search";
 import { commitTypedTags, matchingSearchTags, searchTags, tagAtCursor } from "./resource-search-input";
@@ -39,6 +38,7 @@ export type CloudResourceSearchProps = {
   navigationError?: string;
   placeholder?: string;
   requireReader?: boolean;
+  resourceType?: string;
   navigationItems?: readonly NavigationSearchItem[];
   searchResources?: boolean;
   excludeRefs?: readonly CloudResourceRef[];
@@ -668,9 +668,7 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
                             <span>{item.title}</span>
                             <small>{item.preview ?? item.appName}</small>
                           </span>
-                          <Show when={commandFor(item)?.shortcut}>
-                            {(shortcut) => <kbd class="shrink-0 text-xs text-dimmed">{shortcutLabel(shortcut())}</kbd>}
-                          </Show>
+                          <Show when={commandFor(item)?.shortcut}>{(shortcut) => <Kbd keys={shortcut()} />}</Show>
                           <Show when={props.selectionMode && selectedKey() === itemKey(item)}>
                             <i class="ti ti-check" aria-hidden="true" />
                           </Show>
@@ -792,7 +790,9 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
                     (!activeItem() || !commandFor(activeItem()!) || isLinkableCommand(commandFor(activeItem()!)!))
                   }
                 >
-                  <span>⌘/Ctrl ↵ {t().newTab}</span>
+                  <span>
+                    <Kbd keys="mod+enter" /> {t().newTab}
+                  </span>
                 </Show>
               </div>
             }

package/src/browser/command-shortcuts.ts

@@ -1,6 +1,7 @@
+import { keyboardPlatform } from "@k2b/ui";
 import { COMMANDS_CHANGED, type ContextAwareCommand, collectContextAwareCommands } from "./command-bridge";
 
-const isMac = () => typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform);
+const isMac = () => keyboardPlatform() === "apple";
 const modifiers = ["ctrl", "alt", "shift", "meta"] as const;
 type Combination = { key: string; ctrl: boolean; alt: boolean; shift: boolean; meta: boolean };
 
@@ -26,16 +27,6 @@ export const contextCommandsWithShortcuts = (): ContextAwareCommand[] => {
   }));
 };
 
-export const shortcutLabel = (shortcut: string): string => {
-  const combination = parse(shortcut);
-  if (!combination) return "";
-  const mac = isMac();
-  const names = { ctrl: mac ? "⌃" : "Ctrl", alt: mac ? "⌥" : "Alt", shift: mac ? "⇧" : "Shift", meta: mac ? "⌘" : "Meta" };
-  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 ? "" : "+");
-};
-
 const ARROWS = new Set(["arrowup", "arrowdown", "arrowleft", "arrowright"]);
 
 /**

package/src/browser/resource-picker.tsx

@@ -12,6 +12,7 @@ export type CloudResourcePickerOptions = {
   initialAppId?: string;
   excludeRefs?: readonly CloudResourceRef[];
   requireReader?: boolean;
+  resourceType?: string;
 };
 
 export const openCloudResourcePicker = (options: CloudResourcePickerOptions = {}): Promise<CloudResourcePickerItem | undefined> => {

package/src/browser/resource-search.ts

@@ -27,8 +27,13 @@ export const cloudResourceSearchUrl = (request: {
 
 export const filterCloudResourceSearchItems = (
   items: readonly SearchItem[],
-  options: { excludeRefs?: readonly CloudResourceRef[]; requireReader?: boolean },
+  options: { excludeRefs?: readonly CloudResourceRef[]; requireReader?: boolean; resourceType?: string },
 ): SearchItem[] => {
   const excluded = new Set((options.excludeRefs ?? []).map(refKey));
-  return items.filter((item) => (!options.requireReader || item.readable) && !excluded.has(refKey(item.ref)));
+  return items.filter(
+    (item) =>
+      (options.resourceType === undefined || item.ref.type === options.resourceType) &&
+      (!options.requireReader || item.readable) &&
+      !excluded.has(refKey(item.ref)),
+  );
 };