@k2b/cloud 0.29.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -38,6 +38,7 @@
     "./browser/resource-clipboard": "./src/browser/resource-clipboard.ts",
     "./browser/commands": "./src/browser/commands.ts",
     "./browser/search": "./src/browser/search.ts",
+    "./browser/widgets": "./src/browser/widgets.ts",
     "./browser/testing": "./src/browser/testing.ts",
     "./browser/resource-picker": "./src/browser/resource-picker.tsx",
     "./browser/files": "./src/browser/files.tsx",
@@ -55,6 +56,7 @@
     "./services": "./src/services/index.ts",
     "./services/image-metadata": "./src/services/image-metadata.ts",
     "./services/document-extraction": "./src/services/document-extraction.ts",
+    "./services/outbox": "./src/services/outbox.ts",
     "./services/ipa/service-account": null,
     "./services/*": "./src/services/*",
     "./ai": "./src/ai/index.ts",
@@ -91,7 +93,7 @@
   },
   "scripts": {
     "test": "bun test --isolate --path-ignore-patterns '**/*.behavior.test.*'",
-    "typecheck": "tsc -p tsconfig.json --noEmit --pretty false"
+    "typecheck": "tsc --checkers 2 -p tsconfig.json --noEmit --pretty false"
   },
   "dependencies": {
     "@firecrawl/anydoc": "0.2.4",
@@ -102,7 +104,7 @@
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.17.0",
     "@k2b/ssr": "0.15.0",
-    "@k2b/ui": "0.19.0",
+    "@k2b/ui": "0.21.0",
     "@k2b/stdlib": "0.28.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",

package/src/_internal/app-roles.ts

@@ -0,0 +1,14 @@
+// Types only: the shell evaluates this on every page and must not load the account schemas.
+import type { AppRegistryNav } from "../contracts/registry";
+import type { Role, User } from "../contracts/shared";
+
+/** An app's declared roles: absent roles admit everyone, and `guest` matches the guest profile. */
+export const hasAnyAppRole = (user: User | undefined, roles: readonly Role[] | undefined): boolean =>
+  !roles || (!!user && roles.some((role) => (role === "guest" ? user.profile === "guest" : user.roles.includes(role))));
+
+/**
+ * Who may see an app's Help and Skills: its navigation roles, or administrators for an app reached only through the
+ * admin area (`adminHref` without its own `href`). `undefined` admits every signed-in user.
+ */
+export const appAudienceRoles = (nav: AppRegistryNav | undefined): readonly Role[] | undefined =>
+  nav?.requiresRoles ?? (nav && !nav.href && nav.adminHref ? ["admin"] : undefined);

package/src/_internal/capabilities.ts

@@ -10,6 +10,7 @@ import {
   type CapabilityActionManifest,
   type CapabilityActionReviewResult,
   CapabilityActionReviewSchema,
+  type CapabilityActionSentences,
   type CapabilityCommandDefinition,
   type CapabilityCommandManifest,
   CapabilityCommandManifestSchema,
@@ -38,6 +39,14 @@ import {
 } from "../contracts/capabilities";
 import { fileProviderIssues } from "../contracts/file-provider";
 import { canonicalLocale, localeFallbackChain, normalizeLocale } from "../shared/locale";
+import {
+  CAPABILITY_SENTENCE_KEYS,
+  CAPABILITY_SENTENCE_MAX_CHARS,
+  type CapabilityActionWording,
+  capabilitySentenceFields,
+  parseCapabilitySentence,
+  resolveCapabilityActionSentences,
+} from "./capability-sentences";
 
 type JsonSchema = Record<string, unknown>;
 const MAX_CAPABILITY_MANIFEST_BYTES = 256 * 1024;
@@ -274,6 +283,56 @@ const compileSchemaPresentation = (
   return Object.fromEntries(entries);
 };
 
+const isAction = (
+  operation: CapabilityQueryManifest | CapabilityActionManifest | CapabilityCommandManifest,
+): operation is CapabilityActionManifest => "idempotency" in operation;
+
+/**
+ * Checks one Action's sentences against its schemas: every placeholder names a field the Action declares,
+ * and only `done` reads result data, because the other sentences are shown before or instead of a result.
+ */
+export const compileActionSentences = (
+  value: unknown,
+  operation: Pick<CapabilityActionManifest, "inputSchema" | "dataSchema">,
+  label: string,
+  strict = true,
+): CapabilityActionSentences => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  const copy = value as Record<string, unknown>;
+  const extra = Object.keys(copy).find((key) => !(CAPABILITY_SENTENCE_KEYS as readonly string[]).includes(key));
+  if (strict && extra) throw new Error(`${label} contains unsupported field "${extra}"`);
+  const paths = { input: schemaFieldPaths(operation.inputSchema), data: schemaFieldPaths(operation.dataSchema) };
+  const sentences: Record<string, string> = {};
+  for (const key of CAPABILITY_SENTENCE_KEYS) {
+    const template = copy[key];
+    if (template === undefined) continue;
+    if (typeof template !== "string") throw new Error(`${label}.${key} must be text`);
+    assertText(template, `${label}.${key}`, CAPABILITY_SENTENCE_MAX_CHARS);
+    const parsed = parseCapabilitySentence(template.trim());
+    if ("error" in parsed) throw new Error(`${label}.${key} ${parsed.error}`);
+    for (const part of parsed.parts) {
+      if (typeof part === "string") continue;
+      if (part.source === "data" && key !== "done") throw new Error(`${label}.${key} may read {data.${part.path}} only in done`);
+      if (!paths[part.source].has(part.path)) {
+        throw new Error(`${label}.${key} placeholder {${part.source}.${part.path}} does not exist in the projected ${part.source} schema`);
+      }
+    }
+    sentences[key] = template.trim();
+  }
+  if (Object.keys(sentences).length === 0) throw new Error(`${label} needs at least one sentence`);
+  return sentences;
+};
+
+/** A reader keeps an entry's other copy when only its sentences come from a newer or broken producer. */
+const readActionSentences = (value: unknown, operation: CapabilityActionManifest, label: string, strict: boolean) => {
+  if (strict) return compileActionSentences(value, operation, label, strict);
+  try {
+    return compileActionSentences(value, operation, label, strict);
+  } catch {
+    return undefined;
+  }
+};
+
 const compileOperationPresentation = (
   value: unknown,
   operation: CapabilityQueryManifest | CapabilityActionManifest | CapabilityCommandManifest,
@@ -283,7 +342,9 @@ const compileOperationPresentation = (
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
   const translation = value as Record<string, unknown>;
   const allowed = new Set(
-    "path" in operation ? ["title", "description", "input"] : ["title", "description", "input", "data", "searchTags"],
+    "path" in operation
+      ? ["title", "description", "input"]
+      : ["title", "description", "input", "data", "searchTags", ...(isAction(operation) ? ["sentences"] : [])],
   );
   const extra = Object.keys(translation).find((key) => !allowed.has(key));
   if (strict && extra) throw new Error(`${label} contains unsupported field "${extra}"`);
@@ -330,12 +391,17 @@ const compileOperationPresentation = (
   }
   const input = compileSchemaPresentation(translation.input, operation.inputSchema, `${label}.input`);
   const data = "dataSchema" in operation ? compileSchemaPresentation(translation.data, operation.dataSchema, `${label}.data`) : undefined;
+  const sentences =
+    translation.sentences !== undefined && isAction(operation)
+      ? readActionSentences(translation.sentences, operation, `${label}.sentences`, strict)
+      : undefined;
   return {
     ...(typeof translation.title === "string" ? { title: translation.title.trim() } : {}),
     ...(typeof translation.description === "string" ? { description: translation.description.trim() } : {}),
     ...(input ? { input } : {}),
     ...(data ? { data } : {}),
     ...(searchTags ? { searchTags } : {}),
+    ...(sentences ? { sentences } : {}),
   };
 };
 
@@ -353,7 +419,7 @@ export const compileCapabilityPresentation = (
   if (value === undefined) return undefined;
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Capability presentation must be an object");
   const catalog = value as Record<string, unknown>;
-  if (strict && Object.keys(catalog).some((key) => key !== "baseLocale" && key !== "translations")) {
+  if (strict && Object.keys(catalog).some((key) => key !== "baseLocale" && key !== "sentences" && key !== "translations")) {
     throw new Error("Capability presentation contains unsupported fields");
   }
   const baseLocale = typeof catalog.baseLocale === "string" ? canonicalLocale(catalog.baseLocale) : undefined;
@@ -365,6 +431,23 @@ export const compileCapabilityPresentation = (
   const queries = new Map(manifest.queries.map((operation) => [operation.localId, operation]));
   const actions = new Map(manifest.actions.map((operation) => [operation.localId, operation]));
   const commands = new Map(manifest.commands.map((operation) => [operation.localId, operation]));
+  let sentences: Record<string, CapabilityActionSentences> | undefined;
+  if (catalog.sentences !== undefined) {
+    if (!catalog.sentences || typeof catalog.sentences !== "object" || Array.isArray(catalog.sentences)) {
+      throw new Error("Capability presentation sentences must be an object");
+    }
+    sentences = Object.fromEntries(
+      Object.entries(catalog.sentences as Record<string, unknown>).flatMap(([localId, entry]) => {
+        const action = actions.get(localId);
+        if (!action) {
+          if (strict) throw new Error(`Action sentences reference unknown localId "${localId}"`);
+          return [];
+        }
+        const compiled = readActionSentences(entry, action, `Action ${localId}.sentences`, strict);
+        return compiled ? [[localId, compiled]] : [];
+      }),
+    );
+  }
   const translations: Record<string, CapabilityPresentationTranslation> = {};
   for (const [locale, rawTranslation] of Object.entries(catalog.translations as Record<string, unknown>)) {
     const canonical = canonicalLocale(locale);
@@ -431,7 +514,7 @@ export const compileCapabilityPresentation = (
       ...(translatedCommands ? { commands: translatedCommands } : {}),
     };
   }
-  return { baseLocale, translations };
+  return { baseLocale, ...(sentences && Object.keys(sentences).length > 0 ? { sentences } : {}), translations };
 };
 
 const projectSchema = (schema: z.ZodType, label: string, io: "input" | "output"): JsonSchema => {
@@ -798,6 +881,31 @@ export const resolveCapabilityOperationTitle = (
     operation.title,
   );
 
+/**
+ * Everything a reader needs to word calls of one Action in the requested locale: its title, the app's
+ * sentences, and the labelled fields of the generic sentence. Derived only from the live manifest and
+ * presentation catalog, the same way for every app.
+ */
+export const resolveCapabilityActionWording = (
+  operation: CapabilityActionManifest,
+  catalog: CapabilityPresentationCatalog | undefined,
+  requestedLocale: string,
+): CapabilityActionWording => {
+  const overlays = catalog ? presentationOverlays(catalog, requestedLocale) : [];
+  const inputDescriptions = Object.assign({}, ...overlays.map((translation) => translation.actions?.[operation.localId]?.input ?? {}));
+  const sentences = resolveCapabilityActionSentences(operation.localId, catalog, requestedLocale);
+  return {
+    title: resolveCapabilityOperationTitle(operation, "actions", catalog, requestedLocale),
+    ...(sentences ? { sentences } : {}),
+    fields: capabilitySentenceFields({
+      inputSchema: operation.inputSchema,
+      dataSchema: operation.dataSchema,
+      sentences,
+      inputDescriptions,
+    }),
+  };
+};
+
 /** Resolve only human presentation; stable IDs, flags, tags, aliases, and data shapes stay untouched. */
 export const resolveCapabilityManifestPresentation = (
   manifest: CapabilityManifest,

package/src/_internal/capability-sentences.ts

@@ -0,0 +1,413 @@
+import { dates, i18n } from "@k2b/stdlib";
+import type { CapabilityActionSentences, CapabilityPresentationCatalog } from "../contracts/capabilities";
+import { canonicalLocale, localeFallbackChain, normalizeLocale } from "../shared/locale";
+import { normalizeTimeZone } from "../shared/time";
+
+/**
+ * Action sentences: what an Action will do or did, in the words of its app. One pure renderer serves the
+ * server (approval text for the CLI and notifications) and the chat in the browser, so both read the same.
+ * It never knows an app: everything comes from the Action's presentation catalog and its schemas.
+ */
+
+export const CAPABILITY_SENTENCE_KEYS = ["approval", "done", "rejected", "notRun"] as const;
+export type CapabilitySentenceKey = (typeof CAPABILITY_SENTENCE_KEYS)[number];
+
+export const CAPABILITY_SENTENCE_MAX_CHARS = 200;
+const MAX_PLACEHOLDERS = 6;
+const MAX_VALUE_CHARS = 60;
+const MAX_LIST_ITEMS = 3;
+const MAX_RENDERED_CHARS = 240;
+const MAX_FALLBACK_FIELDS = 2;
+const MAX_LABELLED_FIELDS = 8;
+const MAX_LABEL_CHARS = 40;
+const MAX_DEPTH = 2;
+
+export type CapabilitySentencePlaceholder = { source: "input" | "data"; path: string };
+type Part = string | CapabilitySentencePlaceholder;
+
+const PLACEHOLDER = /\{(input|data)\.([A-Za-z_][\w-]*(?:\[\])?(?:\.[A-Za-z_][\w-]*(?:\[\])?)*)\}/g;
+/** Controls, invisible format characters such as direction marks, joiners, and soft hyphens, and line breaks. */
+const UNSAFE_CHARACTER = /[\p{Cc}\p{Cf}\u2028\u2029]/u;
+const UNSAFE_CHARACTERS = new RegExp(UNSAFE_CHARACTER.source, "gu");
+
+/** Splits a template into text and placeholders, or names what makes it invalid. */
+export const parseCapabilitySentence = (template: string): { parts: Part[] } | { error: string } => {
+  const parts: Part[] = [];
+  let index = 0;
+  for (const match of template.matchAll(PLACEHOLDER)) {
+    parts.push(template.slice(index, match.index));
+    parts.push({ source: match[1] as "input" | "data", path: match[2]! });
+    index = match.index + match[0].length;
+  }
+  parts.push(template.slice(index));
+  const text = parts.filter((part): part is string => typeof part === "string");
+  if (text.some((part) => part.includes("{") || part.includes("}"))) {
+    return { error: "uses a placeholder other than {input.path} or {data.path}" };
+  }
+  if (text.some((part) => UNSAFE_CHARACTER.test(part))) return { error: "contains control or direction characters" };
+  if (parts.length - text.length > MAX_PLACEHOLDERS) return { error: `uses more than ${MAX_PLACEHOLDERS} placeholders` };
+  return { parts: parts.filter((part) => part !== "") };
+};
+
+/** Placeholders of one valid template; empty for an invalid one. */
+export const capabilitySentencePlaceholders = (template: string): CapabilitySentencePlaceholder[] => {
+  const parsed = parseCapabilitySentence(template);
+  return "parts" in parsed ? parsed.parts.filter((part): part is CapabilitySentencePlaceholder => typeof part !== "string") : [];
+};
+
+/** How the renderer reads one schema field: its label for the generic sentence and its date semantics. */
+export type CapabilitySentenceField = {
+  /** `input.<path>` or `data.<path>`. */
+  path: string;
+  /** Short field title in the reader's locale; only labelled input fields appear in the generic sentence. */
+  label?: string;
+  format?: "date" | "date-time";
+};
+
+/** Everything a reader needs to word one Action call, resolved for one locale. */
+export type CapabilityActionWording = {
+  title: string;
+  sentences?: CapabilityActionSentences;
+  fields?: readonly CapabilitySentenceField[];
+};
+
+/** The reader: locale for words and numbers, IANA time zone for instants (UTC when unknown or invalid). */
+export type CapabilitySentenceContext = { locale: string; timeZone?: string };
+
+const words = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      yes: "yes",
+      no: "no",
+      more: ({ count }: { count: number }) => `${count} more`,
+      why: "Why",
+    },
+    de: {
+      yes: "ja",
+      no: "nein",
+      more: ({ count }) => `${count} weitere`,
+      why: "Warum",
+    },
+  },
+});
+
+export const checkCapabilitySentenceMessages = () => words.check();
+
+/** The input field a model may add to an Action call that waits for approval: its own reason, never app input. */
+export const CAPABILITY_APPROVAL_REASON_FIELD = "approvalReason";
+export const CAPABILITY_APPROVAL_REASON_MAX_CHARS = 300;
+
+/** The model's reason for one call as one bounded line, or `null` when it gave none. */
+export const capabilityApprovalReason = (args: unknown): string | null => {
+  const value =
+    isRecord(args) && Object.hasOwn(args, CAPABILITY_APPROVAL_REASON_FIELD) ? args[CAPABILITY_APPROVAL_REASON_FIELD] : undefined;
+  return typeof value === "string" ? plain(value, CAPABILITY_APPROVAL_REASON_MAX_CHARS) || null : null;
+};
+
+/** The label of the model's reason, so a reader never takes it for the app's own words. */
+export const capabilityApprovalReasonLabel = (locale: string): string => words.resolve([locale]).t.why;
+
+/**
+ * The approval as text, for readers without the card such as the CLI: the app and what the call does, the app's live
+ * review of this call, which may say what the input cannot, such as a scheduled send, then the model's labelled reason.
+ */
+export const capabilityApprovalText = (input: {
+  appName: string;
+  subject: string;
+  review?: string | null;
+  reason?: string | null;
+  locale: string;
+}): string =>
+  [
+    `${input.appName}: ${input.subject}`,
+    ...(input.review?.trim() ? [input.review.trim()] : []),
+    ...(input.reason ? [`${capabilityApprovalReasonLabel(input.locale)}: ${input.reason}`] : []),
+  ].join("\n");
+
+const isRecord = (value: unknown): value is Record<string, unknown> => Boolean(value && typeof value === "object" && !Array.isArray(value));
+
+const own = (value: unknown, key: string): unknown => (isRecord(value) && Object.hasOwn(value, key) ? value[key] : undefined);
+
+/**
+ * Plain one-line text without control or invisible format characters, cut at a code point boundary. A value keeps
+ * its start and its end, so a long path keeps its file name and an address its domain; prose keeps its start.
+ */
+const plain = (value: string, max: number, cut: "end" | "middle" = "end"): string => {
+  const text = value.replace(UNSAFE_CHARACTERS, " ").replace(/\s+/g, " ").trim();
+  const points = Array.from(text);
+  if (points.length <= max) return text;
+  if (cut === "end")
+    return `${points
+      .slice(0, max - 1)
+      .join("")
+      .trimEnd()}…`;
+  const tail = Math.floor((max - 1) / 2);
+  return `${points
+    .slice(0, max - 1 - tail)
+    .join("")
+    .trimEnd()}…${points.slice(-tail).join("").trimStart()}`;
+};
+
+/** One inserted value: bounded, and cut in the middle so both of its ends stay readable. */
+const valueText = (value: string): string => plain(value, MAX_VALUE_CHARS, "middle");
+
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|[+-]([01]\d|2[0-3]):[0-5]\d)$/;
+
+/** A real calendar day: JavaScript rolls "2026-02-30" over to March, and year 0 would read as year 1. */
+const isCalendarDate = (value: string): boolean => {
+  const date = new Date(`${value}T12:00:00.000Z`);
+  return !Number.isNaN(date.getTime()) && date.getUTCFullYear() >= 1 && date.toISOString().slice(0, 10) === value;
+};
+
+/**
+ * A value of a field whose schema declares `format: "date"` or `"date-time"`: a calendar date stays that date
+ * everywhere, an instant shows in the reader's time zone, like review details. Anything that is not a real date
+ * or instant stays the text the call carries, so a sentence never names a different value than the one that runs.
+ */
+const formatDate = (value: string, format: "date" | "date-time", context: CapabilitySentenceContext): string | null => {
+  if (!isCalendarDate(value.slice(0, 10))) return null;
+  if (DATE.test(value)) return dates.formatDate(`${value}T12:00:00.000Z`, { locale: context.locale, timeZone: "UTC" });
+  if (!DATE_TIME.test(value) || Number.isNaN(new Date(value).getTime())) return null;
+  const options = { locale: context.locale, timeZone: normalizeTimeZone(context.timeZone) };
+  return format === "date-time" ? dates.formatDateTime(value, options) : dates.formatDate(value, options);
+};
+
+/**
+ * Keys that name a person or resource. The value an Action acts on comes first: a name from the model's input is
+ * not verified, so "Jana Berger" must never stand in for the address a draft actually goes to.
+ */
+const DISPLAY_KEYS = ["email", "address", "path", "displayName", "name", "title", "label"] as const;
+
+const formatValue = (
+  value: unknown,
+  format: CapabilitySentenceField["format"],
+  context: CapabilitySentenceContext,
+  depth = 0,
+): string | null => {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string") {
+    const text = value.trim();
+    if (!text) return null;
+    return (format ? formatDate(text, format, context) : null) ?? (valueText(text) || null);
+  }
+  if (typeof value === "number") return Number.isFinite(value) ? valueText(new Intl.NumberFormat(context.locale).format(value)) : null;
+  if (typeof value === "boolean") {
+    const t = words.resolve([context.locale]).t;
+    return value ? t.yes : t.no;
+  }
+  if (depth >= MAX_DEPTH) return null;
+  if (Array.isArray(value)) {
+    // An entry without a value to show still counts, so a list never reads shorter than the call it describes.
+    const items = value.flatMap((item) => {
+      const text = formatValue(item, format, context, depth + 1);
+      return text ? [text] : [];
+    });
+    if (items.length === 0) return null;
+    const shown = items.slice(0, value.length > MAX_LIST_ITEMS ? MAX_LIST_ITEMS - 1 : MAX_LIST_ITEMS);
+    const rest = value.length - shown.length;
+    const list = rest > 0 ? [...shown, words.resolve([context.locale]).t.more({ count: rest })] : shown;
+    return new Intl.ListFormat(context.locale, { type: "conjunction" }).format(list);
+  }
+  if (isRecord(value)) {
+    for (const key of DISPLAY_KEYS) {
+      const text = formatValue(own(value, key), undefined, context, MAX_DEPTH);
+      if (text) return text;
+    }
+  }
+  return null;
+};
+
+/**
+ * Reads a dotted schema path such as `to[].name` from a value without touching inherited properties. Inside a list
+ * an entry without the field stays as `undefined`, so `{input.to[].name}` still counts a recipient without a name.
+ */
+const valueAt = (root: unknown, path: string): unknown => {
+  let current: unknown[] = [root];
+  let list = false;
+  for (const segment of path.split(".")) {
+    const many = segment.endsWith("[]");
+    const key = many ? segment.slice(0, -2) : segment;
+    current = current.flatMap((entry) => {
+      const next = own(entry, key);
+      if (many && Array.isArray(next)) return next;
+      return list || (!many && next !== undefined) ? [many ? undefined : next] : [];
+    });
+    list ||= many;
+  }
+  return list ? current : current[0];
+};
+
+/**
+ * Renders one template, or `null` when a placeholder has no value to show or the sentence would not fit: the
+ * caller then words the call generically instead of showing a sentence with a gap or without its last words,
+ * which in German often carry the verb or a "nicht".
+ */
+export const renderCapabilitySentence = (
+  template: string,
+  values: { input?: unknown; data?: unknown },
+  fields: readonly CapabilitySentenceField[] | undefined,
+  context: CapabilitySentenceContext,
+): string | null => {
+  const parsed = parseCapabilitySentence(template);
+  if ("error" in parsed) return null;
+  let text = "";
+  for (const part of parsed.parts) {
+    if (typeof part === "string") {
+      text += part;
+      continue;
+    }
+    const path = `${part.source}.${part.path}`;
+    const format = fields?.find((field) => field.path === path)?.format;
+    const value = formatValue(valueAt(part.source === "input" ? values.input : values.data, part.path), format, context);
+    if (value === null) return null;
+    text += value;
+  }
+  const rendered = plain(text, Number.MAX_SAFE_INTEGER);
+  return rendered && Array.from(rendered).length <= MAX_RENDERED_CHARS ? rendered : null;
+};
+
+/** The generic sentence: the title with up to two labelled input fields, in schema order. */
+export const capabilitySentenceFallback = (
+  wording: CapabilityActionWording,
+  input: unknown,
+  context: CapabilitySentenceContext,
+): string => {
+  const details: string[] = [];
+  for (const field of wording.fields ?? []) {
+    if (details.length >= MAX_FALLBACK_FIELDS) break;
+    if (!field.label || !field.path.startsWith("input.")) continue;
+    const value = formatValue(valueAt(input, field.path.slice("input.".length)), field.format, context);
+    if (value) details.push(`${field.label}: ${value}`);
+  }
+  return plain([plain(wording.title, MAX_VALUE_CHARS * 2), ...details].join(" · "), MAX_RENDERED_CHARS);
+};
+
+/** What the call does, as one sentence: the app's approval sentence, else the generic sentence. */
+export const capabilityActionSubject = (wording: CapabilityActionWording, input: unknown, context: CapabilitySentenceContext): string =>
+  (wording.sentences?.approval ? renderCapabilitySentence(wording.sentences.approval, { input }, wording.fields, context) : null) ??
+  capabilitySentenceFallback(wording, input, context);
+
+/** The app's own sentence for one outcome, or `null` when it has none that renders for this call. */
+export const capabilityActionOutcome = (
+  wording: CapabilityActionWording,
+  key: Exclude<CapabilitySentenceKey, "approval">,
+  values: { input?: unknown; data?: unknown },
+  context: CapabilitySentenceContext,
+): string | null => {
+  const template = wording.sentences?.[key];
+  return template ? renderCapabilitySentence(template, values, wording.fields, context) : null;
+};
+
+/**
+ * The sentences of one Action in the requested locale: the most specific locale that words the Action
+ * provides the whole set, so one receipt never mixes two languages.
+ */
+export const resolveCapabilityActionSentences = (
+  localId: string,
+  catalog: Pick<CapabilityPresentationCatalog, "baseLocale" | "sentences" | "translations"> | undefined,
+  requestedLocale: string,
+): CapabilityActionSentences | undefined => {
+  if (!catalog) return undefined;
+  const base = normalizeLocale(catalog.baseLocale);
+  const byLocale = new Map(
+    Object.entries(catalog.translations).flatMap(([locale, translation]) => {
+      const canonical = canonicalLocale(locale);
+      return canonical ? [[canonical, translation] as const] : [];
+    }),
+  );
+  for (const locale of localeFallbackChain(requestedLocale, base)) {
+    const sentences = locale === base ? catalog.sentences?.[localId] : byLocale.get(locale)?.actions?.[localId]?.sentences;
+    if (sentences) return sentences;
+  }
+  return undefined;
+};
+
+type JsonSchema = Record<string, unknown>;
+
+/** The schema of one field path, following properties, array items, and union members. */
+const schemaAt = (schema: unknown, path: string): JsonSchema | undefined => {
+  let nodes: unknown[] = [schema];
+  const expand = (node: unknown): JsonSchema[] => {
+    if (!isRecord(node)) return [];
+    const members = (["anyOf", "oneOf", "allOf"] as const).flatMap((keyword) => (Array.isArray(node[keyword]) ? node[keyword] : []));
+    return [node, ...members.flatMap(expand)];
+  };
+  for (const segment of path.split(".")) {
+    const many = segment.endsWith("[]");
+    const key = many ? segment.slice(0, -2) : segment;
+    nodes = nodes.flatMap(expand).flatMap((node) => {
+      const property = own(node.properties, key);
+      if (!many) return property === undefined ? [] : [property];
+      return expand(property).flatMap((candidate) => (candidate.items === undefined ? [] : [candidate.items]));
+    });
+  }
+  return nodes.flatMap(expand)[0];
+};
+
+const schemaFormat = (schema: JsonSchema | undefined): CapabilitySentenceField["format"] => {
+  const nodes = [schema, ...(["anyOf", "oneOf"] as const).flatMap((keyword) => (Array.isArray(schema?.[keyword]) ? schema[keyword] : []))];
+  const format = nodes.map((node) => own(node, "format")).find((value) => value === "date" || value === "date-time");
+  return format as CapabilitySentenceField["format"];
+};
+
+const schemaTypes = (schema: JsonSchema): string[] => {
+  const nodes = [schema, ...(["anyOf", "oneOf"] as const).flatMap((keyword) => (Array.isArray(schema[keyword]) ? schema[keyword] : []))];
+  return nodes.flatMap((node) => {
+    const type = own(node, "type");
+    return Array.isArray(type)
+      ? type.filter((entry): entry is string => typeof entry === "string")
+      : typeof type === "string"
+        ? [type]
+        : [];
+  });
+};
+
+/** Identifiers and concurrency tokens say nothing to a person. */
+const OPAQUE_FIELD = /(^id$|Ids?$|Revision$|Hash$|Token$|Cursor$|^idempotencyKey$)/;
+/** Long text such as a message body is not a detail of a one-line sentence. */
+const MAX_DETAIL_TEXT_LENGTH = 1000;
+
+/** A field description as a short title: its first clause, if that is short enough to label a value. */
+const shortLabel = (description: unknown): string | undefined => {
+  if (typeof description !== "string") return undefined;
+  const clause = plain(description, 200)
+    .split(/[.;:(]\s|[;:(]|\.$/)[0]!
+    .trim();
+  return clause && Array.from(clause).length <= MAX_LABEL_CHARS ? clause : undefined;
+};
+
+/**
+ * The fields a reader needs to word one Action: the formats of the placeholders its sentences use and
+ * the labelled top-level input fields that the generic sentence may show, in schema order and bounded.
+ * `inputDescriptions` are the reader's localized field descriptions keyed by dotted path.
+ */
+export const capabilitySentenceFields = (input: {
+  inputSchema: JsonSchema;
+  dataSchema?: JsonSchema;
+  sentences?: CapabilityActionSentences;
+  inputDescriptions?: Readonly<Record<string, string>>;
+}): CapabilitySentenceField[] => {
+  const fields = new Map<string, CapabilitySentenceField>();
+  const properties = isRecord(input.inputSchema.properties) ? input.inputSchema.properties : {};
+  for (const [key, value] of Object.entries(properties)) {
+    if (fields.size >= MAX_LABELLED_FIELDS) break;
+    if (!isRecord(value) || OPAQUE_FIELD.test(key) || value.format === "uuid") continue;
+    const types = schemaTypes(value);
+    if (types.length > 0 && types.every((type) => type === "boolean" || type === "null")) continue;
+    if (typeof value.maxLength === "number" && value.maxLength > MAX_DETAIL_TEXT_LENGTH) continue;
+    const label = shortLabel(input.inputDescriptions?.[key] ?? value.description);
+    if (!label) continue;
+    const format = schemaFormat(value);
+    fields.set(`input.${key}`, { path: `input.${key}`, label, ...(format ? { format } : {}) });
+  }
+  const templates = CAPABILITY_SENTENCE_KEYS.flatMap((key) => (input.sentences?.[key] ? [input.sentences[key]] : []));
+  for (const placeholder of templates.flatMap(capabilitySentencePlaceholders)) {
+    const path = `${placeholder.source}.${placeholder.path}`;
+    if (fields.has(path)) continue;
+    const format = schemaFormat(schemaAt(placeholder.source === "input" ? input.inputSchema : input.dataSchema, placeholder.path));
+    fields.set(path, { path, ...(format ? { format } : {}) });
+  }
+  return [...fields.values()];
+};