@k2b/cloud 0.37.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -19,6 +19,7 @@
     "!src/**/*.test.tsx",
     "!src/**/*.integration.test.ts",
     "!src/**/*.test-fixture.ts",
+    "!src/**/*.test-fixture.tsx",
     "!scripts/**/*.test.ts",
     "!scripts/runtime-recovery-*.ts"
   ],
@@ -107,7 +108,7 @@
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
     "@k2b/ssr": "0.17.0",
-    "@k2b/ui": "0.27.0",
+    "@k2b/ui": "0.28.0",
     "@k2b/stdlib": "0.29.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",
@@ -115,6 +116,7 @@
     "@modelcontextprotocol/sdk": "1.32.1",
     "bun-plugin-tailwind": "0.1.2",
     "hono-openapi": "1.3.3",
+    "htmlparser2": "12.0.0",
     "jose": "6.2.12",
     "katex": "0.18.9",
     "liquidjs": "10.29.0",

package/src/_internal/help-catalog.ts

@@ -1,5 +1,124 @@
+import { i18n } from "@k2b/stdlib";
+import { formatShortcut } from "@k2b/ui";
+import type { Token } from "marked";
 import type { HelpArticle } from "../services/help/types";
-import { markdownToPlainText } from "../shared/markdown";
+import { parseHelpReference } from "../shared/help";
+import { lexHelpMarkdown, markdownToPlainText } from "../shared/markdown";
+
+const helpAgentMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: { apple: ({ shortcut }: { shortcut: string }) => `${shortcut} on Mac` },
+    de: { apple: ({ shortcut }) => `${shortcut} auf dem Mac` },
+  },
+});
+
+const helpLinkLabel = (source: string, fallback: string): string => {
+  // Index backtick runs once so unmatched runs cannot repeatedly scan the remaining source.
+  const backticks = new Map<number, { positions: number[]; next: number }>();
+  for (const run of source.matchAll(/`+/g)) {
+    const length = run[0].length;
+    if (!backticks.has(length)) backticks.set(length, { positions: [], next: 0 });
+    backticks.get(length)!.positions.push(run.index);
+  }
+  let depth = 0;
+  for (let index = 1; index < source.length; index++) {
+    const char = source[index];
+    if (char === "\\") index++;
+    else if (char === "`") {
+      let end = index + 1;
+      while (source[end] === "`") end++;
+      const length = end - index;
+      const runs = backticks.get(length);
+      if (runs) {
+        while (runs.next < runs.positions.length && runs.positions[runs.next]! <= index) runs.next++;
+      }
+      const closing = runs?.positions[runs.next];
+      index = closing === undefined ? end - 1 : closing + length - 1;
+    } else if (char === "[") depth++;
+    else if (char === "]") {
+      if (depth === 0) return source.slice(1, index);
+      depth--;
+    }
+  }
+  return fallback;
+};
+
+/** Portable source for agents and Copy as Markdown; code is kept verbatim. */
+export const helpAgentMarkdown = (
+  article: Pick<HelpArticle, "markdown" | "locale" | "appId" | "links">,
+  tokens: readonly Token[] = lexHelpMarkdown(article.markdown, article.locale),
+): string => {
+  const { t } = helpAgentMessages.resolve([article.locale]);
+  const rewriteChildren = (raw: string, children: readonly Token[]): string => {
+    let offset = 0;
+    let result = "";
+    for (const child of children) {
+      let start = raw.indexOf(child.raw, offset);
+      let source = child.raw;
+      if (start < 0 && child.raw.includes("|")) {
+        source = child.raw.replaceAll("|", "\\|");
+        start = raw.indexOf(source, offset);
+      }
+      // Marked removes quote markers and list indentation from child block sources.
+      if (start < 0 && child.raw.includes("\n")) {
+        const pattern = child.raw
+          .split("\n")
+          .map((line, index) => (index > 0 ? line.replace(/^[ \t]+/, "") : line).replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+          .join("\\r?\\n[ \\t>]*");
+        const match = new RegExp(pattern).exec(raw.slice(offset));
+        if (match) {
+          start = offset + match.index;
+          source = match[0];
+        }
+      }
+      if (start < 0) break;
+      result += raw.slice(offset, start) + rewrite(child, source);
+      offset = start + source.length;
+    }
+    return result + raw.slice(offset);
+  };
+  const rewrite = (token: Token, source: string): string => {
+    if (token.type === "code" || token.type === "codespan") return source;
+    if (token.type === "helpKbd") {
+      const keys = String(token.keys);
+      const other = formatShortcut(keys, { platform: "other", locale: article.locale });
+      const apple = formatShortcut(keys, { platform: "apple", locale: article.locale }).label;
+      // Key labels such as | or ` stay text in a table cell or a sentence.
+      const escape = (text: string) => text.replace(/[\\`*_[\]|<>~]/g, "\\$&");
+      // A key without a platform modifier reads by its name: "Enter", not "↵".
+      return other.label === apple ? escape(other.name) : `${escape(other.label)} (${t.apple({ shortcut: escape(apple) })})`;
+    }
+    if (token.type === "helpDetails") {
+      const newline = source.includes("\r\n") ? "\r\n" : "\n";
+      const bodyStart = source.indexOf("\n") + 1;
+      const closing = [...source.matchAll(/^[ \t>]*:::[ \t]*(?:\r?\n|$)/gm)].at(-1)!;
+      const body = source.slice(bodyStart, closing.index);
+      const prefix = body.match(/^[ \t>]+/)?.[0] ?? "";
+      const trailing = source.slice(closing.index + closing[0].length);
+      return `**${rewriteChildren(String(token.title), token.titleTokens ?? [])}**${newline}${prefix}${newline}${rewriteChildren(body, token.tokens ?? [])}${trailing}`;
+    }
+    if (token.type === "helpLabel") return rewriteChildren(source.replace(/\{icon="[a-z0-9-]+"\}$/, ""), token.tokens ?? []);
+    if (token.type === "link" && token.href.startsWith("help:")) {
+      const ref = parseHelpReference(token.href.slice(5));
+      const target = ref && article.links[`${ref.appId ?? article.appId}/${ref.documentId}`];
+      const label = rewriteChildren(helpLinkLabel(source, token.text), token.tokens ?? []);
+      return target ? `[${label}](${target.url}${ref.fragment})` : label;
+    }
+    const children =
+      token.type === "list"
+        ? token.items
+        : token.type === "table"
+          ? [...token.header, ...token.rows.flat()].flatMap((cell) => cell.tokens)
+          : "tokens" in token
+            ? (token.tokens ?? [])
+            : [];
+    const raw = rewriteChildren(source, children);
+    return token.type === "heading" ? raw.replace(/[ \t]+\{icon="[a-z0-9-]+"\}(?=[ \t]*\r?\n?$)/i, "") : raw;
+  };
+  return rewriteChildren(article.markdown, tokens);
+};
+
 export const HELP_SEARCH_MAX_LIMIT = 25;
 export const HELP_READ_MAX_CHARS = 7_000;
 const normalizeSearchText = (value: string): string =>
@@ -33,7 +152,7 @@ const boundedExcerpt = (markdown: string, terms: readonly string[]): string => {
   return `${start > 0 ? `${marker}\n\n` : ""}${body}${start + budget < markdown.length ? `\n\n${marker}` : ""}`;
 };
 
-export const selectHelpMarkdown = (markdown: string, query?: string): { markdown: string; truncated: boolean } => {
+export const selectHelpMarkdown = (markdown: string, query?: string, locale?: string): { markdown: string; truncated: boolean } => {
   // An exact heading identifies one complete reference section, even in short articles.
   const headingQuery = query?.trim().toLocaleLowerCase();
   const exact =
@@ -53,7 +172,7 @@ export const selectHelpMarkdown = (markdown: string, query?: string): { markdown
   const phrase = normalizeSearchText(query ?? "");
   const ranked = splitSections(markdown)
     .map((section, index) => {
-      const text = normalizeSearchText(markdownToPlainText(section));
+      const text = normalizeSearchText(markdownToPlainText(section, locale));
       const score = (phrase && text.includes(phrase) ? 10 : 0) + terms.filter((term) => text.includes(term)).length;
       return { section, index, score };
     })
@@ -79,7 +198,7 @@ export const readHelpArticle = (document: HelpArticle, query?: string) => ({
   documentId: document.documentId,
   title: document.title,
   description: document.description,
-  ...selectHelpMarkdown(document.markdown, query),
+  ...selectHelpMarkdown(helpAgentMarkdown(document), query, document.locale),
 });
 
 export const helpResourceUri = (appId: string, documentId: string): string =>

package/src/_internal/help.ts

@@ -2,28 +2,49 @@ import { createHash } from "node:crypto";
 import type { AppRegistryHelpSummary } from "../contracts/registry";
 import type { HelpDefinition } from "../server/help";
 import type { HelpCorpus, HelpDocument } from "../services/help/types";
+import { parseHelpReference } from "../shared/help";
+import { lexHelpMarkdown, walkHelpTokens } from "../shared/markdown";
 
 export const HELP_DOCUMENT_MAX_BYTES = 128 * 1024;
+// defineHelp documents are frozen; retain only their validated targets, not the token trees.
+export const helpLinkTargets = new WeakMap<object, readonly string[]>();
 export type CompiledHelp = { summary: AppRegistryHelpSummary; corpus: HelpCorpus };
 
 export const compileHelp = (input: { appId: string; basePath?: string; definition: HelpDefinition }): CompiledHelp => {
-  const compileDocuments = (source: HelpDefinition["documents"]): HelpDocument[] =>
-    source.map(({ id, title, icon, description, order, markdown, searchText }) => {
+  const baseIds = new Set(input.definition.documents.map((document) => document.id));
+  const compileDocuments = (source: HelpDefinition["documents"], locale: string): HelpDocument[] =>
+    source.map((document) => {
+      const { id, title, icon, description, order, kind, needs, next, related, markdown, searchText } = document;
       if (Buffer.byteLength(markdown) > HELP_DOCUMENT_MAX_BYTES) {
         throw new Error(`Help document "${id}" exceeds the ${HELP_DOCUMENT_MAX_BYTES}-byte limit`);
       }
-      return { id, title, icon, description, order, markdown, searchText };
+      const validate = (reference: string) => {
+        const ref = parseHelpReference(reference);
+        if (ref?.appId === input.appId && !baseIds.has(ref.documentId))
+          throw new Error(`Help locale "${locale}" document "${id}" has unknown reference "${reference}"`);
+      };
+      for (const reference of related) validate(reference);
+      const targets = helpLinkTargets.get(document);
+      if (targets) {
+        for (const target of targets) validate(target);
+      } else {
+        walkHelpTokens(lexHelpMarkdown(markdown, locale), (token) => {
+          if (token.type === "link" && token.href.startsWith("help:")) validate(token.href.slice(5));
+        });
+      }
+      return { id, title, icon, description, order, kind, needs, next, related, markdown, searchText };
     });
   const baseLocale = input.definition.baseLocale ?? "en";
-  const documents = compileDocuments(input.definition.documents);
+  const documents = compileDocuments(input.definition.documents, baseLocale);
   const documentsByLocale = Object.fromEntries(
     Object.entries(input.definition.documentsByLocale ?? {})
       .filter(([locale]) => locale !== baseLocale)
       .sort(([a], [b]) => a.localeCompare(b))
-      .map(([locale, docs]) => [locale, compileDocuments(docs)]),
+      .map(([locale, docs]) => [locale, compileDocuments(docs, locale)]),
   );
+  // A revision bump republishes every corpus, here to fill the new metadata columns.
   const manifestHash = createHash("sha256")
-    .update(JSON.stringify({ revision: 1, appId: input.appId, baseLocale, documents, documentsByLocale }))
+    .update(JSON.stringify({ revision: 2, appId: input.appId, baseLocale, documents, documentsByLocale }))
     .digest("hex");
   return {
     summary: { manifestHash, pageBase: `${input.basePath?.replace(/\/$/, "") ?? ""}/help`, baseLocale },

package/src/account/Avatar.tsx

@@ -1,10 +1,14 @@
 import { Avatar, type AvatarProps } from "@k2b/ui";
 import type { JSX } from "solid-js";
 
-export type CloudAvatarProps = Omit<AvatarProps, "name" | "src"> & {
+/** Who an avatar stands for; agents and service accounts are square, people round. */
+export type CloudAvatarKind = "user" | "service_account" | "system";
+
+export type CloudAvatarProps = Omit<AvatarProps, "name" | "src" | "shape" | "icon"> & {
   username: string;
   userId?: string | null;
   avatarHash?: string | null;
+  kind?: CloudAvatarKind;
 };
 
 const avatarSource = (userId?: string | null, avatarHash?: string | null): string | undefined => {
@@ -12,14 +16,28 @@ const avatarSource = (userId?: string | null, avatarHash?: string | null): strin
   return `/api/accounts/users/${encodeURIComponent(userId)}/avatar?rev=${encodeURIComponent(avatarHash)}`;
 };
 
+/** The URL of a person's uploaded picture, or undefined when there is none. */
+export const cloudAvatarSource = avatarSource;
+
+const KIND_ICON: Record<CloudAvatarKind, string | undefined> = {
+  user: undefined,
+  service_account: "ti ti-robot",
+  system: "ti ti-settings-automation",
+};
+
+/** One avatar for every Cloud surface: the uploaded picture when there is one, otherwise initials. */
 export function CloudAvatar(props: CloudAvatarProps): JSX.Element {
+  const kind = () => props.kind ?? "user";
   return (
     <Avatar
       name={props.username}
-      src={avatarSource(props.userId, props.avatarHash)}
+      src={kind() === "user" ? avatarSource(props.userId, props.avatarHash) : undefined}
+      icon={KIND_ICON[kind()]}
+      shape={kind() === "user" ? "circle" : "square"}
       alt={props.alt}
       fallback={props.fallback}
       size={props.size}
+      ring={props.ring}
       loading={props.loading}
       class={props.class}
       style={props.style}

package/src/account/ui.ts

@@ -1,3 +1,3 @@
-export { CloudAvatar, type CloudAvatarProps } from "./Avatar";
+export { CloudAvatar, type CloudAvatarKind, type CloudAvatarProps, cloudAvatarSource } from "./Avatar";
 export { type AvatarUploadDialogOptions, openAvatarUploadDialog } from "./avatar-upload-dialog";
 export { default as EntitySearch, type EntitySearchPrincipal } from "./EntitySearch";

package/src/ai/browser.ts

@@ -25,6 +25,7 @@ export {
   cloudAiChartRenderOptions,
   cloudAiChartRows,
   cloudAiChartTable,
+  cloudAiChartTooltip,
   cloudAiChartXValueFormat,
   cloudAiNumberFormatters,
 } from "./chart-block";

package/src/ai/chart-block.ts

@@ -527,15 +527,38 @@ export type CloudAiChartColumn = { id: string; label: string; numeric: boolean }
 export type CloudAiChartRow = { key: string; cells: Record<string, string>; values: Record<string, string | number> };
 export type CloudAiChartTable = { columns: CloudAiChartColumn[]; rows: CloudAiChartRow[] };
 
+/** The first text column titles the tooltip; the other columns become rows, matching the table in every host. */
+export function cloudAiChartTooltip(
+  columns: CloudAiChartColumn[],
+  row: CloudAiChartRow,
+): { title?: string; rows: { label: string; value: string }[] } {
+  const [first, ...rest] = columns;
+  const named = first && !first.numeric;
+  return {
+    title: named ? row.cells[first.id] : undefined,
+    rows: (named ? rest : columns)
+      .filter((column) => column.id in row.cells)
+      .map((column) => ({ label: column.label, value: row.cells[column.id] ?? "" })),
+  };
+}
+
 /**
  * Builds the data table mark by mark, in the order the renderer emits them, so the chat block fills it from the same
  * drawing that shows the chart.
  */
-export function cloudAiChartRows(input: CloudAiChartInput, locale: string) {
+export function cloudAiChartRows(
+  input: CloudAiChartInput,
+  locale: string,
+  options: { formats?: { x?: (v: number) => string; y?: (v: number) => string; value?: (v: number) => string } } = {},
+) {
   const t = labels.resolve([locale]).t;
   const format = formats(input, locale);
+  const valueFormat = input.tooltip?.format
+    ? cloudAiNumberFormatters(input.tooltip.format, locale).value
+    : (options.formats?.value ?? (input.kind === "histogram" ? undefined : options.formats?.y) ?? format.value);
+  const xFormat = options.formats?.x ?? format.x.value;
   const series = seriesOf(input);
-  const countFormat = cloudAiNumberFormatters(undefined, locale).value;
+  const countFormat = (input.kind === "histogram" ? options.formats?.y : undefined) ?? cloudAiNumberFormatters(undefined, locale).value;
   const percent = new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 1 });
   const unit = "unit" in input && input.unit ? ` ${input.unit}` : "";
   const columns = new Map<string, CloudAiChartColumn>();
@@ -575,26 +598,34 @@ export function cloudAiChartRows(input: CloudAiChartInput, locale: string) {
           "x",
           input.kind === "sparkline" || input.kind === "stat" ? "#" : header,
           value,
-          input.kind === "sparkline" || input.kind === "stat" ? String(value + 1) : format.x.value(value),
+          input.kind === "sparkline" || input.kind === "stat" ? String(value + 1) : xFormat(value),
         );
       } else if (field.key === "y") {
         const header =
+          input.tooltip?.label ??
           (input.kind === "line" || input.kind === "scatter" ? input.yAxis?.label : undefined) ??
           (input.kind === "sparkline" || input.kind === "stat" ? t.value : "Y");
-        cell("y", header, value, format.value(value));
+        cell("y", header, value, valueFormat(value));
       } else if (field.key === "value")
-        cell("value", (input.kind === "bar" ? input.yAxis?.label : undefined) ?? t.value, value, `${format.value(value)}${unit}`);
-      else if (field.key === "delta") cell("delta", t.delta, value, `${value > 0 ? "+" : ""}${format.value(value)}`);
-      else if (field.key === "q1" || field.key === "q2" || field.key === "q3" || field.key === "whiskerLow" || field.key === "whiskerHigh")
-        cell(field.key, t[field.key], value, format.value(value));
-      else if (field.key === "percent") cell("percent", t.share, value, percent.format(value / 100));
-      else if (field.key === "from" || field.key === "to" || field.key === "count" || field.key === "min" || field.key === "max")
         cell(
-          field.key,
-          t[field.key],
+          "value",
+          input.tooltip?.label ?? (input.kind === "bar" ? input.yAxis?.label : undefined) ?? t.value,
           value,
-          `${field.key === "count" ? countFormat(value) : format.value(value)}${field.key === "min" || field.key === "max" ? unit : ""}`,
+          `${valueFormat(value)}${unit}`,
         );
+      else if (field.key === "delta") cell("delta", t.delta, value, `${value > 0 ? "+" : ""}${valueFormat(value)}`);
+      else if (field.key === "q1" || field.key === "q2" || field.key === "q3" || field.key === "whiskerLow" || field.key === "whiskerHigh")
+        cell(field.key, t[field.key], value, valueFormat(value));
+      else if (field.key === "percent") cell("percent", t.share, value, percent.format(value / 100));
+      else if (field.key === "from" || field.key === "to" || field.key === "count" || field.key === "min" || field.key === "max") {
+        const fieldFormat =
+          field.key === "count"
+            ? countFormat
+            : input.kind === "histogram" && (field.key === "from" || field.key === "to") && options.formats?.x
+              ? xFormat
+              : valueFormat;
+        cell(field.key, t[field.key], value, `${fieldFormat(value)}${field.key === "min" || field.key === "max" ? unit : ""}`);
+      }
     }
     const row = { key: cloudAiChartMarkKey(datum), cells, values };
     rows.push(row);

package/src/ai/chat/chart-block.tsx

@@ -9,7 +9,6 @@ import {
 } from "@k2b/ui";
 import { createMemo, createUniqueId, Index, type JSX, Show } from "solid-js";
 import {
-  type CloudAiChartColumn,
   type CloudAiChartRow,
   type CloudAiChartTable,
   cloudAiChartLegend,
@@ -17,21 +16,13 @@ import {
   cloudAiChartReferenceMark,
   cloudAiChartRenderOptions,
   cloudAiChartRows,
+  cloudAiChartTooltip,
   cloudAiChartXValueFormat,
 } from "../chart-block";
 import type { CloudAiChartInput } from "../default-tool-contracts";
 import { type CloudAiGroupView, parseCloudAiChartToolView } from "../view-block";
 import { aiChatMessages } from "./messages";
 
-const tooltip = (columns: CloudAiChartColumn[], row: CloudAiChartRow) => {
-  const [first, ...rest] = columns;
-  const named = first && !first.numeric;
-  return {
-    title: named ? row.cells[first.id] : undefined,
-    rows: (named ? rest : columns).map((column) => ({ label: column.label, value: row.cells[column.id] ?? "" })),
-  };
-};
-
 type Kind = CloudAiChartInput["kind"];
 type DrawnChart = { input: CloudAiChartInput; table: CloudAiChartTable; snapshot: ChartSnapshot; legend: ChartLegendEntry[] };
 
@@ -44,7 +35,7 @@ const drawChart = (input: CloudAiChartInput, locale: string): DrawnChart | null
       key: ({ datum }) => cloudAiChartMarkKey(datum),
       tooltip: ({ datum }) => {
         const row = rows.add(datum);
-        return tooltip(rows.columns(), row);
+        return cloudAiChartTooltip(rows.columns(), row);
       },
       reference: ({ datum }) => cloudAiChartReferenceMark(input, datum),
     });

package/src/ai/chat/messages.ts

@@ -137,6 +137,11 @@ const messages = i18n.define({
       revokeFailed: "Could not revoke. Try again.",
       revokeWebsiteFor: ({ host }: { host: string }) => `Revoke the approval for ${host}`,
       websiteRevoked: "Revoked. The next request asks again.",
+      fetchingFile: ({ name }: { name: string }) => `Fetching ${name}`,
+      fetchedFile: ({ name }: { name: string }) => `Fetched ${name}`,
+      fetchSource: "Source",
+      fetchSavedAs: "Saved as",
+      fetchReadableCopy: "Readable copy",
       details: "Details",
       hideDetails: "Hide details",
       moreOptions: ({ title }: { title: string }) => `More options for ${title}`,
@@ -446,6 +451,11 @@ const messages = i18n.define({
       revokeFailed: "Konnte nicht entzogen werden. Versuche es erneut.",
       revokeWebsiteFor: ({ host }: { host: string }) => `Freigabe für ${host} entziehen`,
       websiteRevoked: "Entzogen. Der nächste Abruf fragt wieder.",
+      fetchingFile: ({ name }) => `Lädt herunter: ${name}`,
+      fetchedFile: ({ name }) => `Heruntergeladen: ${name}`,
+      fetchSource: "Quelle",
+      fetchSavedAs: "Gespeichert als",
+      fetchReadableCopy: "Lesbare Kopie",
       details: "Details",
       hideDetails: "Details ausblenden",
       moreOptions: ({ title }) => `Weitere Optionen für ${title}`,

package/src/ai/chat/web-tools.tsx

@@ -136,15 +136,22 @@ export function WebExtractToolBlock(props: { block: ToolBlock }) {
   );
 }
 
-type FetchFileResult = { path: string; size: number; mediaType: string; url: string };
+type FetchFileResult = { path: string; size: number; mediaType: string; url: string; readablePath?: string };
 
+/** Results stored before readable copies existed have no `readable` field and still render. */
 const fetchFileResult = (value: unknown): FetchFileResult | null =>
   isRecord(value) &&
   typeof value.path === "string" &&
   typeof value.size === "number" &&
   typeof value.mediaType === "string" &&
   typeof value.url === "string"
-    ? { path: value.path, size: value.size, mediaType: value.mediaType, url: value.url }
+    ? {
+        path: value.path,
+        size: value.size,
+        mediaType: value.mediaType,
+        url: value.url,
+        ...(isRecord(value.readable) && typeof value.readable.path === "string" ? { readablePath: value.readable.path } : {}),
+      }
     : null;
 
 const filenameOf = (value: string): string => {
@@ -158,6 +165,8 @@ const filenameOf = (value: string): string => {
 
 /** Imported web file: source identity, useful metadata, and chat path without raw tool JSON. */
 export function FetchFileToolBlock(props: { block: ToolBlock }) {
+  const locale = useLocale();
+  const t = () => aiChatMessages(locale());
   const sourceUrl = () => (isRecord(props.block.args) && typeof props.block.args.url === "string" ? props.block.args.url : "");
   const result = () => fetchFileResult(props.block.result);
   const displayName = () => filenameOf(result()?.path ?? sourceUrl()) || "file";
@@ -172,7 +181,7 @@ export function FetchFileToolBlock(props: { block: ToolBlock }) {
       when={props.block.status === "completed" && result()}
       fallback={
         <Chat.Activity
-          label={`Fetching ${displayName()}`}
+          label={t().fetchingFile({ name: displayName() })}
           description={domainOf(sourceUrl())}
           leading={<Favicon url={sourceUrl()} fallbackIcon="ti ti-world-download" />}
           busy
@@ -183,19 +192,27 @@ export function FetchFileToolBlock(props: { block: ToolBlock }) {
         <AiToolActivity
           blockId={props.block.id}
           leading={<Favicon url={sourceUrl() || file().url} fallbackIcon="ti ti-world-download" />}
-          label={`Fetched ${displayName()}`}
+          label={t().fetchedFile({ name: displayName() })}
           description={description()}
           bodyInset={false}
         >
           <dl class="grid w-full min-w-0 grid-cols-[max-content_minmax(0,1fr)] gap-x-3 gap-y-1 rounded-md bg-zinc-100/70 px-2 py-1.5 text-xs [box-shadow:var(--ui-control-recess)] dark:bg-zinc-950/70">
-            <dt class="font-medium text-dimmed">Source</dt>
+            <dt class="font-medium text-dimmed">{t().fetchSource}</dt>
             <dd class="min-w-0 truncate">
               <a href={file().url} target="_blank" rel="noreferrer noopener" class="text-secondary hover:text-primary">
                 {file().url}
               </a>
             </dd>
-            <dt class="font-medium text-dimmed">Saved as</dt>
+            <dt class="font-medium text-dimmed">{t().fetchSavedAs}</dt>
             <dd class="min-w-0 truncate text-secondary">{file().path}</dd>
+            <Show when={file().readablePath}>
+              {(readablePath) => (
+                <>
+                  <dt class="font-medium text-dimmed">{t().fetchReadableCopy}</dt>
+                  <dd class="min-w-0 truncate text-secondary">{readablePath()}</dd>
+                </>
+              )}
+            </Show>
           </dl>
         </AiToolActivity>
       )}

package/src/ai/chat-tasks.ts

@@ -16,11 +16,15 @@ import {
   updateMandatePolicy,
   validateMandateIssueAuthority,
 } from "../services/mandates";
-import { parsePgJsonValue } from "../services/postgres";
+import { parsePgJsonValue, toPgUuidArray } from "../services/postgres";
 import { withAiShortIdForDb } from "./short-id";
 import { aiConversations } from "./store";
 import type { AiChatTurnRunConfig, AiStoredMessage, AiTurnStatus } from "./types";
 
+/** Run history and transcripts are operational evidence; 90 days matches capability execution history.
+ * Fixed platform constant, not configurable. */
+export const AI_CHAT_TASK_RUN_RETENTION_DAYS = 90;
+
 export type AiChatTaskState = "active" | "paused" | "completed" | "needs_attention";
 export type AiChatTaskSchedule = { kind: "once"; runAt: string } | { kind: "cron"; cron: string };
 export type AiChatTask = {
@@ -914,6 +918,66 @@ export const aiChatTasks = {
     return occurrences;
   },
 
+  /** Removes expired runs and their evidence, preserving current once slot rows as dedupe guards. */
+  pruneExpiredRuns: async (input: { now?: Date; limit?: number } = {}): Promise<number> => {
+    const cutoff = new Date((input.now ?? new Date()).getTime() - AI_CHAT_TASK_RUN_RETENTION_DAYS * 86_400_000);
+    const limit = Math.min(Math.max(input.limit ?? 100, 1), 500);
+    return sql.begin(async (tx) => {
+      // Keep the current once slot row as a dedupe guard while its turn and transcript expire.
+      const occurrences = await tx<{ id: string; turn_id: string | null; keep: boolean }[]>`
+        SELECT occurrence.id, occurrence.turn_id, EXISTS (
+          SELECT 1 FROM ai.chat_tasks task WHERE task.id = occurrence.task_id
+            AND task.schedule_kind = 'once' AND task.run_at = occurrence.scheduled_for
+        ) AS keep
+        FROM ai.chat_task_occurrences occurrence
+        WHERE occurrence.state IN ('completed', 'failed') AND occurrence.completed_at < ${cutoff}
+          AND (occurrence.turn_id IS NOT NULL OR NOT EXISTS (
+            SELECT 1 FROM ai.chat_tasks task WHERE task.id = occurrence.task_id
+              AND task.schedule_kind = 'once' AND task.run_at = occurrence.scheduled_for
+          ))
+          AND NOT EXISTS (
+            SELECT 1 FROM ai.turns turn WHERE turn.id = occurrence.turn_id
+              AND turn.status NOT IN ('completed', 'failed', 'aborted')
+          )
+        ORDER BY occurrence.completed_at, occurrence.id
+        LIMIT ${limit}
+        FOR UPDATE OF occurrence SKIP LOCKED
+      `;
+      if (occurrences.length > 0) {
+        const occurrenceIds = toPgUuidArray(occurrences.filter((occurrence) => !occurrence.keep).map((occurrence) => occurrence.id));
+        const turnIds = toPgUuidArray(occurrences.flatMap((occurrence) => (occurrence.turn_id ? [occurrence.turn_id] : [])));
+        await tx`DELETE FROM ai.task_messages WHERE loop_id = ANY(${turnIds}::text[])`;
+        await tx`
+          DELETE FROM ai.turns WHERE id = ANY(${turnIds}::uuid[])
+            AND status IN ('completed', 'failed', 'aborted') AND run_config ? 'background'
+        `;
+        await tx`DELETE FROM ai.chat_task_occurrences WHERE id = ANY(${occurrenceIds}::uuid[])`;
+      }
+      const remaining = limit - occurrences.length;
+      if (remaining === 0) return occurrences.length;
+      const orphanedTurns = await tx<{ id: string }[]>`
+        SELECT turn.id FROM ai.turns turn
+        WHERE turn.run_config ? 'background' AND turn.status IN ('completed', 'failed', 'aborted')
+          AND turn.completed_at < ${cutoff}
+          AND NOT EXISTS (
+            SELECT 1 FROM ai.chat_task_occurrences occurrence WHERE occurrence.turn_id = turn.id
+          )
+        ORDER BY turn.completed_at, turn.id
+        LIMIT ${remaining}
+        FOR UPDATE OF turn SKIP LOCKED
+      `;
+      if (orphanedTurns.length === 0) return occurrences.length;
+      const orphanedTurnIds = toPgUuidArray(orphanedTurns.map((turn) => turn.id));
+      await tx`DELETE FROM ai.task_messages WHERE loop_id = ANY(${orphanedTurnIds}::text[])`;
+      const removedTurns = await tx<{ id: string }[]>`
+        DELETE FROM ai.turns WHERE id = ANY(${orphanedTurnIds}::uuid[])
+          AND status IN ('completed', 'failed', 'aborted') AND run_config ? 'background'
+        RETURNING id
+      `;
+      return occurrences.length + removedTurns.length;
+    });
+  },
+
   listQueuedOccurrences: async (limit = 100): Promise<Array<{ occurrence: AiChatTaskOccurrence; task: AiChatTask }>> => {
     const rows = await sql<(OccurrenceRow & TaskRow)[]>`
       SELECT occurrence.id, occurrence.short_id, occurrence.task_id, occurrence.scheduled_for, occurrence.trigger,