@k2b/cloud 0.38.0 → 0.40.0

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

@@ -1,5 +1,4 @@
-import { dates } from "@k2b/stdlib";
-import { announce, Button, ButtonLink, Chat, NoticeCard, useLocale } from "@k2b/ui";
+import { announce, Button, Chat, NoticeCard, useLocale } from "@k2b/ui";
 import {
   type Accessor,
   createEffect,
@@ -16,36 +15,23 @@ 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";
-import {
-  type AiApprovalDecision,
-  ApprovalBlockView,
-  CompactionBlockView,
-  CompactToolRow,
-  SurveyToolView,
-  TextEditorToolView,
-} from "./blocks";
+import { toolSubject, useReaderTimeZone } from "./action-sentences";
+import { CompactionBlockView, CompactToolRow, SurveyToolView, TextEditorToolView } from "./blocks";
 import { CapabilityTablePreview } from "./capability-table";
 import { CloudChartBlock } from "./chart-block";
 import { PresentToolBlock } from "./file-tools";
 import { useAiChatActions } from "./message-actions";
-import {
-  aiToolIcon,
-  capabilityErrorDescription,
-  displayToolName,
-  isCardToolName,
-  isChartToolName,
-  isRecord,
-  isSurveyToolName,
-} from "./message-utils";
+import { aiToolIcon, displayToolName, isCardToolName, isChartToolName, isRecord, isSurveyToolName } from "./message-utils";
 import { aiChatMessages } from "./messages";
 import { AssistantMarkdownBlock } from "./primitives";
+import { ResultLinks, resultLinks, ToolActionView } from "./tool-action";
 import { AiToolActivity, AiToolDisclosureProvider, type AiToolDisclosureState } from "./tool-disclosure";
 import { type AiWorkEntry, type AiWorkItem, countWorkSteps, groupWorkBlocks } from "./tool-groups";
 import { aiTurnErrorCanContinue, aiTurnErrorDescription } from "./turn-error";
-import type { AiTurnAction, AiTurnActionState, AiTurnLayout, AiTurnPhase, AiTurnResult } from "./turn-layout";
+import type { AiTurnAction, AiTurnLayout, AiTurnPhase, AiTurnResult } from "./turn-layout";
 import { CloudCardBlock } from "./visual-tools";
 
 type ToolBlock = Extract<AiTurnBlock, { kind: "tool" }>;
@@ -65,8 +51,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
@@ -417,42 +412,6 @@ const resultSummary = (block: ToolBlock): string => {
   return typeof value === "string" && value.trim().length <= 500 ? value.trim() : "";
 };
 
-/** Links a result offers, limited to paths inside this Cloud. */
-const resultLinks = (block: ToolBlock): Record<string, unknown>[] => {
-  const value = resultRecord(block)?.links;
-  return Array.isArray(value)
-    ? value.filter(
-        (link): link is Record<string, unknown> =>
-          isRecord(link) && typeof link.href === "string" && /^\/(?![\\/])[^\\\u0000-\u001f\u007f]*$/.test(link.href),
-      )
-    : [];
-};
-
-function ResultLinks(props: { links: Record<string, unknown>[] }) {
-  const locale = useLocale();
-  const t = () => aiChatMessages(locale());
-  const label = (link: Record<string, unknown>) =>
-    typeof link.title === "string" ? link.title : link.rel === "edit" ? t().edit : link.rel === "download" ? t().download : t().open;
-  return (
-    <span class="flex min-w-0 flex-wrap items-center justify-end gap-1">
-      <For each={props.links}>
-        {(link) => (
-          <ButtonLink
-            class="ai-chat-result-link"
-            href={String(link.href)}
-            target="_blank"
-            rel="noopener noreferrer"
-            size="xs"
-            variant="ghost"
-          >
-            {label(link)}
-          </ButtonLink>
-        )}
-      </For>
-    </span>
-  );
-}
-
 /** The summary and links of a table result, unless its receipt in place 4 already shows them. */
 function CapabilityResultRow(props: { block: ToolBlock }) {
   const locale = useLocale();
@@ -516,87 +475,11 @@ function AiTurnResultView(props: { result: Accessor<AiTurnResult | undefined>; r
   );
 }
 
-type ReceiptState = Exclude<AiTurnActionState, "open" | "interaction">;
-
-/**
- * One line for an action in place 4, the same element while it runs and once it is done, rejected, failed, or not run.
- * It says what happened in the owning app's words: its sentence for the outcome, such as "Moved report.pdf to the
- * trash", else, once done, the application's own summary of the call. Without either it puts the state in the reader's
- * language before what the call does, such as "Rejected: Write report.md", or before its title and target.
- */
-function AiReceipt(props: { block: ToolBlock; state: ReceiptState; stopped: boolean }) {
-  const locale = useLocale();
-  const timeZone = useReaderTimeZone();
-  const t = () => aiChatMessages(locale());
-  const block = () => props.block;
-  const subject = () => {
-    const sentence = toolSubject(block(), locale(), timeZone);
-    if (sentence) return sentence;
-    const title = block().presentation?.title ?? displayToolName(block().name, locale());
-    const target = toolTarget(block());
-    return target ? `${title} · ${target}` : title;
-  };
-  const capabilityAction = () => block().presentation?.kind === "capability";
-  const links = () => (props.state === "done" ? resultLinks(block()) : []);
-  const outcomeLabel = () => {
-    const state = props.state;
-    if (state === "running") return t().receiptRunning({ title: subject() });
-    if (state === "done") {
-      // A tool that is not a Cloud action has no effect of its own to report; the receipt records the decision.
-      if (!capabilityAction()) return t().receiptApproved({ title: subject() });
-      return toolOutcome(block(), "done", locale(), timeZone) || resultSummary(block()) || t().receiptDone({ title: subject() });
-    }
-    if (state === "rejected") return toolOutcome(block(), "rejected", locale(), timeZone) ?? t().receiptRejected({ title: subject() });
-    if (state === "failed") return t().receiptFailed({ title: subject() });
-    const notRun = toolOutcome(block(), "notRun", locale(), timeZone);
-    return notRun
-      ? t().receiptNotRunSentence({ sentence: notRun, stopped: props.stopped })
-      : t().receiptNotRun({ title: subject(), stopped: props.stopped });
-  };
-  const declined = () => props.state === "rejected" || props.state === "not_run";
-  const label = () => {
-    const at = block().at;
-    return at && props.state !== "running" ? `${outcomeLabel()} · ${dates.formatTime(at, { locale: locale(), timeZone })}` : outcomeLabel();
-  };
-  return (
-    <Chat.Activity
-      class="ai-turn-receipt"
-      icon={declined() ? "ti ti-circle-off" : aiToolIcon(block().name, block().presentation?.appIcon)}
-      accent={declined() ? undefined : block().presentation?.appAccent}
-      label={label()}
-      busy={props.state === "running"}
-      description={props.state === "failed" ? capabilityErrorDescription(block().result) : undefined}
-      trailing={links().length > 0 ? <ResultLinks links={links()} /> : undefined}
-    />
-  );
-}
-
 function AiTurnActionView(props: { action: Accessor<AiTurnAction | undefined>; turnId: string; phase: AiTurnPhase }) {
   const locale = useLocale();
   const timeZone = useReaderTimeZone();
-  let row!: HTMLDivElement;
-  // Set while focus is in this place, including after the focused control disappeared with the decided card.
-  let focusedHere = false;
-  // The decision the server accepted for a card here; its receipt replaces the card before the turn reports it. It
-  // belongs to the call it answered: code that asks again shows the next request on the same block as a new card.
-  const [decided, setDecided] = createSignal<AiApprovalDecision | null>(null);
   const action = () => props.action();
   const state = () => action()?.state;
-  const decision = () => {
-    const current = action();
-    const value = decided();
-    return current && value?.callId === current.block.callId ? value.approved : null;
-  };
-  const card = () => {
-    const current = action();
-    return current?.state === "open" && current.block.status === "awaiting_approval" && decision() === null ? current.block : undefined;
-  };
-  const receipt = (): ReceiptState | undefined => {
-    const current = action();
-    if (!current || card()) return undefined;
-    if (current.state === "open" && current.block.status === "awaiting_approval") return decision() ? "running" : "rejected";
-    return current.state === "open" || current.state === "interaction" ? undefined : current.state;
-  };
   // Screen readers hear a waiting approval once, as one short line instead of the whole card, without moving focus.
   createEffect(
     on(state, (next, previous) => {
@@ -612,37 +495,14 @@ function AiTurnActionView(props: { action: Accessor<AiTurnAction | undefined>; t
       );
     }),
   );
-  // A card the user decided becomes its receipt in place, once, as the direct result of the decision. Focus stays on
-  // that place without scrolling.
-  createEffect(
-    on(
-      () => card() !== undefined,
-      (open, wasOpen) => {
-        if (!wasOpen || open || !focusedHere || typeof document === "undefined") return;
-        const focused = document.activeElement;
-        if (!focused || focused === document.body || row.contains(focused)) row.focus({ preventScroll: true });
-      },
-    ),
-  );
   return (
-    <div
-      ref={row}
-      class="ai-turn__action"
-      aria-live="off"
-      tabIndex={-1}
-      onFocusIn={() => {
-        focusedHere = true;
-      }}
-      onFocusOut={(event) => {
-        if (event.relatedTarget instanceof Node && !row.contains(event.relatedTarget)) focusedHere = false;
-      }}
-    >
+    <div class="ai-turn__action" aria-live="off">
       <Show when={action()}>
         {(current) => (
           <Switch>
-            <Match when={card()}>{(block) => <ApprovalBlockView turnId={props.turnId} block={block()} onDecided={setDecided} />}</Match>
-            <Match when={receipt()}>
-              {(receiptState) => <AiReceipt block={current().block} state={receiptState()} stopped={props.phase === "stopped"} />}
+            {/* A question and every outcome of its call share one element, so an answer collapses it in place. */}
+            <Match when={current().state !== "interaction"}>
+              <ToolActionView block={current().block} turnId={props.turnId} state={current().state} phase={props.phase} />
             </Match>
             <Match when={true}>
               <Switch
@@ -789,6 +649,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 +690,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 +709,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,
@@ -39,8 +39,11 @@ import { ReferenceText } from "./reference-text";
 const VISIBLE_ROWS = 100;
 /** Rows the viewport shows before it scrolls; it reserves their height from the first frame. */
 const VIEWPORT_ROWS = 8;
-/** A compact row: 12px text on a 16px line, 6px padding above and below, a 1px line. */
-const ROW_REM = 1.8125;
+/** A compact DataTable row and its totals row, and the quieter header row above them. */
+const ROW_REM = 2.5;
+const HEADER_REM = 2.125;
+/** DataTable draws a hairline between rows only above this many columns. */
+const HAIRLINE_ABOVE_COLUMNS = 8;
 
 /** Loads a view file with the viewer's access and validates it again: a file is untrusted whoever wrote it. */
 async function loadView(url: string, path: string, signal: AbortSignal): Promise<CloudAiView | null> {
@@ -75,9 +78,16 @@ type ChartSummary = Extract<CloudAiViewSummary, { view: "chart" }>;
 type GroupSummary = Extract<CloudAiViewSummary, { view: "group" }>;
 type ExplorerSummary = Extract<CloudAiViewSummary, { view: "explorer" }>;
 
-/** The header row, the rows up to the viewport's, and the totals row when there is one. */
-const tableHeight = (summary: TableSummary) =>
-  `${(Math.max(1, Math.min(summary.rows, VIEWPORT_ROWS)) + 1 + Number(summary.footer)) * ROW_REM}rem`;
+/**
+ * The header row, the rows up to the viewport's, and the totals row when there is one, inside the paper's 1px frame.
+ * Wide tables add a 1px hairline after each visible body row with a following body row; the footer adds none.
+ */
+const tableHeight = (summary: TableSummary) => {
+  const bodyRows = Math.max(1, Math.min(summary.rows, VIEWPORT_ROWS));
+  const rows = bodyRows + Number(summary.footer);
+  const lines = summary.columns > HAIRLINE_ABOVE_COLUMNS ? bodyRows - 1 + Number(summary.rows > VIEWPORT_ROWS) : 0;
+  return `calc(${HEADER_REM + rows * ROW_REM}rem + ${2 + lines}px)`;
+};
 
 /**
  * A table view: title, Copy data and a sortable table in a viewport whose height follows the row count of its
@@ -244,12 +254,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-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,12 @@ 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, ...(task.reasonAction ? { action: task.reasonAction } : {}) }
+      : null,
   id: task.shortId,
   chatId: task.chatId,
   chatTitle: task.chatTitle,
@@ -93,12 +110,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,75 @@
+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_action 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;
+      -- Bounded only: an older Core clears reason_code without knowing reason_action, so readers pair the two.
+      IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'ai_chat_tasks_reason_action_length_check') THEN
+        ALTER TABLE ai.chat_tasks ADD CONSTRAINT ai_chat_tasks_reason_action_length_check
+          CHECK (reason_action IS NULL OR char_length(reason_action) BETWEEN 1 AND 200);
+      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_action = NULL,
+          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.replace(/^\p{Lu}(?=\p{Ll})/u, (first) => first.toLowerCase())}. ` : ""}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("; ") });