@k2b/cloud 0.37.0 → 0.39.0

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/action-sentences.ts

@@ -1,15 +1,4 @@
 import { createContext, useContext } from "solid-js";
-import {
-  type CapabilityActionWording,
-  capabilityActionOutcome,
-  capabilityActionSubject,
-  resolveCapabilityActionSentences,
-} from "../../_internal/capability-sentences";
-import type { AiTurnBlock } from "../protocol";
-import { CLOUD_AI_TOOL_PRESENTATION } from "../tool-sentences";
-import { displayToolName, isRecord } from "./message-utils";
-
-type ToolBlock = Extract<AiTurnBlock, { kind: "tool" }>;
 
 const ReaderTimeZoneContext = createContext<string>();
 
@@ -20,36 +9,4 @@ export const AiReaderTimeZoneProvider = ReaderTimeZoneContext.Provider;
 export const useReaderTimeZone = (): string =>
   useContext(ReaderTimeZoneContext) ?? (typeof window === "undefined" ? "UTC" : Intl.DateTimeFormat().resolvedOptions().timeZone);
 
-/**
- * How the chat words one call that acts on something: an app Action through its saved presentation, a
- * Cloud tool through Cloud's own catalog of the same shape. `null` for calls that only read.
- */
-export const toolWording = (block: ToolBlock, locale: string): CapabilityActionWording | null => {
-  const presentation = block.presentation;
-  if (presentation?.kind === "capability") {
-    if (presentation.capabilityKind !== "action") return null;
-    return {
-      title: presentation.title,
-      ...(presentation.sentences ? { sentences: presentation.sentences } : {}),
-      ...(presentation.fields ? { fields: presentation.fields } : {}),
-    };
-  }
-  const sentences = resolveCapabilityActionSentences(block.name, CLOUD_AI_TOOL_PRESENTATION, locale);
-  return sentences ? { title: displayToolName(block.name, locale), sentences } : null;
-};
-
-/** What the call does or would do, as one sentence; `null` for calls that only read. */
-export const toolSubject = (block: ToolBlock, locale: string, timeZone: string): string | null => {
-  const wording = toolWording(block, locale);
-  return wording ? capabilityActionSubject(wording, block.args, { locale, timeZone }) : null;
-};
-
-/** The sentence for one outcome, or `null` when the tool has none that renders for this call. */
-export const toolOutcome = (block: ToolBlock, key: "done" | "rejected" | "notRun", locale: string, timeZone: string): string | null => {
-  const wording = toolWording(block, locale);
-  if (!wording) return null;
-  const result = isRecord(block.result) ? block.result : undefined;
-  // App Actions return their data inside the result envelope; Cloud tools return the data itself.
-  const data = block.presentation?.kind === "capability" ? result?.data : block.result;
-  return capabilityActionOutcome(wording, key, { input: block.args, data }, { locale, timeZone });
-};
+export { toolOutcome, toolSubject, toolWording } from "../tool-wording";

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/turn-view.tsx

@@ -16,6 +16,7 @@ import {
   untrack,
 } from "solid-js";
 import { markdown } from "../../shared";
+import { type ChatTaskReason, chatTaskReasonSentence, chatTaskReasonState, chatTaskStopSentence } from "../chat-task-reasons";
 import { AI_TURN_LEASE_MS, type AiTurnBlock } from "../protocol";
 import type { AiTurnError } from "../types";
 import { toolOutcome, toolSubject, useReaderTimeZone } from "./action-sentences";
@@ -65,8 +66,17 @@ export type AiTurnSegment = {
   earlier: boolean;
   /** Read reactively, so a ticking clock does not rebuild the segment. */
   duration: () => AiTurnDuration | null;
-  /** Shown above the work of a delivered scheduled result. */
-  scheduledTask?: { taskId: string; occurrenceId: string } | null;
+  /**
+   * Shown above the work of a delivered scheduled result. `stop` and `reason` add a system line the chat words in
+   * the reader's language; with `stop` or `reasonOnly` that line replaces the stored text.
+   */
+  scheduledTask?: {
+    taskId: string;
+    occurrenceId: string;
+    reason?: ChatTaskReason;
+    reasonOnly?: true;
+    stop?: { cause: "paused" | "deleted"; done: string[] };
+  } | null;
   /**
    * The live turn cannot reach the model or the server right now: a model call waits for its retry, or the stream
    * reconnects. The working segment's work line says so while its clock stands; a turn without a work line yet says
@@ -789,6 +799,7 @@ function AiTurnText(props: {
  */
 export function AiTurnView(props: { segment: Accessor<AiTurnSegment>; disclosureState: AiToolDisclosureState }): JSX.Element {
   const locale = useLocale();
+  const timeZone = useReaderTimeZone();
   const chatActions = useAiChatActions();
   const layout = () => props.segment().layout;
   const results = createMemo(() => new Map(layout().results.map((result) => [result.id, result])));
@@ -829,7 +840,17 @@ export function AiTurnView(props: { segment: Accessor<AiTurnSegment>; disclosure
           </div>
         </Show>
         <For each={resultIds()}>{(id) => <AiTurnResultView result={() => results().get(id)} receipt={() => actions().has(id)} />}</For>
-        <Show when={layout().text.length > 0}>
+        <Show when={props.segment().scheduledTask?.stop}>
+          {(stop) => (
+            <Chat.Activity
+              class="ai-turn__routine-line"
+              wrap
+              icon="ti ti-player-stop"
+              label={chatTaskStopSentence(stop().done, locale())}
+            />
+          )}
+        </Show>
+        <Show when={layout().text.length > 0 && !props.segment().scheduledTask?.stop && !props.segment().scheduledTask?.reasonOnly}>
           <AiTurnText
             blocks={() => layout().text}
             live={live}
@@ -838,6 +859,17 @@ export function AiTurnView(props: { segment: Accessor<AiTurnSegment>; disclosure
             earlier={() => props.segment().earlier}
           />
         </Show>
+        <Show when={props.segment().scheduledTask?.stop ? undefined : props.segment().scheduledTask?.reason}>
+          {(reason) => (
+            <Chat.Activity
+              class="ai-turn__routine-line"
+              wrap
+              icon={chatTaskReasonState(reason().code) === "paused" ? "ti ti-player-pause" : "ti ti-alert-triangle"}
+              tone={chatTaskReasonState(reason().code) === "paused" ? "neutral" : "warning"}
+              label={chatTaskReasonSentence(reason(), { locale: locale(), timeZone })}
+            />
+          )}
+        </Show>
         <For each={actionIds()}>
           {(id) => <AiTurnActionView action={() => actions().get(id)} turnId={props.segment().turnId} phase={props.segment().phase} />}
         </For>

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

@@ -10,7 +10,7 @@ import {
   useLocale,
 } from "@k2b/ui";
 import { createMemo, createSignal, createUniqueId, Index, type JSX, Match, onCleanup, onMount, Show, Switch } from "solid-js";
-import type { CloudAiChartRow } from "../chart-block";
+import { type CloudAiChartRow, cloudAiNumberFormatters } from "../chart-block";
 import {
   CLOUD_AI_DETAILS_VIEWPORT_ITEMS,
   CLOUD_AI_VIEW_MAX_BYTES,
@@ -244,12 +244,17 @@ function CloudStatsView(props: { summary: StatsSummary; input: CloudAiStatsView
         {(value) => (
           <StatGrid columns={columns()}>
             <Index each={value()}>
-              {(tile) => (
+              {(tile, index) => (
                 <StatCell
                   label={tile().label}
                   value={tile().value}
                   title={tile().value}
                   trend={tile().sparkline}
+                  trendTooltip={({ datum }) => {
+                    const point = tile().sparkline?.[datum.index];
+                    const format = cloudAiNumberFormatters(props.input?.items[index]?.format, locale()).value;
+                    return { rows: point === undefined ? [] : [{ label: tile().label, value: format(point) }] };
+                  }}
                   sub={tile().sub}
                   accent={deltaAccent(tile().delta)}
                 />

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-task-contracts.ts

@@ -6,14 +6,25 @@ import { dates } from "@k2b/stdlib";
 import { z } from "zod";
 import { coreSettings } from "../services";
 import { normalizeWorkflowSchedule } from "../workflows/runtime";
+import type { ChatTaskReason } from "./chat-task-reasons";
 import type { AiChatTask, AiChatTaskOccurrence, AiChatTaskOccurrenceState, AiChatTaskSchedule, AiChatTaskState } from "./chat-tasks";
 import { AI_SHORT_ID_PATTERN } from "./short-id";
 
-export const ChatTaskIdSchema = z.string().regex(AI_SHORT_ID_PATTERN).describe("Readable six-character scheduled task ID.");
-export const ChatTaskOccurrenceIdSchema = z.string().regex(AI_SHORT_ID_PATTERN).describe("Readable six-character task occurrence ID.");
+export const ChatTaskIdSchema = z.string().regex(AI_SHORT_ID_PATTERN).describe("Readable six-character routine ID.");
+export const ChatTaskOccurrenceIdSchema = z.string().regex(AI_SHORT_ID_PATTERN).describe("Readable six-character routine run ID.");
 export const AiConversationIdSchema = z.string().regex(AI_SHORT_ID_PATTERN).describe("Readable six-character AI conversation ID.");
 
+export const chatTaskName = (task: { title?: string | null; chatTitle?: string | null; prompt: string }): string =>
+  task.title?.trim() ||
+  task.chatTitle?.trim() ||
+  Array.from(task.prompt.split(/\n|:\s/u)[0]!.trim())
+    .slice(0, 80)
+    .join("");
+
 export type AiChatTaskView = {
+  title: string | null;
+  name: string;
+  reason: ChatTaskReason | null;
   nextRunAt?: string | null;
   id: string;
   chatId: string;
@@ -42,6 +53,9 @@ export type AiChatTaskOccurrenceView = {
 };
 
 export const toAiChatTaskView = (task: AiChatTask): AiChatTaskView => ({
+  title: task.title,
+  name: task.name,
+  reason: task.reasonCode && task.reasonAt ? { code: task.reasonCode, at: task.reasonAt } : null,
   id: task.shortId,
   chatId: task.chatId,
   chatTitle: task.chatTitle,
@@ -93,12 +107,23 @@ export const getChatTaskTimezone = async (): Promise<string> =>
 export const chatTaskCreateFingerprint = (input: {
   chatId: string;
   prompt: string;
+  title?: string;
   schedule: z.infer<typeof ChatTaskScheduleInputSchema>;
   timezone?: string;
   grants?: TaskGrant[];
 }): string =>
   new Bun.CryptoHasher("sha256")
-    .update(JSON.stringify([input.chatId, input.prompt.trim(), input.schedule, input.timezone ?? null, input.grants ?? []]))
+    .update(
+      JSON.stringify([
+        input.chatId,
+        input.prompt.trim(),
+        input.schedule,
+        input.timezone ?? null,
+        input.grants ?? [],
+        // Without a title the hash stays as before titles existed, so earlier idempotency keys still replay.
+        ...(input.title?.trim() ? [input.title.trim()] : []),
+      ]),
+    )
     .digest("hex");
 
 export const normalizeChatTaskSchedule = async (

package/src/ai/chat-task-reasons-migrate.ts

@@ -0,0 +1,68 @@
+import type { SQL } from "bun";
+import { canonicalLocale } from "../shared/locale";
+
+/** Called in a transaction; new columns and reason repairs commit together. */
+export const migrateChatTaskReasons = async (sql: SQL): Promise<void> => {
+  await sql`ALTER TABLE ai.chat_tasks ADD COLUMN IF NOT EXISTS reason_code TEXT`.simple();
+  await sql`ALTER TABLE ai.chat_tasks ADD COLUMN IF NOT EXISTS reason_at TIMESTAMPTZ`.simple();
+  await sql`ALTER TABLE ai.chat_tasks ADD COLUMN IF NOT EXISTS title TEXT`.simple();
+  const [column] = await sql`SELECT 1 FROM information_schema.columns
+      WHERE table_schema = 'ai' AND table_name = 'chat_tasks' AND column_name = 'locale'`;
+  if (!column) {
+    await sql`ALTER TABLE ai.chat_tasks ADD COLUMN IF NOT EXISTS locale TEXT`.simple();
+    // Data-sized work runs only with the new column. A restart never rescans old turns.
+    let cursor: string | null = null;
+    while (true) {
+      const rows: { id: string; locale: string | null }[] = await sql`
+        SELECT task.id, COALESCE(
+          (SELECT turn.run_config->>'locale' FROM ai.turns turn
+            WHERE turn.conversation_id = task.conversation_id AND turn.run_config->>'kind' = 'chat'
+              AND NOT (turn.run_config ? 'background') AND turn.created_at <= task.created_at
+            ORDER BY turn.created_at DESC, turn.id DESC LIMIT 1),
+          (SELECT turn.run_config->>'locale' FROM ai.turns turn
+            WHERE turn.conversation_id = task.conversation_id AND turn.run_config->>'kind' = 'chat'
+              AND NOT (turn.run_config ? 'background')
+            ORDER BY turn.created_at DESC, turn.id DESC LIMIT 1)) AS locale
+        FROM ai.chat_tasks task WHERE (${cursor}::uuid IS NULL OR task.id > ${cursor}::uuid)
+        ORDER BY task.id LIMIT 500`;
+      if (!rows.length) break;
+      for (const row of rows) {
+        const locale = canonicalLocale(row.locale);
+        if (locale) await sql`UPDATE ai.chat_tasks SET locale = ${locale} WHERE id = ${row.id}::uuid`;
+      }
+      cursor = rows[rows.length - 1]!.id;
+    }
+  }
+  await sql`
+    DO $$ BEGIN
+      IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'ai_chat_tasks_reason_code_check') THEN
+        ALTER TABLE ai.chat_tasks ADD CONSTRAINT ai_chat_tasks_reason_code_check
+          CHECK (reason_code IN ('paused', 'chat_archived', 'owner_inactive', 'failed', 'rights_changed', 'needs_approval'));
+      END IF;
+      IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'ai_chat_tasks_title_check') THEN
+        ALTER TABLE ai.chat_tasks ADD CONSTRAINT ai_chat_tasks_title_check CHECK (char_length(btrim(title)) BETWEEN 1 AND 80);
+      END IF;
+      IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'ai_chat_tasks_reason_state_check') THEN
+        -- Repair legacy and rollback writes, preserving valid reasons and their timestamps.
+        UPDATE ai.chat_tasks SET reason_code = CASE
+          WHEN state NOT IN ('paused', 'needs_attention') THEN NULL
+          WHEN state = 'paused' THEN 'paused'
+          WHEN last_error IN ('Scheduled task mandate revision changed', 'Scheduled task mandate or sponsor is unavailable') THEN 'rights_changed'
+          ELSE 'failed' END,
+          reason_at = CASE WHEN state IN ('paused', 'needs_attention') THEN updated_at ELSE NULL END
+        WHERE NOT (
+          (state IN ('paused', 'needs_attention')) = (reason_code IS NOT NULL)
+          AND (reason_code IS NULL OR
+            (state = 'paused' AND reason_code IN ('paused', 'chat_archived', 'owner_inactive')) OR
+            (state = 'needs_attention' AND reason_code IN ('failed', 'rights_changed', 'needs_approval')))
+        );
+        ALTER TABLE ai.chat_tasks ADD CONSTRAINT ai_chat_tasks_reason_state_check CHECK (
+          (state IN ('paused', 'needs_attention')) = (reason_code IS NOT NULL)
+          AND (reason_code IS NULL OR
+            (state = 'paused' AND reason_code IN ('paused', 'chat_archived', 'owner_inactive')) OR
+            (state = 'needs_attention' AND reason_code IN ('failed', 'rights_changed', 'needs_approval')))
+        );
+      END IF;
+    END $$
+  `.simple();
+};

package/src/ai/chat-task-reasons.ts

@@ -0,0 +1,92 @@
+import { dates, i18n } from "@k2b/stdlib";
+import { canonicalLocale } from "../shared/locale";
+
+export const CHAT_TASK_REASON_CODES = ["paused", "chat_archived", "owner_inactive", "failed", "rights_changed", "needs_approval"] as const;
+export type ChatTaskReasonCode = (typeof CHAT_TASK_REASON_CODES)[number];
+export type ChatTaskReason = { code: ChatTaskReasonCode; at: string; action?: string };
+
+export const chatTaskReasonState = (code: ChatTaskReasonCode): "paused" | "needs_attention" => {
+  switch (code) {
+    case "paused":
+    case "chat_archived":
+    case "owner_inactive":
+      return "paused";
+    case "failed":
+    case "rights_changed":
+    case "needs_approval":
+      return "needs_attention";
+  }
+};
+
+const messages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      paused: ({ time }: { time: string }) => `Paused by you on ${time}. What happens meanwhile is not caught up automatically.`,
+      chat_archived: "Paused because the chat is archived.",
+      owner_inactive: "Paused because the account is inactive.",
+      failed: "The last run failed.",
+      rights_changed: "What it may do changed. Please confirm again.",
+      needs_approval: ({ action }: { action?: string }) =>
+        `${action ? `Tried to ${action}. ` : ""}That needs your approval every time, and routines never ask.`,
+      stopped: ({ list }: { list: string }) =>
+        list
+          ? `Stopped while the routine was running. Already done: ${list}. Nothing was undone.`
+          : "Stopped while the routine was running. Nothing was undone.",
+    },
+    de: {
+      paused: ({ time }) => `Von dir pausiert am ${time}. Was in der Pause passiert, wird nicht von selbst nachgeholt.`,
+      chat_archived: "Pausiert, weil der Chat archiviert ist.",
+      owner_inactive: "Pausiert, weil das Konto inaktiv ist.",
+      failed: "Der letzte Lauf ist fehlgeschlagen.",
+      rights_changed: "Was sie darf, hat sich geändert. Bitte neu bestätigen.",
+      needs_approval: ({ action }) => `${action ? `Wollte ${action}. ` : ""}Das macht der Assistant nur mit dir, und Routinen fragen nie.`,
+      stopped: ({ list }) =>
+        list
+          ? `Angehalten, während die Routine lief. Schon erledigt: ${list}. Nichts wurde rückgängig gemacht.`
+          : "Angehalten, während die Routine lief. Nichts wurde rückgängig gemacht.",
+    },
+  },
+});
+
+/**
+ * A one-time routine resumes only before its time: a run at that time already happened or was stopped, and what was
+ * missed in a pause is not caught up. It needs a new time first.
+ */
+export const chatTaskNeedsNewTime = (
+  task: {
+    state: "active" | "paused" | "completed" | "needs_attention";
+    schedule: { kind: "once"; runAt: string } | { kind: "cron"; cron: string };
+  },
+  now: Date = new Date(),
+): boolean =>
+  task.state !== "active" &&
+  task.schedule.kind === "once" &&
+  (task.state === "needs_attention" || Date.parse(task.schedule.runAt) <= now.getTime());
+
+export const chatTaskLocale = (taskLocale: string | null | undefined, appLocale?: string | null): string =>
+  canonicalLocale(taskLocale) ?? canonicalLocale(appLocale) ?? "en";
+
+export const chatTaskReasonSentence = (reason: ChatTaskReason, context: { locale: string; timeZone: string }): string => {
+  const t = messages.resolve([context.locale]).t;
+  // The record is exhaustive: a new reason must have a sentence in both catalogs.
+  const sentences: Record<ChatTaskReasonCode, () => string> = {
+    paused: () => t.paused({ time: dates.formatDateTime(reason.at, context) }),
+    chat_archived: () => t.chat_archived,
+    owner_inactive: () => t.owner_inactive,
+    failed: () => t.failed,
+    rights_changed: () => t.rights_changed,
+    needs_approval: () => t.needs_approval({ action: reason.action }),
+  };
+  return sentences[reason.code]();
+};
+
+// A scan from the end instead of /[.!?]+$/, which backtracks quadratically on long runs of punctuation.
+const withoutClosingPunctuation = (text: string): string => {
+  let end = text.length;
+  while (end > 0 && ".!?".includes(text[end - 1]!)) end -= 1;
+  return text.slice(0, end);
+};
+
+export const chatTaskStopSentence = (done: readonly string[], locale: string): string =>
+  messages.resolve([locale]).t.stopped({ list: done.map(withoutClosingPunctuation).join("; ") });