@k2b/cloud 0.33.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -106,8 +106,8 @@
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
-    "@k2b/ssr": "0.15.1",
-    "@k2b/ui": "0.24.0",
+    "@k2b/ssr": "0.16.0",
+    "@k2b/ui": "0.25.0",
     "@k2b/stdlib": "0.29.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",

package/src/_internal/app-presentation.ts

@@ -1,4 +1,4 @@
-import type { AppMeta, AppPresentationCatalog, AppPresentationTranslation, AppWidgetTranslation } from "../contracts/app";
+import type { AppMeta, AppPresentationCatalog, AppPresentationTranslation, AppWidgetTranslation, WidgetEndpoint } from "../contracts/app";
 import { WIDGET_DESCRIPTION_MAX_LENGTH, WIDGET_TITLE_MAX_LENGTH } from "../contracts/widgets";
 import { canonicalLocale } from "../shared/locale";
 
@@ -14,23 +14,53 @@ const text = (value: string, label: string, max = MAX_SHORT_TEXT): string => {
 
 const labels = (values: Readonly<Record<string, string>> | undefined, allowed: Set<string>, label: string, max = MAX_SHORT_TEXT) => {
   if (!values) return undefined;
-  const normalized: Record<string, string> = {};
-  for (const [key, value] of Object.entries(values)) {
-    if (!allowed.has(key)) throw new Error(`${label} contains unknown key ${JSON.stringify(key)}`);
-    normalized[key] = text(value, `${label}.${key}`, max);
-  }
-  return normalized;
+  return Object.fromEntries(
+    Object.entries(values).map(([key, value]) => {
+      if (!allowed.has(key)) throw new Error(`${label} contains unknown key ${JSON.stringify(key)}`);
+      return [key, text(value, `${label}.${key}`, max)];
+    }),
+  );
 };
 
 const widgetTexts = (
   values: Readonly<Record<string, AppWidgetTranslation>>,
-  allowed: Set<string>,
+  widgets: readonly WidgetEndpoint[],
   label: string,
 ): Record<string, AppWidgetTranslation> => {
   const normalized: Record<string, AppWidgetTranslation> = {};
   for (const [id, value] of Object.entries(values)) {
-    if (!allowed.has(id)) throw new Error(`${label} contains unknown key ${JSON.stringify(id)}`);
+    const widget = widgets.find((widget) => widget.id === id);
+    if (!widget) throw new Error(`${label} contains unknown key ${JSON.stringify(id)}`);
+    const settings: NonNullable<AppWidgetTranslation["settings"]> = Object.fromEntries(
+      Object.entries(value.settings ?? {}).map(([name, translation]) => {
+        const field = widget.settings?.[name];
+        const settingLabel = `${label}.${id}.settings.${name}`;
+        if (!field) throw new Error(`${settingLabel} is not declared`);
+        return [
+          name,
+          {
+            ...(translation.label !== undefined
+              ? { label: text(translation.label, `${settingLabel}.label`, WIDGET_TITLE_MAX_LENGTH) }
+              : {}),
+            ...(translation.placeholder !== undefined
+              ? { placeholder: text(translation.placeholder, `${settingLabel}.placeholder`, WIDGET_TITLE_MAX_LENGTH) }
+              : {}),
+            ...(translation.options
+              ? {
+                  options: labels(
+                    translation.options,
+                    new Set(field.kind === "choice" ? field.options.map((option) => option.value) : []),
+                    `${settingLabel}.options`,
+                    WIDGET_TITLE_MAX_LENGTH,
+                  ),
+                }
+              : {}),
+          },
+        ];
+      }),
+    );
     normalized[id] = {
+      ...(value.settings ? { settings } : {}),
       ...(value.title !== undefined ? { title: text(value.title, `${label}.${id}.title`, WIDGET_TITLE_MAX_LENGTH) } : {}),
       ...(value.description !== undefined
         ? { description: text(value.description, `${label}.${id}.description`, WIDGET_DESCRIPTION_MAX_LENGTH) }
@@ -55,7 +85,6 @@ export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCat
   const adminHrefs = new Set((app.adminNav ?? []).flatMap((group) => group.links.map((link) => link.href)));
   const searchHrefs = new Set((app.searchLinks ?? []).map((link) => link.href));
   const legalHrefs = new Set((app.legalLinks ?? []).map((link) => link.href));
-  const widgetIds = new Set((app.widgets ?? []).map((widget) => widget.id));
   const translations: Record<string, AppPresentationTranslation> = {};
 
   for (const [locale, translation] of Object.entries(catalog.translations)) {
@@ -82,7 +111,7 @@ export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCat
           }
         : {}),
       ...(translation.legalLinks ? { legalLinks: labels(translation.legalLinks, legalHrefs, `${canonical}.legalLinks`) } : {}),
-      ...(translation.widgets ? { widgets: widgetTexts(translation.widgets, widgetIds, `${canonical}.widgets`) } : {}),
+      ...(translation.widgets ? { widgets: widgetTexts(translation.widgets, app.widgets ?? [], `${canonical}.widgets`) } : {}),
     };
   }
 

package/src/_internal/define-app.ts

@@ -629,6 +629,7 @@ export const defineApp = <
           : undefined,
         widgets: meta.widgets?.map((widget) => ({
           ...widget,
+          ...(widget.settings ? { settings: structuredClone(widget.settings) } : {}),
           sizes: widget.sizes ? [...widget.sizes] : undefined,
           requiresRoles: widget.requiresRoles ? [...widget.requiresRoles] : undefined,
         })),

package/src/_internal/registry.ts

@@ -10,12 +10,14 @@ import {
   resolveWidgetSizes,
   WIDGET_DESCRIPTION_MAX_LENGTH,
   WIDGET_TITLE_MAX_LENGTH,
+  type WidgetSettingsDeclaration,
 } from "../contracts/widgets";
 import { resolveAppPresentations } from "../shared/app-presentation";
 import { compileCapabilityPresentation, parseCapabilityManifest } from "./capabilities";
 import { lazySync } from "./process-sync";
 import { validateAppRegistryEntry } from "./registry-validation";
 import { watchRegistryChanges } from "./registry-watch";
+import { WidgetSettingsDeclarationSchema } from "./widget-settings";
 
 /**
  * Shared app registry: two @k2b/sync ephemerals on the process Sync
@@ -356,6 +358,8 @@ export type DashboardWidget = {
   description: string;
   sizes: DashboardWidgetSize[];
   defaultSize: DashboardWidgetSize;
+  /** Validated setting presentation in the requested locale, absent when none is valid. */
+  settings?: WidgetSettingsDeclaration;
   suggest: boolean;
   /** Visibility only, like `nav.requiresRoles`; empty means everyone. */
   requiresRoles: Role[];
@@ -381,9 +385,13 @@ const declaredText = (value: unknown, max: number): string | undefined =>
 /** The widgets `apps` declare, resolved as `listWidgets()` returns them. */
 export const dashboardWidgetsOf = (apps: readonly AppRegistryEntry[], locale?: string): DashboardWidget[] => {
   const out: DashboardWidget[] = [];
-  for (const app of locale ? resolveAppPresentations(apps, locale) : apps) {
+  for (const [index, app] of (locale ? resolveAppPresentations(apps, locale) : apps).entries()) {
     for (const w of app.widgets ?? []) {
       const { sizes, defaultSize } = resolveWidgetSizes(w);
+      const translated = WidgetSettingsDeclarationSchema.safeParse(w.settings);
+      const original = translated.success
+        ? translated
+        : WidgetSettingsDeclarationSchema.safeParse(apps[index]?.widgets?.find((widget) => widget.id === w.id)?.settings);
       out.push({
         appId: app.id,
         appName: app.name,
@@ -394,6 +402,7 @@ export const dashboardWidgetsOf = (apps: readonly AppRegistryEntry[], locale?: s
         description: declaredText(w.description, WIDGET_DESCRIPTION_MAX_LENGTH) ?? app.description,
         sizes,
         defaultSize,
+        ...(original.success ? { settings: original.data } : {}),
         suggest: w.suggest === true,
         requiresRoles: Array.isArray(w.requiresRoles) ? w.requiresRoles.filter((role) => RoleSchema.safeParse(role).success) : [],
         presentation: legacyPresentation(w.presentation),

package/src/_internal/widget-declarations.ts

@@ -4,8 +4,10 @@ import {
   DASHBOARD_WIDGET_SIZES,
   isDashboardWidgetSize,
   WIDGET_DESCRIPTION_MAX_LENGTH,
+  WIDGET_ID_MAX_LENGTH,
   WIDGET_TITLE_MAX_LENGTH,
 } from "../contracts/widgets";
+import { WidgetSettingsDeclarationSchema } from "./widget-settings";
 
 const text = (value: string | undefined, label: string, max: number): string | undefined => {
   if (value === undefined) return undefined;
@@ -16,9 +18,9 @@ const text = (value: string | undefined, label: string, max: number): string | u
 
 /**
  * Validates and copies an app's widget declarations at `defineApp()`, so a typo fails at startup instead of a widget
- * silently missing from the gallery: unique ids without `@`, which separates a widget's key from the size the
- * dashboard asks for, bounded titles and descriptions, known sizes with the default among them, a boolean `suggest`,
- * and known roles.
+ * silently missing from the gallery: unique ids that fit Core's `widget.read:<id>` invocation, without `@`, which
+ * separates a widget's key from the requested size, bounded titles and descriptions, known sizes with the default
+ * among them, a boolean `suggest`, known roles, and a bounded settings declaration.
  */
 export const compileWidgetDeclarations = (
   appId: string,
@@ -30,6 +32,11 @@ export const compileWidgetDeclarations = (
     const label = `Widget ${JSON.stringify(widget.id)} of app ${JSON.stringify(appId)}`;
     if (!widget.id.trim()) throw new Error(`Widgets of app ${JSON.stringify(appId)} need a non-empty id`);
     if (widget.id.includes("@")) throw new Error(`${label} must not contain "@"`);
+    if (!/^[a-z0-9:._-]+$/.test(widget.id) || widget.id.length > WIDGET_ID_MAX_LENGTH) {
+      throw new Error(
+        `${label} id must use 1 to ${WIDGET_ID_MAX_LENGTH} lowercase letters, digits, ".", "_", "-", or ":" because Core invokes it as widget.read:<id>`,
+      );
+    }
     if (ids.has(widget.id)) throw new Error(`${label} is declared twice`);
     ids.add(widget.id);
     const sizes = widget.sizes ? [...widget.sizes] : undefined;
@@ -42,8 +49,14 @@ export const compileWidgetDeclarations = (
     if (widget.suggest !== undefined && typeof widget.suggest !== "boolean")
       throw new Error(`${label} must declare suggest as true or false`);
     if (widget.requiresRoles?.some((role) => !RoleSchema.safeParse(role).success)) throw new Error(`${label} requires an unknown role`);
+    const settings = widget.settings === undefined ? undefined : WidgetSettingsDeclarationSchema.safeParse(widget.settings);
+    if (settings && !settings.success) {
+      const issue = settings.error.issues[0]!;
+      throw new Error(`${label} setting ${JSON.stringify(issue.path[0] ?? "settings")}: ${issue.message}`);
+    }
     return {
       ...widget,
+      ...(settings?.success ? { settings: settings.data } : {}),
       title: text(widget.title, `${label} title`, WIDGET_TITLE_MAX_LENGTH),
       description: text(widget.description, `${label} description`, WIDGET_DESCRIPTION_MAX_LENGTH),
       sizes: sizes ? DASHBOARD_WIDGET_SIZES.filter((size) => sizes.includes(size)) : undefined,

package/src/_internal/widget-settings.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { CapabilityQualifiedIdSchema, CloudResourceRefSchema } from "../contracts/capabilities";
+import {
+  WIDGET_SETTING_MAX_OPTIONS,
+  WIDGET_SETTING_NAME_MAX_LENGTH,
+  WIDGET_SETTING_TEXT_MAX_LENGTH,
+  WIDGET_SETTINGS_MAX_FIELDS,
+  WIDGET_TITLE_MAX_LENGTH,
+  type WidgetSettings,
+  type WidgetSettingsDeclaration,
+  type WidgetSettingValue,
+} from "../contracts/widgets";
+
+const controlCharacters = /[\u0000-\u001f\u007f-\u009f]/u;
+const settingLabel = z.string().trim().min(1).max(WIDGET_TITLE_MAX_LENGTH);
+/** The single declaration schema used at startup and for tolerant registry reads. */
+export const WidgetSettingsDeclarationSchema = z
+  .record(
+    z.string().regex(new RegExp(`^[a-z][a-zA-Z0-9]{0,${WIDGET_SETTING_NAME_MAX_LENGTH - 1}}$`)),
+    z.discriminatedUnion("kind", [
+      z
+        .object({
+          kind: z.literal("choice"),
+          label: settingLabel,
+          options: z
+            .array(
+              z.object({
+                label: settingLabel,
+                value: z
+                  .string()
+                  .min(1)
+                  .max(100)
+                  .refine((value) => !controlCharacters.test(value)),
+              }),
+            )
+            .min(1)
+            .max(WIDGET_SETTING_MAX_OPTIONS),
+          default: z.string().optional(),
+        })
+        .superRefine((field, ctx) => {
+          if (new Set(field.options.map((option) => option.value)).size !== field.options.length)
+            ctx.addIssue({ code: "custom", path: ["options"], message: "Choice option values must be distinct" });
+          if (field.default !== undefined && !field.options.some((option) => option.value === field.default))
+            ctx.addIssue({ code: "custom", path: ["default"], message: "Choice default must be a declared option" });
+        }),
+      z.object({ kind: z.literal("resource"), label: settingLabel, type: CapabilityQualifiedIdSchema }),
+      z.object({ kind: z.literal("toggle"), label: settingLabel, default: z.boolean().optional() }),
+      z.object({
+        kind: z.literal("text"),
+        label: settingLabel,
+        placeholder: settingLabel.optional(),
+        maxLength: z.number().int().min(1).max(WIDGET_SETTING_TEXT_MAX_LENGTH).optional(),
+      }),
+    ]),
+  )
+  .superRefine((fields, ctx) => {
+    for (const name of Object.keys(fields)) {
+      if (name in Object.prototype)
+        ctx.addIssue({ code: "custom", path: [name], message: "Setting names must not be Object.prototype members" });
+    }
+  })
+  .refine((fields) => Object.keys(fields).length <= WIDGET_SETTINGS_MAX_FIELDS, `Declare at most ${WIDGET_SETTINGS_MAX_FIELDS} settings`);
+
+/** Drop invalid or undeclared values and fill choice and toggle defaults without reporting input errors. */
+export const parseWidgetSettings = (declaration: WidgetSettingsDeclaration | undefined, raw: unknown): WidgetSettings => {
+  const values = z.record(z.string(), z.unknown()).safeParse(raw);
+  const settings: Record<string, WidgetSettingValue> = {};
+  for (const [name, field] of Object.entries(declaration ?? {})) {
+    const value = values.success && Object.hasOwn(values.data, name) ? values.data[name] : undefined;
+    switch (field.kind) {
+      case "choice":
+        if (typeof value === "string" && field.options.some((option) => option.value === value)) settings[name] = value;
+        else if (field.default !== undefined) settings[name] = field.default;
+        break;
+      case "toggle":
+        if (typeof value === "boolean") settings[name] = value;
+        else if (field.default !== undefined) settings[name] = field.default;
+        break;
+      case "text": {
+        if (typeof value !== "string" || controlCharacters.test(value)) break;
+        const text = value.trim();
+        if (text && text.length <= (field.maxLength ?? WIDGET_SETTING_TEXT_MAX_LENGTH)) settings[name] = text;
+        break;
+      }
+      case "resource": {
+        const ref = CloudResourceRefSchema.safeParse(value);
+        if (ref.success && ref.data.type === field.type) settings[name] = ref.data;
+        break;
+      }
+    }
+  }
+  return settings;
+};

package/src/ai/capabilities.ts

@@ -15,8 +15,8 @@ import {
   type CapabilityActionManifest,
   type CapabilityActionReview,
   type CapabilityQueryManifest,
-  CloudResourceRefSchema,
   cloudResourceRefAppId,
+  LinkedCloudResourceReferenceSchema,
   resolveCapabilityResourceReader,
 } from "../contracts/capabilities";
 import type { CapabilityRegistryEntry } from "../contracts/registry";
@@ -29,6 +29,7 @@ import { recordRejectedAiCapability } from "./capability-execution";
 import { CODE_SOURCE_TOOLS } from "./code-source-contracts";
 import { createCodeSourceTool } from "./code-source-tools";
 import { CLOUD_AI_DEFERRED_BUILTIN_TOOL_NAMES } from "./default-tools";
+import { addCloudResourceHrefs } from "./resource-refs";
 import { type AiToolPreparationContext, defineAiTool, type PreparedAiTools, prepareAiTools } from "./tools";
 import type { AiConversationService, AiRuntimeTool, AiToolPresentation } from "./types";
 
@@ -638,6 +639,7 @@ export const createAiToolMetaTools = (input: {
 };
 
 export const createLoadedAiCapabilityTools = (input: {
+  apps: readonly CapabilityRegistryEntry[];
   catalog: readonly AiCapabilityCatalogEntry[];
   loadedNames: readonly string[];
   actor: RequestActor;
@@ -686,7 +688,7 @@ export const createLoadedAiCapabilityTools = (input: {
             throw new Error("Capability Action was rejected by the user.");
           }
         }
-        return input.execute(entry, args, context);
+        return addCloudResourceHrefs(await input.execute(entry, args, context), input.apps);
       }),
     ];
   });
@@ -701,14 +703,14 @@ export const createAiResourceReaderTool = (input: {
     name: "read_cloud_resource",
     description:
       "Read a Cloud resource from its structured reference using the resource type's current canonical reader. Pass refs returned by search, Projects, or other capabilities unchanged; never substitute an id from another resource type.",
-    inputSchema: CloudResourceRefSchema,
+    inputSchema: LinkedCloudResourceReferenceSchema,
     outputSchema: z.unknown(),
     approval: "never",
   }).server(async (ref, context) => {
     if (ref.type === "assistant.artifact") {
       const tool = createCodeSourceTool("code_read");
       if (tool.location !== "server") throw new Error("Code reader must execute on the server.");
-      return tool.run(CODE_SOURCE_TOOLS.code_read.input.parse({ id: ref.id }), context);
+      return addCloudResourceHrefs(await tool.run(CODE_SOURCE_TOOLS.code_read.input.parse({ id: ref.id }), context), input.apps);
     }
     const appId = cloudResourceRefAppId(ref);
     const app = input.apps.find((candidate) => candidate.appId === appId);
@@ -718,7 +720,7 @@ export const createAiResourceReaderTool = (input: {
       (candidate) => candidate.appId === appId && candidate.kind === "query" && candidate.operation.localId === reader.localId,
     );
     if (!entry) throw new Error(`Cloud resource reader ${appId}.${reader.localId} is unavailable.`);
-    return input.execute(entry, { id: ref.id }, context);
+    return addCloudResourceHrefs(await input.execute(entry, { id: ref.id }, context), input.apps);
   });
 
 /** Nessi resolver: one registry/load-state snapshot drives discovery, loading, schemas, and execution per model turn. */
@@ -860,6 +862,7 @@ export const createAiToolResolver =
       ...activeBuiltIns,
       ...(input.execute
         ? createLoadedAiCapabilityTools({
+            apps: registry,
             catalog: capabilityCatalog,
             loadedNames,
             actor: input.actor,

package/src/ai/resource-refs.ts

@@ -1,12 +1,43 @@
 import {
+  CloudResourceHrefSchema,
   type CloudResourceRef,
-  type CloudResourceReference,
   CloudResourceReferenceSchema,
   type CloudResourceView,
   CloudResourceViewSchema,
+  cloudResourceHref,
+  cloudResourceRefAppId,
+  resolveCapabilityResourceReader,
 } from "../contracts/capabilities";
+import type { CapabilityRegistryEntry } from "../contracts/registry";
 import type { AiConversationResourceObservation } from "./types";
 
+const LinkedResourceReferenceSchema = CloudResourceReferenceSchema.extend({
+  href: CloudResourceHrefSchema.optional(),
+});
+
+export const addCloudResourceHrefs = <T>(
+  value: T,
+  apps: readonly Pick<CapabilityRegistryEntry, "appId" | "manifest">[],
+  origin?: string,
+) => {
+  if (!value || typeof value !== "object" || !("refs" in value) || !Array.isArray(value.refs)) return value;
+  return {
+    ...value,
+    refs: value.refs.map((reference: unknown) => {
+      if (reference && typeof reference === "object" && "href" in reference) return reference;
+      const parsed = CloudResourceReferenceSchema.safeParse(reference);
+      if (!parsed.success) return reference;
+      const ref = parsed.data;
+      if (!ref.id.isWellFormed()) return reference;
+      const app = apps.find((candidate) => candidate.appId === cloudResourceRefAppId(ref));
+      if (!app || !resolveCapabilityResourceReader(app.manifest, ref)) return reference;
+      const href = CloudResourceHrefSchema.safeParse(cloudResourceHref(ref));
+      if (!href.success) return reference;
+      return { ...ref, href: origin ? new URL(href.data, origin).href : href.data };
+    }),
+  };
+};
+
 const observationKey = (ref: CloudResourceRef): string => `${ref.type}\0${ref.id}`;
 
 export const isConversationResourceCursor = (value: string, scope: "conversation" | "user"): boolean => {
@@ -47,9 +78,9 @@ export const collectConversationResourceObservations = (...values: unknown[]): A
         href: resource.links.find((link) => link.rel === "open")?.href,
       });
     } else {
-      const reference = CloudResourceReferenceSchema.safeParse(value);
+      const reference = LinkedResourceReferenceSchema.safeParse(value);
       if (reference.success) {
-        const resource: CloudResourceReference = reference.data;
+        const resource = reference.data;
         const ref: CloudResourceRef = { type: resource.type, id: resource.id };
         const previous = observations.get(observationKey(ref));
         observations.set(observationKey(ref), {
@@ -58,6 +89,7 @@ export const collectConversationResourceObservations = (...values: unknown[]): A
           ...(resource.title !== undefined ? { title: resource.title } : {}),
           ...(resource.preview !== undefined ? { preview: resource.preview } : {}),
           ...(resource.icon !== undefined ? { icon: resource.icon } : {}),
+          ...(resource.href !== undefined ? { href: resource.href } : {}),
         });
       }
     }

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",