@k2b/cloud 0.29.1 → 0.31.0

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()];
+};

package/src/_internal/define-app.ts

@@ -1,3 +1,4 @@
+import { type AppSkillDefinition, appSkillManifestHash, registerAppSkills, validateAppSkillCatalog } from "../ai/app-skills";
 import { startLiveOutbox } from "../events/live";
 import { registerHelp } from "../services/help";
 import { preloadLayoutHelp } from "../ssr/help";
@@ -53,6 +54,7 @@ import { matchedRouteTemplate, routeTemplate } from "../server/middleware/route-
 import { runtime as runtimeMiddleware } from "../server/middleware/runtime";
 import { preloadLayoutAnnouncements, settings as settingsMiddleware } from "../server/middleware/settings";
 import { validationErrorResponse } from "../server/middleware/validator";
+import { setWidgetRequest } from "../server/widget-request";
 import {
   capabilityInvocationOperation,
   searchInvocationOperation,
@@ -91,6 +93,7 @@ import { ensureRuntimeWatcher, getCurrentRuntime, stopRuntimeWatcher } from "./r
 import { servePublicAsset } from "./static-assets";
 import { createStatusPreservingSsrHandler } from "./status-preserving-ssr";
 import { WEB_VITALS_ASSET_HREF } from "./web-vitals-asset";
+import { compileWidgetDeclarations } from "./widget-declarations";
 
 /** Cache-busting version stamp — changes on every server start / rebuild. */
 const v = Date.now();
@@ -167,6 +170,8 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
   settings?: S;
   /** Notification kinds owned by this app, conventionally imported from `src/notifications.ts`. */
   notifications?: N;
+  /** Assistant skills owned by this app, conventionally imported from `src/skills.ts`. */
+  skills?: readonly AppSkillDefinition[];
   /**
    * Legal/info links contributed by this app — aggregated app-wide via
    * `listLegalLinks()` and rendered in login footer, app Footer, rail more
@@ -375,6 +380,8 @@ export const defineApp = <
 >(
   opts: AppOptions<S, N, AppId>,
 ): AppDefinition<S, N, AppId> => {
+  const appSkills = opts.skills ? validateAppSkillCatalog(opts.skills) : undefined;
+  const skillsManifestHash = appSkills ? appSkillManifestHash(appSkills) : undefined;
   configurePostgresApplicationName(opts.id);
   const isDevelopment = env.IS_DEVELOPMENT;
   const notifications = bindNotificationDefinitions(opts.id, opts.notifications);
@@ -510,7 +517,7 @@ export const defineApp = <
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
     searchLinks: opts.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
     pwa: pwaPart,
-    widgets: opts.widgets ? opts.widgets.map((w) => ({ ...w })) : undefined,
+    widgets: compileWidgetDeclarations(opts.id, opts.widgets),
     settingKeys: opts.settings ? Object.keys(opts.settings) : undefined,
     openapi: opts.openapi,
     cli: opts.cli,
@@ -603,12 +610,17 @@ export const defineApp = <
             }
           : undefined,
         help: compiledHelp?.summary,
+        skills: skillsManifestHash ? { manifestHash: skillsManifestHash } : undefined,
         legalLinks: meta.legalLinks ? meta.legalLinks.map((l) => ({ ...l })) : undefined,
         searchLinks: meta.searchLinks,
         pwa: meta.pwa
           ? { href: meta.pwa.href, requiresRoles: meta.pwa.requiresRoles ? [...meta.pwa.requiresRoles] : undefined }
           : undefined,
-        widgets: meta.widgets ? meta.widgets.map((w) => ({ ...w })) : undefined,
+        widgets: meta.widgets?.map((widget) => ({
+          ...widget,
+          sizes: widget.sizes ? [...widget.sizes] : undefined,
+          requiresRoles: widget.requiresRoles ? [...widget.requiresRoles] : undefined,
+        })),
         platformPermissions: meta.platformPermissions ? [...meta.platformPermissions] : undefined,
         settingKeys: meta.settingKeys ? [...meta.settingKeys] : undefined,
         openapi: advertiseOpenapi ? opts.openapi : undefined,
@@ -618,7 +630,10 @@ export const defineApp = <
       // Heartbeat
       const heartbeat = createHeartbeat(meta.id, entry, {
         registry: appRegistry(),
-        beforeWrite: compiledHelp ? () => registerHelp(compiledHelp.corpus) : undefined,
+        beforeWrite: async () => {
+          if (compiledHelp) await registerHelp(compiledHelp.corpus);
+          if (appSkills && skillsManifestHash) await registerAppSkills(meta.id, appSkills, skillsManifestHash);
+        },
         onError: (error) =>
           log.error("Registry heartbeat failed", {
             appId: meta.id,
@@ -854,8 +869,12 @@ export const defineApp = <
           runtimeMiddleware(),
           settingsMiddleware(),
           async (c) => {
-            const handler = startOpts.widgets?.[c.req.param("widgetId") ?? ""];
-            return handler ? handler(c, async () => {}) : c.json({ message: "Widget not found" }, 404);
+            const widgetId = c.req.param("widgetId") ?? "";
+            const handler = startOpts.widgets?.[widgetId];
+            const declaration = meta.widgets?.find((widget) => widget.id === widgetId);
+            if (!handler || !declaration) return c.json({ message: "Widget not found" }, 404);
+            setWidgetRequest(c, declaration);
+            return handler(c, async () => {});
           },
         );
       }

package/src/_internal/registry-validation.ts

@@ -166,6 +166,11 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
       return invalid("capabilities", "a valid capability summary");
     }
   }
+  if (
+    value.skills !== undefined &&
+    (!isRecord(value.skills) || !isString(value.skills.manifestHash) || !/^[a-f0-9]{64}$/.test(value.skills.manifestHash))
+  )
+    return invalid("skills", "a valid app skill manifest hash");
   if (
     value.help !== undefined &&
     (!isRecord(value.help) ||

package/src/_internal/registry.ts

@@ -3,7 +3,14 @@ import type { AppAppearanceColor } from "../contracts/app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
 import { fileProviderIssues } from "../contracts/file-provider";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
-import type { DashboardWidgetPresentation } from "../contracts/widgets";
+import { type Role, RoleSchema } from "../contracts/shared";
+import {
+  type DashboardWidgetPresentation,
+  type DashboardWidgetSize,
+  resolveWidgetSizes,
+  WIDGET_DESCRIPTION_MAX_LENGTH,
+  WIDGET_TITLE_MAX_LENGTH,
+} from "../contracts/widgets";
 import { resolveAppPresentations } from "../shared/app-presentation";
 import { compileCapabilityPresentation, parseCapabilityManifest } from "./capabilities";
 import { lazySync } from "./process-sync";
@@ -332,7 +339,9 @@ export const listLegalLinks = async (locale?: string): Promise<Array<{ label: st
  * the dashboard app to build the widget grid and for Core to resolve the
  * exact target before proxying a widget request.
  *
- * Order = registration order across apps.
+ * Order = registration order across apps. Every optional declaration field is
+ * resolved here, so readers never see a registry record from an older app
+ * without `title`, `sizes`, or `defaultSize`, nor an unknown size or role.
  */
 export type DashboardWidget = {
   appId: string;
@@ -341,23 +350,58 @@ export type DashboardWidget = {
   widgetId: string;
   /** Fully-qualified URL — `<baseUrl>/<path>`. */
   url: string;
+  /** The declared title in the requested locale, or the app's name. */
+  title: string;
+  /** The declared description in the requested locale, or the app's description. */
+  description: string;
+  sizes: DashboardWidgetSize[];
+  defaultSize: DashboardWidgetSize;
+  suggest: boolean;
+  /** Visibility only, like `nav.requiresRoles`; empty means everyone. */
+  requiresRoles: Role[];
+  /**
+   * @deprecated The zone and width the app recommended before widgets had sizes. Only the dashboard reads it, to
+   * convert a board saved then into the board the person saw.
+   */
   presentation?: DashboardWidgetPresentation;
 };
 
-export const listWidgets = async (): Promise<DashboardWidget[]> => {
-  const apps = await listApps();
+const LEGACY_ZONES = ["focus", "overview", "context"] as const;
+const LEGACY_SPANS = ["standard", "wide"] as const;
+
+const legacyPresentation = (value: DashboardWidgetPresentation | undefined): DashboardWidgetPresentation | undefined => {
+  const defaultZone = LEGACY_ZONES.find((zone) => zone === value?.defaultZone);
+  const defaultSpan = LEGACY_SPANS.find((span) => span === value?.defaultSpan);
+  return defaultZone || defaultSpan ? { defaultZone, defaultSpan } : undefined;
+};
+
+const declaredText = (value: unknown, max: number): string | undefined =>
+  typeof value === "string" && value.trim() && value.trim().length <= max ? value.trim() : 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 apps) {
+  for (const app of locale ? resolveAppPresentations(apps, locale) : apps) {
     for (const w of app.widgets ?? []) {
+      const { sizes, defaultSize } = resolveWidgetSizes(w);
       out.push({
         appId: app.id,
         appName: app.name,
         appIcon: app.icon,
         widgetId: w.id,
         url: `${app.baseUrl.replace(/\/$/, "")}${w.path.startsWith("/") ? w.path : `/${w.path}`}`,
-        presentation: w.presentation,
+        title: declaredText(w.title, WIDGET_TITLE_MAX_LENGTH) ?? app.name,
+        description: declaredText(w.description, WIDGET_DESCRIPTION_MAX_LENGTH) ?? app.description,
+        sizes,
+        defaultSize,
+        suggest: w.suggest === true,
+        requiresRoles: Array.isArray(w.requiresRoles) ? w.requiresRoles.filter((role) => RoleSchema.safeParse(role).success) : [],
+        presentation: legacyPresentation(w.presentation),
       });
     }
   }
   return out;
 };
+
+/** Every declared widget, with titles and descriptions in `locale` when given. */
+export const listWidgets = async (locale?: string): Promise<DashboardWidget[]> => dashboardWidgetsOf(await listApps(), locale);

package/src/_internal/widget-declarations.ts

@@ -0,0 +1,53 @@
+import type { WidgetEndpoint } from "../contracts/app";
+import { RoleSchema } from "../contracts/shared";
+import {
+  DASHBOARD_WIDGET_SIZES,
+  isDashboardWidgetSize,
+  WIDGET_DESCRIPTION_MAX_LENGTH,
+  WIDGET_TITLE_MAX_LENGTH,
+} from "../contracts/widgets";
+
+const text = (value: string | undefined, label: string, max: number): string | undefined => {
+  if (value === undefined) return undefined;
+  const normalized = value.trim();
+  if (!normalized || normalized.length > max) throw new Error(`${label} must contain 1 to ${max} characters`);
+  return normalized;
+};
+
+/**
+ * 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.
+ */
+export const compileWidgetDeclarations = (
+  appId: string,
+  widgets: ReadonlyArray<WidgetEndpoint> | undefined,
+): WidgetEndpoint[] | undefined => {
+  if (!widgets) return undefined;
+  const ids = new Set<string>();
+  return widgets.map((widget) => {
+    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 (ids.has(widget.id)) throw new Error(`${label} is declared twice`);
+    ids.add(widget.id);
+    const sizes = widget.sizes ? [...widget.sizes] : undefined;
+    if (sizes && (sizes.length === 0 || sizes.some((size) => !isDashboardWidgetSize(size)) || new Set(sizes).size !== sizes.length)) {
+      throw new Error(`${label} must declare sizes as distinct values of ${DASHBOARD_WIDGET_SIZES.join(", ")}`);
+    }
+    if (widget.defaultSize !== undefined && !(sizes ?? ["large"]).includes(widget.defaultSize)) {
+      throw new Error(`${label} must declare a defaultSize it offers in sizes`);
+    }
+    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`);
+    return {
+      ...widget,
+      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,
+      requiresRoles: widget.requiresRoles ? [...widget.requiresRoles] : undefined,
+    };
+  });
+};