@k2b/cloud 0.33.0 → 0.35.0

package/package.json

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

package/src/_internal/app-presentation.ts

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

package/src/_internal/define-app.ts

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

package/src/_internal/registry.ts

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

package/src/_internal/widget-declarations.ts

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

package/src/_internal/widget-settings.ts

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

package/src/ai/capabilities.ts

@@ -15,8 +15,8 @@ import {
   type CapabilityActionManifest,
   type CapabilityActionReview,
   type CapabilityQueryManifest,
-  CloudResourceRefSchema,
   cloudResourceRefAppId,
+  LinkedCloudResourceReferenceSchema,
   resolveCapabilityResourceReader,
 } from "../contracts/capabilities";
 import type { CapabilityRegistryEntry } from "../contracts/registry";
@@ -29,6 +29,7 @@ import { recordRejectedAiCapability } from "./capability-execution";
 import { CODE_SOURCE_TOOLS } from "./code-source-contracts";
 import { createCodeSourceTool } from "./code-source-tools";
 import { CLOUD_AI_DEFERRED_BUILTIN_TOOL_NAMES } from "./default-tools";
+import { addCloudResourceHrefs } from "./resource-refs";
 import { type AiToolPreparationContext, defineAiTool, type PreparedAiTools, prepareAiTools } from "./tools";
 import type { AiConversationService, AiRuntimeTool, AiToolPresentation } from "./types";
 
@@ -424,6 +425,7 @@ const SCHEMA_KEYS = new Set([
   "required",
   "items",
   "prefixItems",
+  "additionalItems",
   "additionalProperties",
   "anyOf",
   "oneOf",
@@ -434,29 +436,139 @@ const SCHEMA_KEYS = new Set([
   "definitions",
 ]);
 
-const reduceSchemaValue = (value: unknown, key?: string): unknown => {
-  if (key === "const") return structuredClone(value);
+type SchemaReductionContext = {
+  root: Record<string, unknown>;
+  mirrorNames: Map<string, string>;
+  mirrors: Record<string, Record<string, unknown>>;
+};
+
+/** A local reference into the input schema: the root (`#`) or one of its `$defs` or `definitions`. */
+const localReference = (
+  reference: unknown,
+  root: Record<string, unknown>,
+): { identity: string; keyword: string; name: string; schema: unknown } | null => {
+  if (reference === "#") {
+    const { $defs: _defs, definitions: _definitions, ...schema } = root;
+    return { identity: "#", keyword: "$defs", name: "root", schema };
+  }
+  const match = typeof reference === "string" ? /^#\/(\$defs|definitions)\/([^/]+)$/.exec(reference) : null;
+  if (!match) return null;
+  const [, keyword, encodedName] = match;
+  const name = encodedName!.replace(/~1/g, "/").replace(/~0/g, "~");
+  const definitions = root[keyword!];
+  if (!definitions || typeof definitions !== "object" || !Object.hasOwn(definitions, name)) return null;
+  return { identity: `${keyword}/${name}`, keyword: keyword!, name, schema: Reflect.get(definitions, name) };
+};
+
+/** Whether a raw schema reaches a tuple; `visited` keeps each definition to one visit per question. */
+const containsTuple = (value: unknown, context: SchemaReductionContext, key?: string, visited = new Set<string>()): boolean => {
+  if (key === "const" || key === "enum" || key === "default" || key === "required" || key === "type") return false;
+  if (Array.isArray(value)) return value.some((item) => containsTuple(item, context, undefined, visited));
+  if (!value || typeof value !== "object") return false;
+  if (key === "properties" || key === "$defs" || key === "definitions") {
+    return Object.values(value).some((schema) => containsTuple(schema, context, undefined, visited));
+  }
+  if (Object.hasOwn(value, "prefixItems") || Array.isArray(Reflect.get(value, "items"))) return true;
+  const reference = localReference(Reflect.get(value, "$ref"), context.root);
+  if (reference && !visited.has(reference.identity)) {
+    visited.add(reference.identity);
+    if (containsTuple(reference.schema, context, undefined, visited)) return true;
+  }
+  return Object.entries(value).some(([childKey, childValue]) => containsTuple(childValue, context, childKey, visited));
+};
+
+const reduceSchemaValue = (value: unknown, context: SchemaReductionContext, key?: string, merged = false): unknown => {
+  if (key === "const" || key === "default") return structuredClone(value);
   if (Array.isArray(value)) {
     if (key === "required" || key === "enum" || key === "type") return structuredClone(value);
-    return value.map((item) => reduceSchemaValue(item));
+    return value.map((item) => reduceSchemaValue(item, context, undefined, merged));
   }
   if (!value || typeof value !== "object") return value;
+  if (key === "properties" || key === "$defs" || key === "definitions") {
+    return Object.fromEntries(Object.entries(value).map(([name, schema]) => [name, reduceSchemaValue(schema, context, undefined, merged)]));
+  }
 
   const output: Record<string, unknown> = {};
   for (const [childKey, childValue] of Object.entries(value)) {
-    if (key === "properties" || key === "$defs" || key === "definitions") {
-      output[childKey] = reduceSchemaValue(childValue);
-      continue;
+    if (!SCHEMA_KEYS.has(childKey) || (merged && childKey === "default")) continue;
+    // Tuple widening can make surrounding union branches overlap, so their defaults belong to the app.
+    const unionMerged =
+      merged ||
+      ((childKey === "anyOf" || childKey === "oneOf") &&
+        Array.isArray(childValue) &&
+        childValue.some((branch) => containsTuple(branch, context)));
+    output[childKey] = reduceSchemaValue(childValue, context, childKey, unionMerged);
+  }
+  if (output.oneOf !== undefined) {
+    if (output.anyOf === undefined) output.anyOf = output.oneOf;
+    else {
+      output.allOf = [...(Array.isArray(output.allOf) ? output.allOf : []), { anyOf: output.anyOf }, { anyOf: output.oneOf }];
+      delete output.anyOf;
     }
-    if (!SCHEMA_KEYS.has(childKey)) continue;
-    output[childKey] = reduceSchemaValue(childValue, childKey);
+    delete output.oneOf;
+  }
+
+  const positions = Array.isArray(output.prefixItems) ? output.prefixItems : Array.isArray(output.items) ? output.items : null;
+  if (positions) {
+    const rest = Array.isArray(output.prefixItems) ? output.items : output.additionalItems;
+    // Extra items of an open tuple may be anything, so the AI side must not narrow them to the positions.
+    const schemas = rest === undefined || rest === true ? [] : rest === false ? positions : [...positions, rest];
+    // Position-erased branches must leave defaults to the app's authoritative tuple schema.
+    const mergedSchemas = schemas.some((schema) => JSON.stringify(schema) !== JSON.stringify(schemas[0]))
+      ? schemas.map((schema) => reduceSchemaValue(schema, context, undefined, true))
+      : schemas;
+    const distinct = mergedSchemas.filter(
+      (schema, index) => mergedSchemas.findIndex((candidate) => JSON.stringify(candidate) === JSON.stringify(schema)) === index,
+    );
+    output.items = distinct.length === 0 ? {} : distinct.length === 1 ? distinct[0] : { anyOf: distinct };
+    if (rest === false)
+      output.maxItems = Math.min(typeof output.maxItems === "number" ? output.maxItems : positions.length, positions.length);
+  }
+  delete output.prefixItems;
+  delete output.additionalItems;
+  if (output.items === false) output.maxItems = 0;
+  // Zod drops array bounds without an item schema, so "any item" stays an empty schema.
+  if (typeof output.items === "boolean") output.items = {};
+  const reference = merged ? localReference(output.$ref, context.root) : null;
+  if (reference) {
+    const { identity, keyword, name } = reference;
+    const definitions = context.root[keyword];
+    const mirrors = context.mirrors[keyword] ?? {};
+    context.mirrors[keyword] = mirrors;
+    let mirrorName = context.mirrorNames.get(identity);
+    if (mirrorName === undefined) {
+      mirrorName = `${name}.ai`;
+      for (
+        let suffix = 1;
+        (definitions && typeof definitions === "object" && Object.hasOwn(definitions, mirrorName)) || Object.hasOwn(mirrors, mirrorName);
+        suffix++
+      ) {
+        mirrorName = `${name}.ai${suffix}`;
+      }
+      // Reserve the mirror before descending so recursive refs never reach default-bearing originals.
+      context.mirrorNames.set(identity, mirrorName);
+      mirrors[mirrorName] = {};
+      mirrors[mirrorName] = reduceSchemaValue(reference.schema, context, undefined, true);
+    }
+    output.$ref = `#/${keyword}/${mirrorName.replace(/~/g, "~0").replace(/\//g, "~1")}`;
   }
   return output;
 };
 
-/** Keep the provider-useful shape while leaving authoritative validation in the target app. */
-export const reduceAiCapabilityInputSchema = (schema: Record<string, unknown>): Record<string, unknown> =>
-  reduceSchemaValue(schema) as Record<string, unknown>;
+/**
+ * Keep the provider-useful shape while leaving authoritative validation in the target app.
+ * Tuples reach the model as bounded arrays of their item schemas and `oneOf` as `anyOf`, because loosened branches may
+ * overlap; the app still validates exact tuple positions and exclusive unions.
+ */
+export const reduceAiCapabilityInputSchema = (schema: Record<string, unknown>): Record<string, unknown> => {
+  const context: SchemaReductionContext = { root: schema, mirrorNames: new Map(), mirrors: {} };
+  const reduced = reduceSchemaValue(schema, context) as Record<string, unknown>;
+  for (const [keyword, mirrors] of Object.entries(context.mirrors)) {
+    const definitions = reduced[keyword];
+    reduced[keyword] = { ...(definitions && typeof definitions === "object" ? definitions : {}), ...mirrors };
+  }
+  return reduced;
+};
 
 export const aiCapabilityInputSchema = (schema: Record<string, unknown>): z.ZodType =>
   z.fromJSONSchema(reduceAiCapabilityInputSchema(schema));
@@ -638,6 +750,7 @@ export const createAiToolMetaTools = (input: {
 };
 
 export const createLoadedAiCapabilityTools = (input: {
+  apps: readonly CapabilityRegistryEntry[];
   catalog: readonly AiCapabilityCatalogEntry[];
   loadedNames: readonly string[];
   actor: RequestActor;
@@ -686,7 +799,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 +814,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 +831,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 +973,7 @@ export const createAiToolResolver =
       ...activeBuiltIns,
       ...(input.execute
         ? createLoadedAiCapabilityTools({
+            apps: registry,
             catalog: capabilityCatalog,
             loadedNames,
             actor: input.actor,

package/src/ai/firecrawl-tools.ts

@@ -1,8 +1,8 @@
-import { isIP } from "node:net";
 import { type ToolContext, truncateMiddle } from "@k2b/nessi";
 import { z } from "zod";
 import type { RequestActor } from "../server";
 import { coreSettings } from "../services";
+import { isUnsafeNetworkAddress, isUnsafeNetworkHostname, parseNetworkAddress } from "../shared/network-address";
 import { AI_WEBSITE_APPROVAL_TOOL, aiTurnAllowsWebsiteApprovals, aiWebsiteApprovalScope, findRememberedAiToolApproval } from "./approvals";
 import { aiConversations } from "./store";
 import { defineAiTool } from "./tools";
@@ -141,31 +141,6 @@ const truncate = (text: string, maxChars: number): { text: string; truncated: bo
   return { text: text.slice(0, Math.max(0, maxChars)).trimEnd(), truncated: true };
 };
 
-const isPrivateIpv4 = (hostname: string): boolean => {
-  const parts = hostname.split(".").map((part) => Number(part));
-  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return true;
-  const [a, b] = parts as [number, number, number, number];
-  if (a === 0 || a === 10 || a === 127) return true;
-  if (a === 100 && b >= 64 && b <= 127) return true;
-  if (a === 169 && b === 254) return true;
-  if (a === 172 && b >= 16 && b <= 31) return true;
-  if (a === 192 && (b === 0 || b === 168)) return true;
-  if (a === 198 && (b === 18 || b === 19)) return true;
-  return a >= 224;
-};
-
-const isPrivateIpv6 = (hostname: string): boolean => {
-  const normalized = hostname.replace(/^\[|\]$/g, "").toLowerCase();
-  return (
-    normalized === "::" ||
-    normalized === "::1" ||
-    normalized.startsWith("fc") ||
-    normalized.startsWith("fd") ||
-    normalized.startsWith("fe80:") ||
-    normalized.startsWith("2001:db8:")
-  );
-};
-
 export const assertPublicHttpUrl = (rawUrl: string): string => {
   let parsed: URL;
   try {
@@ -176,13 +151,11 @@ export const assertPublicHttpUrl = (rawUrl: string): string => {
   if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw new Error("URL must use http or https.");
 
   const hostname = parsed.hostname.toLowerCase();
-  if (!hostname || hostname === "localhost" || hostname.endsWith(".localhost")) {
+  if (isUnsafeNetworkHostname(hostname)) {
     throw new Error("URL host is not allowed.");
   }
 
-  const ipKind = isIP(hostname.replace(/^\[|\]$/g, ""));
-  if (ipKind === 4 && isPrivateIpv4(hostname)) throw new Error("URL must not point to a private IP address.");
-  if (ipKind === 6 && isPrivateIpv6(hostname)) throw new Error("URL must not point to a private IP address.");
+  if (parseNetworkAddress(hostname) && isUnsafeNetworkAddress(hostname)) throw new Error("URL must not point to a private IP address.");
   return parsed.toString();
 };
 

package/src/ai/resource-refs.ts

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