@k2b/cloud 0.32.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.32.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": {
@@ -105,10 +105,10 @@
     "@simplewebauthn/server": "14.0.3",
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
-    "@k2b/nessi": "0.17.1",
-    "@k2b/ssr": "0.15.0",
-    "@k2b/ui": "0.23.0",
-    "@k2b/stdlib": "0.28.0",
+    "@k2b/nessi": "0.18.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",
     "@nats-io/transport-node": "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

@@ -74,7 +74,7 @@ import { createSyncOpsRoutes } from "../services/sync-ops";
 import { capabilityMessages } from "../shared/capability-messages";
 import { normalizeLocale } from "../shared/locale";
 import { escapeHtml } from "../shared/markdown/shared";
-import { themeBootstrapScript } from "../shared/theme";
+import { type CloudThemePreference, readThemePreferenceFromCookieHeader, themeBootstrapScript } from "../shared/theme";
 import { appFaviconHref } from "./app-favicon";
 import { compileAppPresentation } from "./app-presentation";
 import { readBoundedJson } from "./bounded-json";
@@ -102,6 +102,7 @@ const v = Date.now();
 export type PageOptions = {
   title?: string;
   description?: string;
+  /** Fix public displays such as Pulse, Weather and Venue monitors to one theme; otherwise follow the person's preference. */
   theme?: "light" | "dark";
   /** Framework-resolved BCP 47 document language — always the canonical request locale, never a page override. */
   lang?: string;
@@ -109,7 +110,7 @@ export type PageOptions = {
   pwa?: { name: string };
 };
 
-type ResolvedPageOptions = PageOptions & { performanceRoute?: string };
+type ResolvedPageOptions = PageOptions & { performanceRoute?: string; themePreference?: CloudThemePreference };
 
 // ── Public types ────────────────────────────────────────────────────────────
 
@@ -411,17 +412,24 @@ export const defineApp = <
     // Every island instance already mounts inside its own error boundary; this
     // only gives the fallback Cloud's look and the reader's language.
     errorFallback: fileURLToPath(new URL("../ssr/IslandError.tsx", import.meta.url)),
-    template: ({ body, scripts, title, description, theme, lang, performanceRoute, pwa }) => {
-      const themeFixed = theme !== undefined;
+    template: ({ body, scripts, title, description, theme, themePreference, lang, performanceRoute, pwa }) => {
+      const fixed = theme !== undefined;
+      const resolved = theme ?? (themePreference === "light" || themePreference === "dark" ? themePreference : undefined);
       // App pages paint the canvas before any stylesheet and give it to the
       // status bar. No status-bar style: `black-translucent` lays a blur band
       // over the top edge on iOS 26.
-      const canvas = PWA_CANVAS_COLORS[theme ?? "light"];
+      const canvas = resolved ? PWA_CANVAS_COLORS[resolved] : undefined;
       const head = pwa
         ? {
-            html: ` style="background-color:${canvas}"`,
+            html: canvas ? ` style="background-color:${canvas}"` : "",
             viewport: "width=device-width, initial-scale=1, viewport-fit=cover",
-            app: `<meta name="theme-color" content="${canvas}">
+            app: `${
+              canvas
+                ? `<meta name="theme-color" content="${canvas}">`
+                : `<meta name="theme-color" media="(prefers-color-scheme: light)" content="${PWA_CANVAS_COLORS.light}">
+    <meta name="theme-color" media="(prefers-color-scheme: dark)" content="${PWA_CANVAS_COLORS.dark}">
+    <style data-cloud-canvas>html{background-color:${PWA_CANVAS_COLORS.light}}@media (prefers-color-scheme: dark){html{background-color:${PWA_CANVAS_COLORS.dark}}}</style>`
+            }
     <link rel="manifest" href="${PWA_MANIFEST_PATH}">
     <link rel="apple-touch-icon" href="/branding/apple-touch-icon.png">
     <meta name="apple-mobile-web-app-title" content="${escapeHtml(pwa.name)}">`,
@@ -442,7 +450,7 @@ export const defineApp = <
       // stylesheet declares a layer. Tailwind's `properties` layer resets
       // `--tw-*` in browsers without `@property` and must stay lowest.
       return `<!DOCTYPE html>
-<html lang="${normalizeLocale(lang)}" class="${theme ?? "light"}"${themeFixed ? " data-theme-fixed" : ""}${head.html}>
+<html lang="${normalizeLocale(lang)}" class="${resolved ?? "light"}"${fixed ? " data-theme-fixed" : ""}${head.html}>
   <head><meta charset="UTF-8"><meta name="viewport" content="${head.viewport}">
     <meta name="view-transition" content="same-origin">
     <title>${escapeHtml(title ?? "Cloud")}</title>
@@ -480,6 +488,7 @@ export const defineApp = <
   const ssr = Object.assign(
     createStatusPreservingSsrHandler<ResolvedPageOptions>(html, async (c) => {
       c.get("page").lang = getLocale(c);
+      c.get("page").themePreference = readThemePreferenceFromCookieHeader(c.req.header("Cookie"));
       const user = c.get("user");
       c.get("page").performanceRoute =
         user && c.get("settings")?.observability?.web_vitals?.enabled === true ? (matchedRouteTemplate(c) ?? undefined) : undefined;
@@ -620,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/page-responses.ts

@@ -5,6 +5,7 @@ import { PWA_AUTH_PATH, PWA_SCOPE } from "../contracts/pwa";
 import { getLocale } from "../server/locale";
 import { preloadLayoutAnnouncements } from "../server/middleware/settings";
 import { createLoginRedirectUrl } from "../shared/redirect";
+import { readThemePreferenceFromCookieHeader } from "../shared/theme";
 import type { PageOptions } from "./define-app";
 
 export type PageErrorOptions = {
@@ -21,7 +22,10 @@ export type PageErrorStatus = ClientErrorStatusCode | ServerErrorStatusCode;
 export const createPageResponses = (html: HtmlFn<PageOptions>) => {
   const error = async (c: Context, status: PageErrorStatus, options: PageErrorOptions = {}): Promise<Response> => {
     // Auth middleware may reject before ssr() initializes page metadata.
-    c.set("page", { lang: getLocale(c) });
+    c.set("page", {
+      lang: getLocale(c),
+      themePreference: readThemePreferenceFromCookieHeader(c.req.header("Cookie")),
+    });
     c.header("Cache-Control", "private, no-store");
     if (options.layout !== "pwa") await preloadLayoutAnnouncements(c);
     // Load JSX only after the application's SSR plugin has been installed.

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/code-source-contracts.ts

@@ -283,9 +283,24 @@ export const CODE_SOURCE_TOOLS = {
     input: Id.extend(ArtifactMetadata.shape),
   },
   code_create: {
+    promptHint:
+      "build every app, calculator, converter, timer, form or other tool the person asks for as a saved Studio app. In one turn, load_skill assistant-code-mode and load_tools code_create, code_write, code_check and code_open.",
     description:
-      "Create a private reusable App: an index.html interface with optional style.css and app.js, published actions and optional persistence. Starts with a minimal index.html. For one-off analysis, use code_run with code instead. Returns id and entry path; write source with code_write. Optional icon uses the complete class, e.g. ti ti-chart-bar; omit it when unsure. Does not run or share anything.",
-    input: ArtifactCreate.pick({ title: true, description: true, icon: true }),
+      "Create a saved Studio app; it appears in the person's Studio Apps and can be opened, reused and shared. Use it for every app, calculator, converter, timer, form or other interactive tool the person asks for, even when it keeps no data. Pass the complete first version as html (a small app is this one file) and steps (its steps.json), so one call creates it; add style.css, app.js or more files with code_write. Without html it starts with a minimal index.html. Returns id, revision and the lines and length of every file; with html or steps also diagnostics, like code_write. Optional icon uses the complete class, e.g. ti ti-calculator; omit it when unsure. For a one-off analysis use code_run instead. Does not run, check or share anything.",
+    input: ArtifactCreate.pick({ title: true, description: true, icon: true }).extend({
+      html: z
+        .string()
+        .max(1024 * 1024)
+        .optional()
+        .describe(
+          'Complete index.html. A small app fits in this one file: put its script in <script type="module"> and its CSS in <style>. Omit it to start with a minimal page.',
+        ),
+      steps: z
+        .string()
+        .max(1024 * 1024)
+        .optional()
+        .describe("Complete steps.json text for code_check: the main flow, at most 20 steps."),
+    }),
   },
   // Source text stays top-level because some providers corrupt strings nested in arrays.
   // Imports carry only references, so they keep an array and one review per batch.

package/src/ai/code-source-tools.ts

@@ -50,6 +50,7 @@ export function createCodeSourceTool(name: CodeSourceToolName) {
     inputSchema: definition.input,
     outputSchema: z.unknown(),
     approval: "never",
+    promptHint: "promptHint" in definition ? definition.promptHint : undefined,
   }).server(async (input, context) => {
     if (!context.conversationId) throw new Error("Code tools require an Assistant conversation.");
     const { actor } = await resolveAiCapabilityActor({

package/src/ai/default-tools.ts

@@ -99,12 +99,12 @@ export const createCloudAiCardTool = () =>
 export const createCloudAiChartTool = () =>
   defineAiTool({
     name: "chart",
-    description: `Show one chart in the chat from a few values you already have that did not come from a code run, such as figures from the conversation, a web page or a small capability result: bar, line (area: true fills it), scatter, pie, donut, histogram, gauge, sparkline, boxplot, heatmap, barGauge or stat. Several related measures go into one call as a group of small charts (charts, at most ${CLOUD_AI_GROUP_MAX_CHARTS}); linkX shares the x cursor between line charts with the same kind of x. There is no second y axis: compare measures with different units as a group. Cloud draws it with the renderer of cloud.chart() and gives the reader a data table and Copy data; no code, sandbox or app check is involved. Values computed in code_run never go here: the script shows them itself with cloud.view.chart, cloud.view.group, cloud.view.table, cloud.view.stats, cloud.view.details or cloud.view.explorer, and you present the returned path. Aggregate first. Say what the chart shows in title and put the unit, period or source in subtitle; formats are data ({ style: "percent" } takes fractions). The chart has no state, filters or actions: filters, steps and comparison over computed rows come from cloud.view.explorer in code_run; for other interaction show an app in the chat with code_present, and build a saved Studio App only when data must be kept or the app reused. After the chart, state the finding instead of repeating its values.`,
+    description: `Show one chart in the chat from a few values you already have that did not come from a code run, such as figures from the conversation, a web page or a small capability result: bar, line (area: true fills it), scatter, pie, donut, histogram, gauge, sparkline, boxplot, heatmap, barGauge or stat. Several related measures go into one call as a group of small charts (charts, at most ${CLOUD_AI_GROUP_MAX_CHARTS}); linkX shares the x cursor between line charts with the same kind of x. There is no second y axis: compare measures with different units as a group. Cloud draws it with the renderer of cloud.chart() and gives the reader a data table and Copy data; no code, sandbox or app check is involved. Values computed in code_run never go here: the script shows them itself with cloud.view.chart, cloud.view.group, cloud.view.table, cloud.view.stats, cloud.view.details or cloud.view.explorer, and you present the returned path. Aggregate first. Say what the chart shows in title and put the unit, period or source in subtitle; formats are data ({ style: "percent" } takes fractions). The chart has no state, filters or actions: filters, steps and comparison over computed rows come from cloud.view.explorer in code_run; anything else the person interacts with, such as a calculator, converter or form, is a Studio app built with code_create. After the chart, state the finding instead of repeating its values.`,
     inputSchema: CloudAiChartInputSchema,
     outputSchema: CloudAiChartOutputSchema,
     approval: "never",
     promptHint:
-      "show a few values you already have (not from a code run) as a chart in the chat. Code results use cloud.view.* and present; filters, steps and comparison use cloud.view.explorer in code_run; interaction beyond that needs a chat app (code_present).",
+      "show a few values you already have (not from a code run) as a chart in the chat. Code results use cloud.view.* and present; filters, steps and comparison use cloud.view.explorer in code_run; an app or tool to interact with is a Studio app (code_create).",
   }).clientView();
 
 export const createCloudAiSurveyTool = () =>
@@ -246,7 +246,7 @@ export const createCloudAiCodeTools = () => [
   defineAiTool({
     name: "code_open",
     description:
-      "Show the app beside the chat without starting it; HTML apps require a passing code_check for the current files and tables. For one-off calculations, return the result instead of opening an app.",
+      "Show a saved Studio app beside the chat without starting it; HTML apps require a passing code_check for the current files and tables. When the person only wants one calculated result, answer it instead of building an app.",
     inputSchema: CodeOpenInput,
     outputSchema: z.json(),
     approval: "never",
@@ -262,7 +262,7 @@ export const createCloudAiCodeTools = () => [
   defineAiTool({
     name: "code_present",
     description:
-      "Show an HTML app as a card in this chat after a passing code_check for exactly these files and table definitions. Pass files (index.html plus optional style.css and app.js) for a one-off app without saved data, or the id of a saved app to run it live with its data. The person starts the card with a click. Static problems such as CDN scripts, inline handlers or a missing index.html are rejected before anything is saved. For a reusable app beside the chat use code_open.",
+      "Show a saved Studio app as a card in this chat: pass its id after a passing code_check for its current files and tables; it runs live with its data, and the person starts the card with a click. Every app, calculator, converter, form or tool the person asks for is a Studio app created with code_create; code_open shows it beside the chat instead. files (index.html plus optional style.css and app.js) instead of id show a throwaway card that is not saved and does not appear in Studio: only when the person explicitly asks for a preview they do not want to keep, after a passing code_check for exactly these files. Static problems such as CDN scripts, inline handlers or a missing index.html are rejected before anything is saved.",
     inputSchema: CodePresentInput,
     outputSchema: z.json(),
     approval: "never",

package/src/ai/memories.ts

@@ -7,6 +7,10 @@ export const AI_MEMORY_CONTENT_MAX_CHARS = 500;
 export const AI_MEMORY_HOT_MAX_ITEMS = 20;
 export const AI_MEMORY_HOT_MAX_CHARS = 6_000;
 
+// PostgreSQL stores at most 16,383 word positions per tsvector; a parsed token takes at least
+// one character. 12,000 characters keep every position distinct for the stop-word pairing below.
+const AI_MEMORY_RELEVANCE_MAX_CHARS = 12_000;
+
 export type AiMemoryKind = "fact" | "preference" | "workflow";
 export type AiMemoryPriority = "normal" | "pinned";
 export type AiMemorySource = "user" | "agent" | "background";
@@ -131,6 +135,49 @@ const listActive = async (userId: string, limit: number): Promise<AiMemory[]> =>
   return rows.map(toMemory);
 };
 
+const selectRelevant = async (input: { userId: string; text: string; total: number; limit: number }): Promise<AiMemory[]> => {
+  const text = (
+    input.text.length > AI_MEMORY_RELEVANCE_MAX_CHARS
+      ? `${input.text.slice(0, AI_MEMORY_RELEVANCE_MAX_CHARS / 2)}\n${input.text.slice(-AI_MEMORY_RELEVANCE_MAX_CHARS / 2)}`
+      : input.text
+  ).trim();
+  if (!text) return [];
+
+  const rows = await sql<MemoryRow[]>`
+    WITH english AS (
+      SELECT position, token.lexeme
+      FROM unnest(to_tsvector('english', ${text}::text)) AS token, unnest(token.positions) AS position
+    ), german AS (
+      SELECT position, token.lexeme
+      FROM unnest(to_tsvector('german', ${text}::text)) AS token, unnest(token.positions) AS position
+    ), words AS (
+      -- Both configurations parse the same tokens, so a position missing in one holds that language's stop word.
+      SELECT row_number() OVER () AS word, english, german
+      FROM (SELECT DISTINCT english.lexeme AS english, german.lexeme AS german FROM english JOIN german USING (position)) AS pairs
+    ), lexemes AS (
+      SELECT DISTINCT words.word, lexeme FROM words, unnest(ARRAY[words.english, words.german]) AS lexeme
+    ), matches AS (
+      SELECT DISTINCT memory.id, lexemes.word
+      FROM ai.memories AS memory
+      CROSS JOIN LATERAL unnest(tsvector_to_array(memory.stem_document)) AS document(lexeme)
+      JOIN lexemes ON lexemes.lexeme = document.lexeme
+      WHERE memory.user_id = ${input.userId}::uuid AND memory.deleted_at IS NULL AND memory.superseded_by_id IS NULL
+    ), scores AS (
+      -- A word found in fewer of the user's memories says more about relevance.
+      SELECT id, sum(ln((${input.total} + 1)::float8 / matching)) AS score
+      FROM (SELECT id, count(*) OVER (PARTITION BY word) AS matching FROM matches) AS weighted
+      GROUP BY id
+    )
+    SELECT memory.id, memory.short_id, memory.user_id, memory.kind, memory.content, memory.priority, memory.source,
+           memory.source_conversation_id, memory.source_message_id, memory.resource_type, memory.resource_id,
+           memory.created_at, memory.updated_at
+    FROM ai.memories AS memory JOIN scores ON scores.id = memory.id
+    ORDER BY scores.score DESC, memory.updated_at DESC, memory.id ASC
+    LIMIT ${input.limit}
+  `;
+  return rows.map(toMemory);
+};
+
 const searchRows = async (input: { userId: string; query: string; limit: number; backend: SearchBackend }): Promise<AiMemory[]> => {
   const query = input.query.trim();
   if (!query) return listActive(input.userId, input.limit);
@@ -609,7 +656,7 @@ export const aiMemories = {
 
     const [pinned, relevant, recent] = await Promise.all([
       listActive(userId, 50).then((items) => items.filter((item) => item.priority === "pinned")),
-      search({ userId, query, limit: 40 }),
+      selectRelevant({ userId, text: query, total: count, limit: 40 }),
       listActive(userId, 40),
     ]);
     const seen = new Set<string>();