@k2b/cloud 0.40.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -29,6 +29,7 @@
     "./desktop/solid": "./src/desktop/solid.tsx",
     "./server": "./src/server/index.ts",
     "./server/*": "./src/server/*",
+    "./geo/ui": "./src/geo/ui.ts",
     "./browser": "./src/server/api-client.ts",
     "./browser/app-approval": "./src/browser/app-approval.ts",
     "./browser/app-badges": "./src/browser/app-badges.ts",
@@ -67,10 +68,12 @@
     "./ai": "./src/ai/index.ts",
     "./ai/admin": "./src/ai/admin.ts",
     "./ai/browser": "./src/ai/browser.ts",
+    "./ai/question-text": "./src/ai/question-text.ts",
     "./ai/live": "./src/ai/live.ts",
     "./ai/live-events": "./src/ai/live-events.ts",
     "./ai/runtime": "./src/ai/runtime.ts",
     "./ai/solid": "./src/ai/solid.ts",
+    "./ai/testing": "./src/ai/testing.ts",
     "./ai/tools": "./src/ai/runtime-tools.ts",
     "./ai/ui": "./src/ai/ui.tsx",
     "./account/ui": "./src/account/ui.ts",
@@ -107,13 +110,13 @@
     "@firecrawl/anydoc": "0.2.4",
     "@napi-rs/canvas": "1.0.9",
     "pdfjs-dist": "6.3.289",
-    "sharp": "0.35.4",
+    "sharp": "0.35.5",
     "@simplewebauthn/server": "14.0.3",
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
-    "@k2b/ssr": "0.18.0",
-    "@k2b/ui": "0.30.0",
+    "@k2b/ssr": "0.20.0",
+    "@k2b/ui": "0.32.0",
     "@k2b/stdlib": "0.30.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",
@@ -121,6 +124,7 @@
     "@modelcontextprotocol/sdk": "1.32.1",
     "bun-plugin-tailwind": "0.1.2",
     "hono-openapi": "1.3.3",
+    "entities": "8.0.0",
     "htmlparser2": "12.0.0",
     "jose": "6.2.12",
     "katex": "0.18.9",
@@ -149,7 +153,7 @@
     "babel-preset-solid": "1.9.15",
     "hono": "4.13.9",
     "playwright": "1.64.1",
-    "solid-js": "1.9.15",
+    "solid-js": "1.9.17",
     "typescript": "7.0.2",
     "zod": "4.6.5"
   },

package/src/_internal/bounded-json.ts

@@ -1,7 +1,8 @@
 export type BoundedJsonResult = { ok: true; data: unknown } | { ok: false; reason: "too_large" | "invalid_json" };
 
 /** Reads JSON without allowing a missing or forged Content-Length to bypass the byte cap. */
-export const readBoundedJson = async (message: Request | Response, maxBytes: number): Promise<BoundedJsonResult> => {
+export const readBoundedJson = async (message: Request | Response, maxBytes: number, signal?: AbortSignal): Promise<BoundedJsonResult> => {
+  signal?.throwIfAborted();
   const declared = message.headers.get("content-length");
   if (declared !== null) {
     const bytes = Number(declared);
@@ -13,6 +14,12 @@ export const readBoundedJson = async (message: Request | Response, maxBytes: num
 
   const reader = message.body?.getReader();
   if (!reader) return { ok: false, reason: "invalid_json" };
+  const aborted = () => {
+    // Releasing the caller must not wait for a stalled source's cancellation hook.
+    void reader.cancel(signal?.reason).catch(() => undefined);
+  };
+  signal?.addEventListener("abort", aborted, { once: true });
+  if (signal?.aborted) aborted();
 
   const chunks: Uint8Array[] = [];
   let total = 0;
@@ -28,10 +35,15 @@ export const readBoundedJson = async (message: Request | Response, maxBytes: num
       chunks.push(next.value);
     }
   } catch {
-    await reader.cancel().catch(() => undefined);
+    if (!signal?.aborted) await reader.cancel().catch(() => undefined);
     return { ok: false, reason: "invalid_json" };
+  } finally {
+    signal?.removeEventListener("abort", aborted);
+    reader.releaseLock();
   }
 
+  signal?.throwIfAborted();
+
   const bytes = new Uint8Array(total);
   let offset = 0;
   for (const chunk of chunks) {

package/src/_internal/capabilities.ts

@@ -1,3 +1,4 @@
+import { capabilityMessages } from "../shared/capability-messages";
 import { capabilityHash, projectSchema, stableJsonValue } from "./capability-schemas";
 
 export { capabilityHash } from "./capability-schemas";
@@ -8,6 +9,7 @@ import {
   CAPABILITY_ERROR_STATUSES,
   CAPABILITY_FRAMEWORK_ERROR_CODES,
   CAPABILITY_MAX_RESULT_BYTES,
+  CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
   CAPABILITY_PROTOCOL_VERSION,
   type CapabilityActionDefinition,
   type CapabilityActionManifest,
@@ -193,7 +195,7 @@ const providerPayload = (code: string, message: string, details?: Record<string,
 /** Serializes one framework-owned provider response exactly once and enforces the public byte bound. */
 export const serializeCapabilityProviderResult = (
   result: CapabilityProviderResult,
-  options: { nonIdempotentAction?: boolean } = {},
+  options: { nonIdempotentAction?: boolean; review?: boolean } = {},
 ): { body: string; status: number } => {
   if (options.nonIdempotentAction && !result.ok && result.error.code === CAPABILITY_FRAMEWORK_ERROR_CODES.invalidAppResponse) {
     const unknown = providerPayload(
@@ -206,7 +208,9 @@ export const serializeCapabilityProviderResult = (
   const payload = result.ok ? result.data : providerPayload(result.error.code, result.error.message, result.error.details);
   try {
     const body = JSON.stringify(payload);
-    if (new TextEncoder().encode(body).byteLength <= CAPABILITY_MAX_RESULT_BYTES) {
+    if (
+      new TextEncoder().encode(body).byteLength <= (options.review ? CAPABILITY_MAX_REVIEW_RESPONSE_BYTES : CAPABILITY_MAX_RESULT_BYTES)
+    ) {
       return { body, status: result.ok ? 200 : result.error.status };
     }
   } catch {
@@ -1091,7 +1095,48 @@ const schemaSemantics = (value: unknown): unknown => {
 const sameSchema = (left: unknown, right: unknown): boolean =>
   JSON.stringify(stableJsonValue(schemaSemantics(left))) === JSON.stringify(stableJsonValue(schemaSemantics(right)));
 
+const isSchemaObject = (value: unknown): value is JsonSchema => typeof value === "object" && value !== null && !Array.isArray(value);
+
+// Input recursion visits schema nodes explicitly. Never strip annotation names from
+// property maps or literal enum/const values when proving that old inputs survive.
+const inputConstraints = (schema: unknown): unknown =>
+  isSchemaObject(schema) ? Object.fromEntries(Object.entries(schema).filter(([key]) => key !== "title" && key !== "description")) : schema;
+const sameInputSchema = (left: unknown, right: unknown): boolean =>
+  JSON.stringify(stableJsonValue(inputConstraints(left))) === JSON.stringify(stableJsonValue(inputConstraints(right)));
+
+/** Only finite scalar tags: object/array equality and general schema exclusion are outside this proof. */
+const discriminatorValues = (schema: unknown): unknown[] | undefined => {
+  if (!isSchemaObject(schema)) return;
+  const values = Object.hasOwn(schema, "const") ? [schema.const] : schema.enum;
+  if (
+    Array.isArray(values) &&
+    values.length > 0 &&
+    values.every(
+      (value) =>
+        value === null || typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value)),
+    )
+  )
+    return values;
+};
+
+const disjointObjectBranches = (left: unknown, right: unknown): boolean => {
+  if (!isSchemaObject(left) || !isSchemaObject(right) || left.type !== "object" || right.type !== "object") return false;
+  const leftProperties = left.properties;
+  const rightProperties = right.properties;
+  const leftRequired = left.required;
+  const rightRequired = right.required;
+  if (!isSchemaObject(leftProperties) || !isSchemaObject(rightProperties) || !Array.isArray(leftRequired) || !Array.isArray(rightRequired))
+    return false;
+  return leftRequired.some((name) => {
+    if (typeof name !== "string" || !rightRequired.includes(name)) return false;
+    const leftValues = discriminatorValues(leftProperties[name]);
+    const rightValues = discriminatorValues(rightProperties[name]);
+    return Boolean(leftValues && rightValues && leftValues.every((value) => !rightValues.includes(value)));
+  });
+};
+
 const schemaEvolutionIssues = (previous: JsonSchema, next: JsonSchema, path: string, direction: "input" | "data"): string[] => {
+  const schemasMatch = direction === "input" ? sameInputSchema : sameSchema;
   for (const keyword of ["oneOf", "anyOf"] as const) {
     const previousBranches = previous[keyword];
     const nextBranches = next[keyword];
@@ -1100,9 +1145,25 @@ const schemaEvolutionIssues = (previous: JsonSchema, next: JsonSchema, path: str
     const nextRest = { ...next };
     delete previousRest[keyword];
     delete nextRest[keyword];
-    if (!sameSchema(previousRest, nextRest) || previousBranches.length !== nextBranches.length) {
-      return [`${path} changed`];
+    if (!schemasMatch(previousRest, nextRest)) return [`${path} changed`];
+    if (direction === "input") {
+      if (!previousBranches.every(isSchemaObject) || !nextBranches.every(isSchemaObject)) return [`${path} changed`];
+      if (nextBranches.length < previousBranches.length) return [`${path} changed`];
+      // anyOf is monotonic under branch additions. oneOf is not: a newly overlapping
+      // branch rejects previously valid input, even when the branch count stays the same.
+      if (
+        keyword === "oneOf" &&
+        !sameInputSchema(previousBranches, nextBranches) &&
+        !nextBranches.every((branch, index) => nextBranches.slice(index + 1).every((other) => disjointObjectBranches(branch, other)))
+      )
+        return [`${path} oneOf branches are not provably disjoint`];
+      return previousBranches.flatMap((branch, index) =>
+        nextBranches.some((candidate) => schemaEvolutionIssues(branch, candidate, path, direction).length === 0)
+          ? []
+          : [`${path} ${keyword}[${index}] was removed or narrowed`],
+      );
     }
+    if (previousBranches.length !== nextBranches.length) return [`${path} changed`];
     return previousBranches.flatMap((branch, index) =>
       schemaEvolutionIssues(branch as JsonSchema, nextBranches[index] as JsonSchema, `${path} ${keyword}[${index}]`, direction),
     );
@@ -1114,16 +1175,16 @@ const schemaEvolutionIssues = (previous: JsonSchema, next: JsonSchema, path: str
     const nextItems = nextRest.items;
     delete previousRest.items;
     delete nextRest.items;
-    const issues = sameSchema(previousRest, nextRest) ? [] : [`${path} constraints changed`];
+    const issues = schemasMatch(previousRest, nextRest) ? [] : [`${path} constraints changed`];
     if (previousItems && nextItems) {
       issues.push(...schemaEvolutionIssues(previousItems as JsonSchema, nextItems as JsonSchema, `${path} items`, direction));
-    } else if (!sameSchema(previousItems, nextItems)) {
+    } else if (!schemasMatch(previousItems, nextItems)) {
       issues.push(`${path} items changed`);
     }
     return issues;
   }
   if (previous.type !== "object" || next.type !== "object") {
-    return sameSchema(previous, next) ? [] : [`${path} changed`];
+    return schemasMatch(previous, next) ? [] : [`${path} changed`];
   }
   const issues: string[] = [];
   const previousRest = { ...previous };
@@ -1132,10 +1193,15 @@ const schemaEvolutionIssues = (previous: JsonSchema, next: JsonSchema, path: str
   delete previousRest.required;
   delete nextRest.properties;
   delete nextRest.required;
-  if (!sameSchema(previousRest, nextRest)) issues.push(`${path} constraints changed`);
+  if (!schemasMatch(previousRest, nextRest)) issues.push(`${path} constraints changed`);
 
   const previousProperties = (previous.properties ?? {}) as Record<string, JsonSchema>;
   const nextProperties = (next.properties ?? {}) as Record<string, JsonSchema>;
+  if (direction === "input" && (previous.additionalProperties !== false || previous.patternProperties !== undefined)) {
+    for (const name of Object.keys(nextProperties)) {
+      if (!Object.hasOwn(previousProperties, name)) issues.push(`${path}.${name} may constrain previously allowed additional input`);
+    }
+  }
   for (const [name, schema] of Object.entries(previousProperties)) {
     const nextSchema = nextProperties[name];
     if (!nextSchema) issues.push(`${path}.${name} was removed`);
@@ -1302,6 +1368,15 @@ export const validateCapabilityResult = (
   return { ok: true, data: parsed.data };
 };
 
+const cancelledInvocation = (locale: string) => ({
+  ok: false as const,
+  error: {
+    code: CAPABILITY_FRAMEWORK_ERROR_CODES.requestCancelled,
+    message: capabilityMessages(locale).requestCancelled,
+    status: 499 as const,
+  },
+});
+
 export const invokeCompiledCapability = async (params: {
   compiled: CompiledCapabilities;
   kind: "query" | "action";
@@ -1403,6 +1478,9 @@ export const invokeCompiledCapability = async (params: {
     )
       return { ok: false, error: { code: "VALIDATION_FAILED", message: "Unsupported search scope", status: 400 } };
   }
+  // Preparation can finish after the forwarding request was cancelled. Never
+  // cross into application code for the first time with an aborted invocation.
+  if (context.signal.aborted) return cancelledInvocation(context.locale);
   try {
     const invoked = await operation.definition.run(input.data, context);
     if (!invoked.ok) {
@@ -1496,6 +1574,7 @@ export const reviewCompiledCapability = async (params: {
       },
     };
   }
+  if (params.context.signal.aborted) return cancelledInvocation(params.context.locale);
   try {
     const reviewed = await operation.definition.review(input.data, params.context);
     if (!reviewed.ok) {

package/src/_internal/capability-reviews.ts

@@ -67,8 +67,14 @@ export const capabilityActionReviewIssues = (review: unknown, context: Capabilit
       data.links,
       // A per-call reason never lifts the declared `sends` completeness rule.
       data.ask === "sends" || ("ask" in context.policy && context.policy.ask === "sends"),
+      Boolean(data.content),
     ),
   );
+  if (data.content?.kind === "message" && "ask" in context.policy && context.policy.ask === "sends") {
+    if (!data.content.from) issues.push("Full sends content requires from");
+    if (!data.content.to.length && !data.content.cc?.length && !data.content.bcc?.length)
+      issues.push("Full sends content requires a recipient");
+  }
   return [...new Set(issues)];
 };
 /** A receipt's own rules; completeness links are the result envelope's top-level `links`. */

package/src/_internal/capability-sentences.ts

@@ -465,7 +465,8 @@ const slotText = (slot: CapabilitySlot, context: CapabilitySlotSentenceContext,
     }
     case "person": {
       const total = slot.total ?? slot.people.length;
-      if (mode === "button") return total === 1 ? (slot.people[0]!.name ?? slot.people[0]!.address ?? "") : t.people({ count: total });
+      if (mode === "button")
+        return total === 1 ? plain(slot.people[0]!.name ?? slot.people[0]!.address ?? "", 24, "middle") : t.people({ count: total });
       const shown = mode === "full" ? slot.people : slot.people.slice(0, 3);
       const list = shown.map((person) =>
         mode === "chip" ? plain(person.name ?? person.address ?? "", 40, "middle") : capabilityPersonText(person),

package/src/_internal/capability-timeout.ts

@@ -0,0 +1,71 @@
+import type { Context } from "hono";
+import { REQUEST_IDLE_TIMEOUT_SECONDS, setRequestTimeout } from "../server/request-timeout";
+
+type InvocationKind = "query" | "action" | "review";
+export type CapabilityTimeoutOverrides = { queryTimeoutMs?: number; actionTimeoutMs?: number; reviewTimeoutMs?: number };
+
+/** Discovery and recent-resource reads keep their short, independent budget. */
+export const CAPABILITY_DISCOVERY_TIMEOUT_MS = 15_000;
+
+export const capabilityTimeoutMs = (kind: InvocationKind, overrides: CapabilityTimeoutOverrides = {}): number => {
+  if (kind === "review") return overrides.reviewTimeoutMs ?? 15_000;
+  return kind === "query" ? (overrides.queryTimeoutMs ?? 45_000) : (overrides.actionTimeoutMs ?? 30_000);
+};
+
+/** Only JSON request owners use this; streaming responses own their idle lifecycle. */
+export const withCapabilityRequestTimeout = async <T>(c: Context, kind: InvocationKind, run: () => Promise<T>): Promise<T> => {
+  setRequestTimeout(c, Math.ceil(capabilityTimeoutMs(kind) / 1000) + REQUEST_IDLE_TIMEOUT_SECONDS);
+  try {
+    return await run();
+  } finally {
+    setRequestTimeout(c, REQUEST_IDLE_TIMEOUT_SECONDS);
+  }
+};
+
+/** One monotonic budget, including preparation. Waiting reads never start after it expires. */
+export const createCapabilityDeadline = (timeoutMs: number, caller: AbortSignal) => {
+  const controller = new AbortController();
+  const expiresAt = performance.now() + timeoutMs;
+  const expire = () => controller.abort(new DOMException("Capability deadline exceeded", "TimeoutError"));
+  const timer = setTimeout(expire, timeoutMs);
+  const signal = AbortSignal.any([caller, controller.signal]);
+  const check = () => {
+    if (performance.now() >= expiresAt) expire();
+    signal.throwIfAborted();
+  };
+  const wait = <T>(read: () => Promise<T>): Promise<T> => {
+    check();
+    return new Promise<T>((resolve, reject) => {
+      const aborted = () => reject(signal.reason);
+      signal.addEventListener("abort", aborted, { once: true });
+      // Observe both outcomes even after cancellation; a late read cannot resume dispatch.
+      Promise.resolve()
+        .then(() => {
+          check();
+          return read();
+        })
+        .then(
+          (result) => {
+            signal.removeEventListener("abort", aborted);
+            try {
+              check();
+              resolve(result);
+            } catch (error) {
+              reject(error);
+            }
+          },
+          (error) => {
+            signal.removeEventListener("abort", aborted);
+            reject(error);
+          },
+        );
+    });
+  };
+  return {
+    signal,
+    check,
+    wait,
+    remainingMs: () => Math.max(1, Math.ceil(expiresAt - performance.now())),
+    clear: () => clearTimeout(timer),
+  };
+};