@k2b/cloud 0.38.0 → 0.39.0

package/src/access/PermissionEditor.tsx

@@ -1,6 +1,6 @@
 import { mutation } from "@k2b/stdlib/solid";
 import { announce, IconButton, Placeholder, prompts, SelectChip, Tooltip, useLocale } from "@k2b/ui";
-import { createMemo, createSignal, For, onCleanup, Show } from "solid-js";
+import { createEffect, createMemo, createSignal, For, onCleanup, Show } from "solid-js";
 import { createStore, reconcile } from "solid-js/store";
 import { CloudAvatar } from "../account/Avatar";
 import type { AccessEntry, PermissionLevel, Principal, ServiceAccountKind } from "../contracts/shared";
@@ -27,9 +27,9 @@ export type GrantableLevel = Exclude<PermissionLevel, "none">;
 export type AllowedLevel = GrantableLevel | { level: GrantableLevel; scope?: string; label?: string; icon?: string; description?: string };
 
 type PermissionEditorProps = {
-  /** Initial access entries — caller stays the source of truth for
-   *  what's stored on the resource; the editor updates its local copy
-   *  after successful mutations. */
+  /** The editor mounts from this list and merges later lists by entry id once no change is saving.
+   *  Rows the caller changed since its last list win; unchanged rows keep the editor's confirmed result.
+   *  Keep the editor mounted (no keyed Show or unmount during refresh) and pass refetched data. */
   initialEntries: AccessEntry[];
 
   /** Whether the current user can edit permissions. When `false`, the
@@ -179,7 +179,9 @@ export default function PermissionEditor(props: PermissionEditorProps) {
   const t = () => accessMessages.resolve([locale()]).t;
   // A store keeps each row's identity across level changes, so an expanded member list stays open. It holds
   // copies: store writes go into the objects themselves, and the caller's entries are not the editor's to change.
-  const [entries, setEntries] = createStore<AccessEntry[]>(props.initialEntries.map((entry) => ({ ...entry })));
+  const initialEntries = props.initialEntries;
+  let appliedCallerEntries = new Map(initialEntries.map((entry) => [entry.id, JSON.stringify(entry)]));
+  const [entries, setEntries] = createStore<AccessEntry[]>(initialEntries.map((entry) => ({ ...entry })));
   const [pending, setPending] = createSignal<string | null>(null);
   const grantPending = () => pending() !== null;
   let disposed = false;
@@ -281,6 +283,29 @@ export default function PermissionEditor(props: PermissionEditorProps) {
     },
   });
   const busy = () => grantPending() || updateMut.loading() || revokeMut.loading();
+  createEffect(() => {
+    const next = props.initialEntries;
+    const nextCallerEntries = new Map(next.map((entry) => [entry.id, JSON.stringify(entry)]));
+    // Mutation loading clears before onSuccess; wait for its local writes and onFinally too.
+    if (busy() || updating() !== null || revoking() !== null) return;
+    if (
+      nextCallerEntries.size === appliedCallerEntries.size &&
+      next.every((entry) => nextCallerEntries.get(entry.id) === appliedCallerEntries.get(entry.id))
+    )
+      return;
+    // Rows the caller changed since its last list win; unchanged rows keep the editor's confirmed result.
+    const localEntries = new Map(entries.map((entry) => [entry.id, entry]));
+    const merged: AccessEntry[] = [];
+    for (const entry of next) {
+      const row = nextCallerEntries.get(entry.id) !== appliedCallerEntries.get(entry.id) ? entry : localEntries.get(entry.id);
+      if (row) merged.push({ ...row });
+    }
+    for (const entry of entries) {
+      if (!nextCallerEntries.has(entry.id) && !appliedCallerEntries.has(entry.id)) merged.push({ ...entry });
+    }
+    setEntries(reconcile(merged, { key: "id" }));
+    appliedCallerEntries = nextCallerEntries;
+  });
   // The service refuses to remove the last manager; the row says so up front.
   const lastManagerId = createMemo(() => {
     // A grant on part of the resource never manages it.

package/src/access/ResourceApiKeys.tsx

@@ -176,7 +176,11 @@ export default function ResourceApiKeys(props: ResourceApiKeysProps) {
   const createMutation = mutations.create<{ credential: ResourceApiKey; token: string }, CreateResourceApiKeyInput>({
     mutation: props.createKey,
     onSuccess: async (data) => {
-      setKeys([data.credential, ...keys()]);
+      setKeys((current) =>
+        current.some((key) => key.id === data.credential.id)
+          ? current.map((key) => (key.id === data.credential.id ? data.credential : key))
+          : [data.credential, ...current],
+      );
       await prompts.dialog<void>(() => <TokenDialog token={data.token} />, {
         title: t().keyCreated,
         icon: "ti ti-key",

package/src/ai/approval-routes.ts

@@ -56,7 +56,7 @@ type AiApprovalRouteDependencies = {
   limit?: MiddlewareHandler<AuthContext>;
   authenticate?: MiddlewareHandler<AuthContext>;
   listPreferences?: (actorUserId: string, options: { conversationId?: string }) => Promise<AiToolApprovalPreference[]>;
-  revokePreference?: (actorUserId: string, preferenceId: string) => Promise<boolean>;
+  revokePreference?: typeof revokeAiToolApprovalPreference;
   listCapabilities?: () => Promise<CapabilityRegistryEntry[]>;
   /** Resolves a chat the user owns by its ID or short ID. */
   findConversation?: (ownerUserId: string, conversation: string) => Promise<{ id: string } | null>;
@@ -157,7 +157,10 @@ export const createAiApprovalPreferenceRoutes = (dependencies: AiApprovalRouteDe
       v("param", AiApprovalPreferenceParamSchema),
       async (c) => {
         const user = expectUserBackedActor(c);
-        const deleted = await revokePreference(user.id, c.req.valid("param").preferenceId);
+        const deleted = await revokePreference(user.id, c.req.valid("param").preferenceId, {
+          actor: c.get("actor"),
+          requestId: c.req.header("x-request-id") ?? null,
+        });
         return deleted ? c.json({ deleted: true as const }) : c.json({ message: "Approval not found", code: "NOT_FOUND" }, 404);
       },
     );

package/src/ai/approvals.ts

@@ -1,4 +1,8 @@
-import { sql } from "bun";
+import { type SQL, sql } from "bun";
+import type { AccessSubject } from "../contracts/shared";
+import type { RequestActor } from "../server/middleware/auth";
+import { type AuditActor, type AuditRecordParams, audit } from "../services/audit";
+import { toPgTextArray } from "../services/postgres";
 import type { AiToolApprovalPolicy, AiTurnRunConfig } from "./types";
 
 /** Background authority never inherits a user's interactive Always Allow preference. */
@@ -31,6 +35,16 @@ export type AiToolApprovalContext = {
   actorUserId: string;
 };
 
+/**
+ * Request identity for approval changes; never persist this context in a turn run config.
+ * When actor is absent, audit uses { userId: actorUserId } for the approval's owner.
+ * The access subject is derived from actor, or falls back to { type: "user", userId: actorUserId }.
+ */
+export type AiToolApprovalChangeContext = AiToolApprovalContext & {
+  actor?: RequestActor;
+  requestId?: string | null;
+};
+
 /** Where a remembered approval applies: in one chat until it is deleted, or always. */
 export type AiToolApprovalRemember = "chat" | "always";
 
@@ -55,6 +69,59 @@ type AiToolApprovalPreferenceRow = {
   expires_at: Date | string | null;
 };
 
+type ApprovalAuditRow = Pick<AiToolApprovalPreferenceRow, "id" | "tool_name" | "approval_scope" | "conversation_id">;
+type ApprovalAuditIdentity = {
+  actor: AuditActor | null;
+  accessSubject: AccessSubject | null;
+  serviceAccountId?: string;
+  requestId?: string | null;
+  reason?: string;
+};
+
+const approvalAuditIdentity = (context: AiToolApprovalChangeContext): ApprovalAuditIdentity => {
+  const user = context.actor?.kind === "user" ? context.actor.user : context.actor?.delegatedUser;
+  return {
+    actor: context.actor
+      ? user
+        ? { userId: user.id, uid: user.uid, provider: user.provider, roles: user.roles }
+        : null
+      : { userId: context.actorUserId },
+    // Match aiChatAccessSubject locally: importing assistant-models creates a cycle through firecrawl-tools.
+    accessSubject: user
+      ? {
+          type: "user",
+          userId: user.id,
+          ...(context.actor?.kind === "service_account" ? { delegatedByServiceAccountId: context.actor.serviceAccount.id } : {}),
+        }
+      : context.actor?.kind === "service_account"
+        ? { type: "service_account", serviceAccountId: context.actor.serviceAccount.id }
+        : { type: "user", userId: context.actorUserId },
+    ...(context.actor?.kind === "service_account" ? { serviceAccountId: context.actor.serviceAccount.id } : {}),
+    requestId: context.requestId,
+  };
+};
+
+const approvalAuditEvent = (
+  action: "ai.approval.remember" | "ai.approval.revoke",
+  row: ApprovalAuditRow,
+  identity: ApprovalAuditIdentity,
+): AuditRecordParams => ({
+  action,
+  outcome: "allowed",
+  actor: identity.actor,
+  target: { type: "ai_approval", id: row.id, label: row.tool_name },
+  requestId: identity.requestId,
+  reason: identity.reason,
+  metadata: {
+    toolName: row.tool_name,
+    approvalScope: row.approval_scope,
+    remember: row.conversation_id !== null ? "chat" : "always",
+    ...(row.conversation_id !== null ? { conversationId: row.conversation_id } : {}),
+    accessSubject: identity.accessSubject,
+    ...(identity.serviceAccountId ? { serviceAccountId: identity.serviceAccountId } : {}),
+  },
+});
+
 export const aiToolApprovalScope = (toolName: string, policy: AiToolApprovalPolicy | undefined): string => {
   if (policy && typeof policy === "object") return policy.scope ?? toolName;
   return toolName;
@@ -100,20 +167,12 @@ export const hasRememberedAiToolApproval = async (
 
 /** Remembers an approval everywhere, or in one chat when `conversationId` is set; a chat approval ends with its chat. */
 export const rememberAiToolApproval = async (
-  context: AiToolApprovalContext,
+  context: AiToolApprovalChangeContext,
   input: { toolName: string; approvalScope: string; conversationId?: string | null; expiresAt?: Date | null },
 ): Promise<void> => {
   const conversationId = input.conversationId ?? null;
-  await sql.begin(async () => {
-    await sql`
-      DELETE FROM ai.tool_approval_preferences
-      WHERE actor_user_id = ${context.actorUserId}
-        AND tool_name = ${input.toolName}
-        AND approval_scope = ${input.approvalScope}
-        AND conversation_id IS NOT DISTINCT FROM ${conversationId}::uuid
-    `;
-
-    await sql`
+  await sql.begin(async (tx) => {
+    const [row] = await tx<{ id: string }[]>`
       INSERT INTO ai.tool_approval_preferences (
         actor_user_id,
         tool_name,
@@ -130,24 +189,46 @@ export const rememberAiToolApproval = async (
         now(),
         ${input.expiresAt ?? null}
       )
+      ON CONFLICT (actor_user_id, tool_name, approval_scope, conversation_id)
+      DO UPDATE SET
+        created_at = EXCLUDED.created_at,
+        last_used_at = EXCLUDED.last_used_at,
+        expires_at = EXCLUDED.expires_at
+      RETURNING id
     `;
+    await audit.record(
+      approvalAuditEvent(
+        "ai.approval.remember",
+        {
+          id: row!.id,
+          tool_name: input.toolName,
+          approval_scope: input.approvalScope,
+          conversation_id: conversationId,
+        },
+        approvalAuditIdentity(context),
+      ),
+      tx,
+    );
   });
 };
 
 /** Forgets the approval with exactly this reach: everywhere, or in the one chat `conversationId` names. */
 export const forgetAiToolApproval = async (
-  context: AiToolApprovalContext,
+  context: AiToolApprovalChangeContext,
   input: { toolName: string; approvalScope: string; conversationId?: string | null },
 ): Promise<boolean> => {
-  const rows = await sql<{ id: string }[]>`
-    DELETE FROM ai.tool_approval_preferences
-    WHERE actor_user_id = ${context.actorUserId}
-      AND tool_name = ${input.toolName}
-      AND approval_scope = ${input.approvalScope}
-      AND conversation_id IS NOT DISTINCT FROM ${input.conversationId ?? null}::uuid
-    RETURNING id
-  `;
-  return rows.length > 0;
+  return sql.begin(async (tx) => {
+    const rows = await tx<ApprovalAuditRow[]>`
+      DELETE FROM ai.tool_approval_preferences
+      WHERE actor_user_id = ${context.actorUserId}
+        AND tool_name = ${input.toolName}
+        AND approval_scope = ${input.approvalScope}
+        AND conversation_id IS NOT DISTINCT FROM ${input.conversationId ?? null}::uuid
+      RETURNING id, tool_name, approval_scope, conversation_id
+    `;
+    for (const row of rows) await audit.record(approvalAuditEvent("ai.approval.revoke", row, approvalAuditIdentity(context)), tx);
+    return rows.length > 0;
+  });
 };
 
 const toIsoString = (value: Date | string): string => (value instanceof Date ? value : new Date(value)).toISOString();
@@ -186,12 +267,42 @@ export const listAiToolApprovalPreferences = async (
   return rows.map(approvalPreferenceFromRow);
 };
 
-export const revokeAiToolApprovalPreference = async (actorUserId: string, preferenceId: string): Promise<boolean> => {
-  const rows = await sql<{ id: string }[]>`
+export const revokeAiToolApprovalPreference = async (
+  actorUserId: string,
+  preferenceId: string,
+  change?: { actor?: RequestActor; requestId?: string | null },
+): Promise<boolean> =>
+  sql.begin(async (tx) => {
+    const rows = await tx<ApprovalAuditRow[]>`
+      DELETE FROM ai.tool_approval_preferences
+      WHERE id = ${preferenceId}
+        AND actor_user_id = ${actorUserId}
+      RETURNING id, tool_name, approval_scope, conversation_id
+    `;
+    for (const row of rows)
+      await audit.record(approvalAuditEvent("ai.approval.revoke", row, approvalAuditIdentity({ ...change, actorUserId })), tx);
+    return rows.length > 0;
+  });
+
+/** Core migrations supply their transaction so deletion and system audit events commit together. */
+export const revokeAiToolApprovalPreferencesAsSystem = async (
+  db: SQL,
+  input: { ids: readonly string[]; reason: string },
+): Promise<number> => {
+  if (input.ids.length === 0) return 0;
+  const rows = await db<(ApprovalAuditRow & { actor_user_id: string | null })[]>`
     DELETE FROM ai.tool_approval_preferences
-    WHERE id = ${preferenceId}
-      AND actor_user_id = ${actorUserId}
-    RETURNING id
+    WHERE id = ANY(${toPgTextArray([...input.ids])}::uuid[])
+    RETURNING id, tool_name, approval_scope, conversation_id, actor_user_id
   `;
-  return rows.length > 0;
+  for (const row of rows)
+    await audit.record(
+      approvalAuditEvent("ai.approval.revoke", row, {
+        actor: null,
+        accessSubject: row.actor_user_id === null ? null : { type: "user", userId: row.actor_user_id },
+        reason: input.reason,
+      }),
+      db,
+    );
+  return rows.length;
 };

package/src/ai/browser.ts

@@ -189,6 +189,16 @@ export const launchAssistant = async (input: LaunchAssistantInput): Promise<Assi
   };
 };
 
+export {
+  CHAT_TASK_REASON_CODES,
+  type ChatTaskReason,
+  type ChatTaskReasonCode,
+  chatTaskLocale,
+  chatTaskNeedsNewTime,
+  chatTaskReasonSentence,
+  chatTaskReasonState,
+  chatTaskStopSentence,
+} from "./chat-task-reasons";
 export {
   CLOUD_AI_STATS_MAX_ITEMS,
   CLOUD_AI_TABLE_MAX_COLUMNS,

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/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-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();
+};