@k2b/cloud 0.38.0 → 0.39.0

package/src/ai/index.ts

@@ -2,6 +2,7 @@ export { type AiAppSkillIssue, aiAppSkills, appSkillsRegistryState, reconcileApp
 export { type AiApprovalPreferenceRoutes, type AiApprovalPreferenceView, createAiApprovalPreferenceRoutes } from "./approval-routes";
 export {
   AI_WEBSITE_APPROVAL_TOOL,
+  type AiToolApprovalChangeContext,
   type AiToolApprovalContext,
   type AiToolApprovalPreference,
   type AiToolApprovalRemember,
@@ -33,11 +34,22 @@ export {
   ChatTaskOccurrenceIdSchema,
   ChatTaskScheduleInputSchema,
   chatTaskCreateFingerprint,
+  chatTaskName,
   getChatTaskTimezone,
   normalizeChatTaskSchedule,
   toAiChatTaskOccurrenceView,
   toAiChatTaskView,
 } from "./chat-task-contracts";
+export {
+  CHAT_TASK_REASON_CODES,
+  type ChatTaskReason,
+  type ChatTaskReasonCode,
+  chatTaskLocale,
+  chatTaskNeedsNewTime,
+  chatTaskReasonSentence,
+  chatTaskReasonState,
+  chatTaskStopSentence,
+} from "./chat-task-reasons";
 export {
   type AiChatTask,
   AiChatTaskIdempotencyConflictError,

package/src/ai/migrate.ts

@@ -1,6 +1,7 @@
 import { sql } from "bun";
 import { CapabilityActionReviewSchema } from "../contracts/capabilities";
 import { APPROVAL_MAX_WAIT_MS, approvalAssurance, approvalScopeFromToolName, approvals, migrateApprovals } from "../services/approvals";
+import { migrateChatTaskReasons } from "./chat-task-reasons-migrate";
 import { migrateAiMessageQueue } from "./message-queue";
 import { migrateAiModelAccess } from "./model-access-migrate";
 import { migrateAiQuotas } from "./quotas-migrate";
@@ -885,6 +886,8 @@ export const migrateCloudAi = async (): Promise<void> => {
     )
   `.simple();
 
+  await sql.begin(migrateChatTaskReasons);
+
   await sql`ALTER TABLE ai.chat_tasks ADD COLUMN IF NOT EXISTS idempotency_fingerprint TEXT`.simple();
   await sql`ALTER TABLE ai.chat_tasks ADD COLUMN IF NOT EXISTS revision BIGINT NOT NULL DEFAULT 0`.simple();
   await sql`ALTER TABLE ai.chat_tasks ADD COLUMN IF NOT EXISTS mandate_id UUID`.simple();
@@ -998,6 +1001,17 @@ export const migrateCloudAi = async (): Promise<void> => {
     )
   `.simple();
 
+  await sql`
+    DO $$ BEGIN
+      IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'ai_chat_task_occurrences_state_check'
+          AND pg_get_constraintdef(oid) LIKE '%stopped%') THEN
+        ALTER TABLE ai.chat_task_occurrences DROP CONSTRAINT IF EXISTS ai_chat_task_occurrences_state_check;
+        ALTER TABLE ai.chat_task_occurrences ADD CONSTRAINT ai_chat_task_occurrences_state_check
+          CHECK (state IN ('queued', 'running', 'completed', 'failed', 'stopped'));
+      END IF;
+    END $$
+  `.simple();
+
   await sql`ALTER TABLE ai.chat_task_occurrences ADD COLUMN IF NOT EXISTS task_revision BIGINT NOT NULL DEFAULT 0`.simple();
 
   await sql`
@@ -1016,10 +1030,18 @@ export const migrateCloudAi = async (): Promise<void> => {
     WHERE state = 'queued'
   `.simple();
 
+  await sql`
+    DO $$ BEGIN
+      IF EXISTS (SELECT 1 FROM pg_indexes WHERE schemaname = 'ai' AND indexname = 'idx_ai_chat_task_occurrences_finished'
+          AND indexdef NOT LIKE '%stopped%') THEN
+        DROP INDEX ai.idx_ai_chat_task_occurrences_finished;
+      END IF;
+    END $$
+  `.simple();
   await sql`
     CREATE INDEX IF NOT EXISTS idx_ai_chat_task_occurrences_finished
     ON ai.chat_task_occurrences(completed_at, id)
-    WHERE state IN ('completed', 'failed')
+    WHERE state IN ('completed', 'failed', 'stopped')
   `.simple();
 
   await sql`
@@ -2468,7 +2490,11 @@ export const migrateCloudAi = async (): Promise<void> => {
   {
     const { coreSettings } = await import("../services");
     const { setAiCredential, splitAiProfileCredentials } = await import("./credentials");
-    const split = splitAiProfileCredentials((await coreSettings.get<string>("ai.model_profiles_json")) ?? "[]");
+    const profiles = await coreSettings.read<string>("ai.model_profiles_json");
+    if (profiles.stored === "unreadable") {
+      console.warn('[ai] cannot read setting "ai.model_profiles_json"; skipping credential split');
+    }
+    const split = profiles.stored === "unreadable" ? null : splitAiProfileCredentials(profiles.value ?? "[]");
     if (split && split.credentials.length > 0) {
       for (const { profileId, secret } of split.credentials) await setAiCredential(profileId, secret);
       await coreSettings.set("ai.model_profiles_json", split.profilesJson);

package/src/ai/request-context.ts

@@ -3,7 +3,7 @@ import { userFromActor } from "../server/actor";
 import { type ApiErrorResponse, respond } from "../server/api";
 import type { AuthContext, RequestActor } from "../server/middleware/auth";
 import { err, fail } from "../server/services";
-import type { AiToolApprovalContext } from "./approvals";
+import type { AiToolApprovalChangeContext, AiToolApprovalContext } from "./approvals";
 import { personalAiModelPolicy } from "./personal-agent";
 import type { AiModelPolicy } from "./types";
 
@@ -13,6 +13,7 @@ export type AiChatRequestContext = {
   ownerUserId: string;
   modelPolicy: AiModelPolicy;
   toolApprovalContext: AiToolApprovalContext;
+  toolApprovalChangeContext: AiToolApprovalChangeContext;
   /** A person in a signed-in browser session, not `cld`, an API key, or another delegated credential. */
   signedInSession: boolean;
 };
@@ -28,6 +29,11 @@ export const resolveAiChatRequestContext = async <T extends AuthContext>(
     ownerUserId: user.id,
     modelPolicy: personalAiModelPolicy,
     toolApprovalContext: { actorUserId: user.id },
+    toolApprovalChangeContext: {
+      actorUserId: user.id,
+      actor,
+      requestId: c.req.header("x-request-id") ?? null,
+    },
     signedInSession: actor.kind === "user" && !actor.delegation && c.get("credentialKind") === "session",
   };
 };

package/src/ai/routes.ts

@@ -17,6 +17,7 @@ import {
   respond,
   v,
 } from "../server";
+import { isAppSessionActor } from "../server/actor";
 import { isRequestCredentialCurrent } from "../server/middleware/auth";
 import { approvalDecisionChannel } from "../services/approvals";
 import { ImageMetadataError } from "../services/image-metadata";
@@ -28,6 +29,7 @@ import { AI_AUDIO_MAX_BYTES } from "./audio-format";
 import { buildAiCapabilityCatalog } from "./capabilities";
 import { aiChatMessages } from "./chat/messages";
 import { getAiChatQuotas } from "./chat-quotas";
+import { aiChatTasks } from "./chat-tasks";
 import { AI_CLIENT_TOOL_ACTION_MAX_BYTES, aiClientToolOutputSchemas } from "./client-tool-results";
 import { createCloudAiLocalBashTool, createCloudAiLocalTools, createConfiguredDefaultCloudAiTools } from "./default-tools";
 import { enqueueAiDictation } from "./dictation-runtime";
@@ -784,6 +786,13 @@ export const aiRoutes = (() => {
           ownerUserId: ctx.ownerUserId,
         });
         if (!archived) return notFound(c);
+        // The chat is archived either way; admission pauses a routine this step missed before its next run.
+        await aiChatTasks.pauseForArchivedChat({ conversationId: conversation.id, userId: ctx.ownerUserId }).catch((error) =>
+          logger("ai:chat-tasks").warn("Could not pause the routines of an archived chat", {
+            conversationId: conversation.id,
+            error: error instanceof Error ? error.message : String(error),
+          }),
+        );
         return respond(c, ok({ ok: true }));
       })
       .post("/conversations/:conversationId/restore", async (c) => {
@@ -791,10 +800,27 @@ export const aiRoutes = (() => {
         if (ctx instanceof Response) return ctx;
         const conversation = await loadConversation(c, ctx, true);
         if (!conversation) return notFound(c);
+        await aiChatTasks.markRestoreStarted({ conversationId: conversation.id, userId: ctx.ownerUserId });
         const restored = await aiConversations.restoreConversation({
           conversationId: conversation.id,
           ownerUserId: ctx.ownerUserId,
         });
+        // A restored chat must not leave archive reasons on routines that stay paused.
+        // The phone app may restore the chat and relabel pauses, but may not resume background authority.
+        // If this step fails, the routine recovery relabels them after a grace period; it never resumes.
+        if (restored)
+          await aiChatTasks
+            .resumeForRestoredChat({
+              conversationId: conversation.id,
+              userId: ctx.ownerUserId,
+              resume: !isAppSessionActor(c.get("actor")),
+            })
+            .catch((error) =>
+              logger("ai:chat-tasks").warn("Could not resume the routines of a restored chat", {
+                conversationId: conversation.id,
+                error: error instanceof Error ? error.message : String(error),
+              }),
+            );
         return restored ? respond(c, ok(await publicConversationFor(restored, c.get("accessSubject")))) : notFound(c);
       })
       .post("/conversations/:conversationId/viewed", async (c) => {
@@ -1168,7 +1194,7 @@ export const aiRoutes = (() => {
                 client: c.req.header(APPROVAL_CLIENT_HEADER),
               }),
             },
-            toolApprovalContext: ctx.toolApprovalContext,
+            toolApprovalContext: ctx.toolApprovalChangeContext,
             signedInSession: ctx.signedInSession,
           });
           if (!result.ok) return toAiActionFailureResponse(c, result);

package/src/ai/runtime.ts

@@ -8,7 +8,13 @@ import { type ApprovalDecisionChannel, approvals } from "../services/approvals";
 import { logger } from "../services/logging";
 import { superviseRuntimeTask } from "../services/runtime-lifecycle";
 import { coreSettings } from "../services/settings/api";
-import { AI_WEBSITE_APPROVAL_TOOL, type AiToolApprovalContext, aiTurnAllowsRememberedApprovals, rememberAiToolApproval } from "./approvals";
+import {
+  AI_WEBSITE_APPROVAL_TOOL,
+  type AiToolApprovalChangeContext,
+  type AiToolApprovalContext,
+  aiTurnAllowsRememberedApprovals,
+  rememberAiToolApproval,
+} from "./approvals";
 import { aiChatAccessSubject, selectAssistantAiModelId } from "./assistant-models";
 import { startAiDictationRuntime } from "./dictation-runtime";
 import { AiTurnExecutor, type ExecutorConfig } from "./executor";
@@ -20,8 +26,9 @@ import { aiQuotas } from "./quotas";
 import { parseAiResourceMarker } from "./resource-markers";
 import { isAiVisionModelConfigured } from "./settings";
 import { aiConversations } from "./store";
-import { publishAiTurnAbort, publishAiWireEvent } from "./stream";
+import { publishAiWireEvent } from "./stream";
 import { aiToolAudit } from "./tool-audit";
+import { finishAiTurnAbort } from "./turn-abort";
 import type {
   AiChatTurnRunConfig,
   AiClientToolId,
@@ -273,32 +280,10 @@ export const submitAiCompaction = async (input: SubmitAiCompactionInput): Promis
 // ---------------------------------------------------------------------------
 
 export const abortAiTurn = async (input: { conversationId: string; turnId: string }): Promise<{ ok: true }> => {
-  // Capture the wire coordinates before finalization so we can emit turn_finished.
+  // Capture wire coordinates before the cancellation flag can wake its owner.
   const active = await aiConversations.getActiveTurn({ conversationId: input.conversationId }).catch(() => null);
   const request = await aiConversations.requestTurnAbort({ ...input, reason: "user" });
-  if (!request.found) return { ok: true };
-
-  // Tell any live owner to stop (its heartbeat also detects the cancel flag).
-  await publishAiTurnAbort(input).catch(() => undefined);
-
-  if (request.ownerless) {
-    const finalized = await aiConversations.completeTurn({ ...input, status: "aborted", error: null });
-    const config = await aiConversations.getTurnRunConfig(input);
-    if (finalized === "completed" && !(config?.kind === "chat" && config.background)) {
-      const attempt = active?.turn.id === input.turnId ? active.turn.attempt : 1;
-      const seq = (active?.turn.id === input.turnId ? active.liveSeq : 0) + 1;
-      await publishAiWireEvent({
-        v: 1,
-        conversationId: input.conversationId,
-        turnId: input.turnId,
-        attempt,
-        seq,
-        type: "turn_finished",
-        status: "aborted",
-        error: null,
-      }).catch(() => undefined);
-    }
-  }
+  await finishAiTurnAbort(input, request, active);
   return { ok: true };
 };
 
@@ -331,7 +316,7 @@ export const submitAiTurnAction = async (input: {
   callId: string;
   action: AiTurnActionInput;
   decidedBy: { userId: string; via: ApprovalDecisionChannel; deviceId?: string };
-  toolApprovalContext?: AiToolApprovalContext;
+  toolApprovalContext?: AiToolApprovalChangeContext;
   /** Whether a person decides in a signed-in browser session; only such a decision may remember a website. */
   signedInSession?: boolean;
 }): Promise<{ ok: true } | { ok: false; status: 400 | 403 | 404 | 409; message: string }> => {

package/src/ai/store.ts

@@ -2992,12 +2992,14 @@ export const aiConversations: AiConversationService = {
     return Boolean(rows[0]);
   },
 
-  requestTurnAbort: async (input) => {
+  requestTurnAbort: async (input, options) => {
     const reason = input.reason ?? "user";
-    const rows = await sql<TurnRow[]>`
+    const rows = await (options?.db ?? sql)<TurnRow[]>`
       UPDATE ai.turns
       SET cancel_requested_at = COALESCE(cancel_requested_at, now()),
-          cancellation_reason = COALESCE(cancellation_reason, ${reason})
+          cancellation_reason = CASE WHEN ${reason} = 'routine_deleted' THEN ${reason}
+            WHEN ${reason} = 'routine_paused' AND cancellation_reason IS DISTINCT FROM 'routine_deleted' THEN ${reason}
+            ELSE COALESCE(cancellation_reason, ${reason}) END
       WHERE id = ${input.turnId}
         AND conversation_id = ${input.conversationId}
         AND status IN ('queued', 'running', 'waiting_for_action')

package/src/ai/timeline.ts

@@ -36,6 +36,9 @@ const isAssistantPart = (entry: AiStoredMessage): boolean =>
   entry.kind === "message" && (entry.message.role === "assistant" || entry.message.role === "tool_result");
 
 const sameLoop = (entry: AiStoredMessage, loopId: string | null): boolean => (loopId ? entry.loopId === loopId : entry.loopId === null);
+/** Each delivered routine run is its own answer, with its own run link and system line, also when runs follow each other. */
+const sameRoutineRun = (entry: AiStoredMessage, first: AiStoredMessage): boolean =>
+  (entry.meta?.scheduledTask?.occurrenceId ?? null) === (first.meta?.scheduledTask?.occurrenceId ?? null);
 
 const assistantActionEntry = (entries: AiStoredMessage[]): AiStoredMessage | null => {
   const assistantEntries = entries.filter((entry) => entry.kind === "message" && entry.message.role === "assistant");
@@ -107,7 +110,12 @@ export const buildAiMessageTimeline = (messages: AiStoredMessage[]): AiMessageTi
     pendingSteers = [];
     const entries = [entry];
     index += 1;
-    while (index < messages.length && isAssistantPart(messages[index]!) && sameLoop(messages[index]!, loopId)) {
+    while (
+      index < messages.length &&
+      isAssistantPart(messages[index]!) &&
+      sameLoop(messages[index]!, loopId) &&
+      (loopId !== null || sameRoutineRun(messages[index]!, entry))
+    ) {
       entries.push(messages[index]!);
       index += 1;
     }

package/src/ai/tool-wording.ts

@@ -0,0 +1,45 @@
+import {
+  type CapabilityActionWording,
+  capabilityActionOutcome,
+  capabilityActionSubject,
+  resolveCapabilityActionSentences,
+} from "../_internal/capability-sentences";
+import { displayToolName, isRecord } from "./chat/message-utils";
+import type { AiTurnBlock } from "./protocol";
+import { CLOUD_AI_TOOL_PRESENTATION } from "./tool-sentences";
+
+type ToolBlock = Extract<AiTurnBlock, { kind: "tool" }>;
+
+/**
+ * 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 });
+};

package/src/ai/turn-abort.ts

@@ -0,0 +1,33 @@
+import { aiConversations } from "./store";
+import { publishAiTurnAbort, publishAiWireEvent } from "./stream";
+import type { AiTurnAbortRequest } from "./types";
+
+/** Finish a committed cancellation request; shared by interactive and routine cancellation. */
+export const finishAiTurnAbort = async (
+  input: { conversationId: string; turnId: string },
+  request: AiTurnAbortRequest,
+  active: Awaited<ReturnType<typeof aiConversations.getActiveTurn>> = null,
+): Promise<void> => {
+  if (!request.found) return;
+  // Tell any live owner to stop (its heartbeat also detects the cancel flag).
+  await publishAiTurnAbort(input).catch(() => undefined);
+
+  if (request.ownerless) {
+    const finalized = await aiConversations.completeTurn({ ...input, status: "aborted", error: null });
+    const config = await aiConversations.getTurnRunConfig(input);
+    if (finalized === "completed" && !(config?.kind === "chat" && config.background)) {
+      const attempt = active?.turn.id === input.turnId ? active.turn.attempt : 1;
+      const seq = (active?.turn.id === input.turnId ? active.liveSeq : 0) + 1;
+      await publishAiWireEvent({
+        v: 1,
+        conversationId: input.conversationId,
+        turnId: input.turnId,
+        attempt,
+        seq,
+        type: "turn_finished",
+        status: "aborted",
+        error: null,
+      }).catch(() => undefined);
+    }
+  }
+};

package/src/ai/types.ts

@@ -298,6 +298,10 @@ export type AiStoredMessage = {
       sourceHref?: string;
     };
     scheduledTask?: {
+      reason?: import("./chat-task-reasons").ChatTaskReason;
+      /** The message text is only the reason sentence; the chat words the reason itself instead. */
+      reasonOnly?: true;
+      stop?: { cause: "paused" | "deleted"; done: string[] };
       taskId: string;
       occurrenceId: string;
       scheduledFor: string;
@@ -613,6 +617,10 @@ export type AiConversationFileSnapshot = {
 };
 
 export type AiBackgroundRunContext = {
+  scheduledFor?: string;
+  trigger?: "scheduled" | "manual";
+  timezone?: string;
+  stopDeliveredAt?: string;
   taskId: string;
   occurrenceId: string;
   context: Array<{ seq: number; kind: "message" | "summary"; message: Message }>;
@@ -977,7 +985,10 @@ export type AiConversationService = {
     seq: number;
   }): Promise<boolean>;
   /** Record an abort wish. The caller finalizes ownerless turns itself. */
-  requestTurnAbort(input: { conversationId: string; turnId: string; reason?: string }): Promise<AiTurnAbortRequest>;
+  requestTurnAbort(
+    input: { conversationId: string; turnId: string; reason?: string },
+    options?: { db: import("bun").SQL },
+  ): Promise<AiTurnAbortRequest>;
   completeTurn(input: {
     conversationId: string;
     turnId: string;