@k2b/cloud 0.26.0 → 0.28.0

package/src/ai/executor.ts

@@ -1,4 +1,4 @@
-import type { CompactEvent, LoopAggregate, NessiLoop, OutboundEvent, Provider, Tool, ToolResolver } from "@k2b/nessi";
+import type { CompactEvent, LoopAggregate, NessiLoop, OutboundEvent } from "@k2b/nessi";
 import { compact, nessi } from "@k2b/nessi";
 import { listCapabilities } from "../_internal/registry";
 import type { CapabilityActionReview } from "../contracts/capabilities";
@@ -15,8 +15,11 @@ import {
   hasRememberedAiToolApproval,
 } from "./approvals";
 import { isAssistantChatTurn } from "./assistant-models";
+import { CODE_RUNTIME_TOOL_NAMES } from "./browser-code-contracts";
 import { createAiToolResolver, createRunToolStore } from "./capabilities";
 import { AiCapabilityExecutionError, executeAiCapability, resolveAiCapabilityActor, reviewAiCapability } from "./capability-execution";
+import { aiChatMessages } from "./chat/messages";
+import { aiTurnErrorText } from "./chat/turn-error";
 import { aiChatTasks } from "./chat-tasks";
 import { createCloudCompactFn } from "./compaction";
 import { createCloudAiCodeTools, createCloudAiLocalBashTool, createConfiguredDefaultCloudAiTools } from "./default-tools";
@@ -25,10 +28,12 @@ import { aiMemories } from "./memories";
 import { createCloudAiMemoryTool } from "./memory-tool";
 import { recordAiMemoryWorkflowEvidence } from "./memory-workflow-evidence";
 import { aiModelAccess } from "./model-access";
+import { answerOpenToolCalls } from "./open-tool-calls";
 import { type AiUserPrefs, aiActorUser, aiUserPrefs } from "./prefs";
 import { createCloudAiReadProjectKnowledgeTool, createCloudAiSearchProjectTool } from "./project-tool";
 import { aiProjects } from "./projects";
 import {
+  AI_TURN_LEASE_MS,
   type AiTurnBlock,
   type AiWireEvent,
   applyWireEventToBlocks,
@@ -49,11 +54,21 @@ import { selectAiSkillCatalog } from "./skill-catalog";
 import { createCloudAiLoadSkillTool, createCloudAiSearchSkillsTool, loadSelectedAiSkills } from "./skill-tool";
 import { aiSkills } from "./skills";
 import { aiConversations } from "./store";
-import { publishAiWireEvent } from "./stream";
+import { AI_LIVE_SNAPSHOT_INTERVAL_MS, publishAiWireEvent } from "./stream";
 import { composeAiSystemPrompt } from "./system-prompt";
 import { aiToolAudit } from "./tool-audit";
+import { acceptCanonicalToolNames } from "./tool-call-names";
 import { resolveAiToolResultMaxChars } from "./tool-result-budget";
 import { aiToolPromptHints, type PreparedAiTools, prepareAiTools } from "./tools";
+import {
+  AiTurnFailure,
+  type AiTurnFailureInfo,
+  type AiTurnFailureReason,
+  aiTurnFailureFromThrown,
+  aiTurnReasonFromThrown,
+  rememberProviderErrors,
+} from "./turn-failure";
+import { type AiTurnPolicyToolCall, applyAiTurnPolicy } from "./turn-policy";
 import { createTurnTimingRecorder, withDurableTurnTiming } from "./turn-timing";
 import type {
   AiChatTurnRunConfig,
@@ -72,13 +87,9 @@ import { validateAiTurnRequest } from "./validate";
 
 const log = logger("ai:executor");
 
-const AI_TURN_LEASE_MS = 45_000;
 const AI_COALESCE_MS = 25;
 const AI_COALESCE_MAX_CHARS = 512;
-const AI_SNAPSHOT_INTERVAL_MS = 1_000;
 const AI_ACTION_BUDGET_MS = 24 * 60 * 60_000;
-const AI_FINAL_TOOL_ROUND_PROMPT = `# Final response
-The configured tool-round budget has been reached, so no more tools are available in this turn. Answer the user's request now with the best result supported by the evidence already gathered. State any material uncertainty or incomplete part clearly.`;
 
 const toolRoundState = (messages: AiStoredMessage[]): { issued: number; completed: number } => {
   const completedCallIds = new Set(messages.flatMap(({ message }) => (message.role === "tool_result" ? [message.callId] : [])));
@@ -93,50 +104,6 @@ const toolRoundState = (messages: AiStoredMessage[]): { issued: number; complete
   };
 };
 
-const applyToolRoundPolicy = (input: {
-  provider: Provider;
-  tools: Tool[] | ToolResolver;
-  maxToolRounds?: number;
-  issuedToolRounds: number;
-  completedToolRounds: number;
-}): { provider: Provider; tools: Tool[] | ToolResolver; maxTurns?: number; noteToolRound: () => void } => {
-  const limit = Math.floor(input.maxToolRounds ?? 0);
-  if (limit <= 0) return { provider: input.provider, tools: input.tools, noteToolRound: () => undefined };
-
-  const issuedAtStart = Math.max(0, Math.floor(input.issuedToolRounds));
-  let completed = Math.max(0, Math.floor(input.completedToolRounds));
-  let finalSynthesis = completed >= limit;
-  const tools: ToolResolver = async () => {
-    finalSynthesis = completed >= limit;
-    if (finalSynthesis) return [];
-    return typeof input.tools === "function" ? input.tools() : input.tools;
-  };
-  const provider: Provider = {
-    name: input.provider.name,
-    family: input.provider.family,
-    model: input.provider.model,
-    contextWindow: input.provider.contextWindow,
-    capabilities: input.provider.capabilities,
-    complete: (request) => input.provider.complete(request),
-    stream: async function* (request) {
-      yield* input.provider.stream(
-        finalSynthesis ? { ...request, systemPrompt: `${request.systemPrompt ?? ""}\n\n${AI_FINAL_TOOL_ROUND_PROMPT}`.trim() } : request,
-      );
-    },
-  };
-
-  // Nessi checks this before provider calls. The extra round is the tool-free
-  // synthesis call after the last allowed tool-using round.
-  return {
-    provider,
-    tools,
-    maxTurns: Math.max(1, limit - issuedAtStart + 1),
-    noteToolRound: () => {
-      completed += 1;
-    },
-  };
-};
-
 const indexConversationResources = async (input: Parameters<typeof aiConversations.indexConversationResources>[0]): Promise<void> => {
   try {
     await aiConversations.indexConversationResources(input);
@@ -162,6 +129,10 @@ const recordMemoryWorkflowEvidence = async (input: Parameters<typeof recordAiMem
   }
 };
 
+/**
+ * Indexes what a finished tool call read or delivered; never throws. A browser tool ends here too, once the turn
+ * continues with the result the browser reported.
+ */
 const indexConversationToolSource = async (input: {
   conversationId: string;
   turnId: string;
@@ -184,10 +155,45 @@ const indexConversationToolSource = async (input: {
         });
     }
     let source: Parameters<typeof aiConversations.indexConversationSource>[0]["source"] | null = null;
+    const args = typeof input.args === "object" && input.args !== null ? (input.args as Record<string, unknown>) : {};
+    const text = (value: unknown) => (typeof value === "string" ? value.trim() : "");
+    const result = typeof input.result === "object" && input.result !== null ? (input.result as Record<string, unknown>) : {};
     if (input.name === "web_search") {
-      const args = input.args;
-      const query = typeof args === "object" && args !== null && "query" in args && typeof args.query === "string" ? args.query.trim() : "";
-      source = { kind: "activity", key: "web_search", title: query || "Web search", preview: "Searched the web", icon: "ti ti-world" };
+      const query = text(args.query);
+      // One entry per query: each search is something the user may want to see that the assistant looked up.
+      const key = query ? `web_search:${query.replace(/\s+/gu, " ").toLocaleLowerCase()}` : "web_search";
+      source = { kind: "activity", key, title: query || "Web search", preview: "Searched the web", icon: "ti ti-world" };
+    } else if (input.name === "present" && text(result.path)) {
+      const path = text(result.path);
+      source = {
+        kind: "result",
+        key: path,
+        title: text(args.title) || path.slice(path.lastIndexOf("/") + 1),
+        preview: text(args.description) || undefined,
+        icon: "ti ti-file",
+      };
+    } else if (
+      input.name === "code_open" &&
+      text(args.id) &&
+      typeof input.result === "object" &&
+      input.result !== null &&
+      !("error" in input.result)
+    ) {
+      // The browser reports a failure as a result with an error, which reaches this point without isError.
+      source = {
+        kind: "result",
+        key: `assistant.artifact:${text(args.id)}`,
+        title: "Studio app",
+        icon: "ti ti-app-window",
+        ref: { type: "assistant.artifact", id: text(args.id) },
+      };
+    } else if (input.name === "code_present" && text(result.presentationId)) {
+      source = {
+        kind: "result",
+        key: `code_present:${input.callId}`,
+        title: text(args.title) || text(result.title) || "Visualization",
+        icon: "ti ti-chart-dots",
+      };
     } else if (input.name === "web_extract" && typeof input.result === "object" && input.result !== null) {
       const result = input.result as Record<string, unknown>;
       if (typeof result.url === "string" && result.url.trim()) {
@@ -552,8 +558,10 @@ const materializeChatConfig = async (config: AiChatTurnRunConfig, signal: AbortS
       source.kind === "default"
         ? [
             ...(await createConfiguredDefaultCloudAiTools()),
-            ...(config.clientToolIds?.includes("local_bash") ? [createCloudAiLocalBashTool()] : []),
-            ...createCloudAiCodeTools().filter((tool) => config.clientToolIds?.some((name) => name === tool.def.name)),
+            // Cloud runs the code tools itself; only tools a client must run wait for that client to declare them.
+            ...[createCloudAiLocalBashTool(), ...createCloudAiCodeTools()].filter(
+              (tool) => tool.location === "server" || config.clientToolIds?.some((name) => name === tool.def.name),
+            ),
           ]
         : [],
     toolApprovalContext: config.toolApprovalContext,
@@ -567,7 +575,7 @@ const materializeChatConfig = async (config: AiChatTurnRunConfig, signal: AbortS
 // ---------------------------------------------------------------------------
 
 type AttemptOutcome =
-  | { kind: "finished"; status: "completed" | "failed" | "aborted"; error: string | null; timing?: LoopAggregate["timing"] }
+  | { kind: "finished"; status: "completed" | "failed" | "aborted"; failure: AiTurnFailureInfo | null; timing?: LoopAggregate["timing"] }
   | { kind: "suspended" };
 
 export class AiTurnExecutor {
@@ -590,7 +598,14 @@ export class AiTurnExecutor {
       pipeline.seedBaseline(claim.liveBlocks ?? []);
       await pipeline.emitTurnStarted(claim.turn.modelProfileId ?? "");
       await pipeline.emitBaseline();
-      await this.finalize(conversationId, turnId, pipeline, "failed", "AI turn is missing its run configuration.", null);
+      await this.finalize(
+        conversationId,
+        turnId,
+        pipeline,
+        "failed",
+        { error: { code: "failed" }, detail: "AI turn is missing its run configuration." },
+        null,
+      );
       return;
     }
 
@@ -614,8 +629,9 @@ export class AiTurnExecutor {
         turnId,
         pipeline,
         "failed",
-        error instanceof Error ? error.message : "AI turn state could not be loaded.",
+        aiTurnFailureFromThrown(error, "AI turn state could not be loaded."),
         "chat",
+        claim.runConfig?.kind === "chat" ? claim.runConfig.locale : undefined,
       );
       return;
     }
@@ -625,16 +641,39 @@ export class AiTurnExecutor {
     await this.runChat(conversationId, turnId, claim, runConfig, pipeline, signal, false, attemptState);
   }
 
+  /**
+   * Ends the turn. A failure stores its reason twice: as a code on the turn's last message, which the chat words in
+   * the reader's language, and as text in the turn's language for readers without the chat view. The raw cause, such
+   * as a provider's own message, goes only to the log. A failed compaction left the chat as it was, so its text names
+   * only the reason.
+   */
   private async finalize(
     conversationId: string,
     turnId: string,
     pipeline: StreamPipeline,
     status: "completed" | "failed" | "aborted",
-    error: string | null,
+    failure: AiTurnFailureInfo | null,
     kind: AiTurnRunConfig["kind"] | null,
+    locale?: string,
   ) {
-    if (status === "failed" && error) log.error("AI turn failed", { conversationId, turnId, error });
-    const finalized = await aiConversations.completeTurn({ conversationId, turnId, status, error, leaseOwner: this.config.leaseOwner });
+    const failed = status === "failed" ? (failure ?? { error: { code: "failed" as const }, detail: "AI turn failed" }) : null;
+    let error: string | null = null;
+    if (failed) {
+      log.error("AI turn failed", { conversationId, turnId, code: failed.error.code, error: failed.detail });
+      error = failed.message ?? null;
+      if (!error) {
+        const textLocale = normalizeLocale(locale ?? (await coreSettings.get<string>("app.locale")));
+        error = kind === "compact" ? aiChatMessages(textLocale).turnErrorReason(failed.error) : aiTurnErrorText(failed.error, textLocale);
+      }
+    }
+    const finalized = await aiConversations.completeTurn({
+      conversationId,
+      turnId,
+      status,
+      error,
+      turnError: failed?.error ?? null,
+      leaseOwner: this.config.leaseOwner,
+    });
     if (finalized === "completed") await pipeline.emitTurnFinished(status, error);
     await pipeline.flush().catch(() => undefined);
     if (finalized === "completed" && this.config.onTurnFinalized) {
@@ -671,6 +710,7 @@ export class AiTurnExecutor {
     let resolvedProjectId: string | null = null;
     let chatId = config.chatId ?? "";
     let allowedTools: string[] | null = null;
+    let sourceToolNames: string[] = [];
     try {
       if (config.background && !config.mandate) throw new Error("Background execution requires its task mandate.");
       const [nextMaterial, conversation] = await Promise.all([
@@ -681,13 +721,14 @@ export class AiTurnExecutor {
       if (!conversation) throw new Error("Conversation is no longer available.");
       allowedTools = conversation.allowedTools ?? null;
       const allowed = allowedTools === null ? null : new Set(allowedTools);
+      sourceToolNames = material.tools.map((tool) => tool.def.name);
       if (allowed) material.tools = material.tools.filter((tool) => allowed.has(tool.def.name));
       chatId ||= conversation?.shortId ?? "";
       if (config.project) {
         const subject = accessSubjectForActor(material.actor);
         const project = subject ? await aiProjects.getByShortId(config.project.id, subject, "read") : null;
         if (!project) {
-          throw new Error("Project access is no longer available.");
+          throw new AiTurnFailure("not_allowed", "Project access is no longer available.");
         }
         resolvedProjectId = project.id;
       }
@@ -710,7 +751,15 @@ export class AiTurnExecutor {
       }
     } catch (error) {
       signal.removeEventListener("abort", onSignal);
-      await this.finalize(conversationId, turnId, pipeline, "failed", error instanceof Error ? error.message : "AI turn failed", "chat");
+      await this.finalize(
+        conversationId,
+        turnId,
+        pipeline,
+        "failed",
+        aiTurnFailureFromThrown(error, "AI turn failed"),
+        "chat",
+        config.locale,
+      );
       return;
     }
     const { settings, resolved } = validated;
@@ -733,8 +782,12 @@ export class AiTurnExecutor {
         turnId,
         pipeline,
         "failed",
-        error instanceof Error ? error.message : "Cloud capability actor resolution failed",
+        {
+          error: { code: "not_allowed" },
+          detail: error instanceof Error ? error.message : "Cloud capability actor resolution failed",
+        },
         "chat",
+        config.locale,
       );
       return;
     }
@@ -802,6 +855,12 @@ export class AiTurnExecutor {
           (tool) => (!allowed || allowed.has(tool.def.name)) && !(config.mandate && ["code_open", "code_secret"].includes(tool.def.name)),
         )
       : [];
+    const offeredToolNames = new Set(activeTools.map((tool) => tool.def.name));
+    // Built-ins that exist but this turn does not offer: client tools without their client, tools a
+    // task cannot use, and tools outside the conversation's fixed scope. load_tools explains each one.
+    const unofferedTools = [
+      ...new Set([...sourceToolNames, ...runtimeTools.map((tool) => tool.def.name), ...CODE_RUNTIME_TOOL_NAMES, "local_bash"]),
+    ].filter((name) => !offeredToolNames.has(name));
     const memoryToolEnabled = activeTools.some((tool) => tool.def.name === "memory");
     const projectToolEnabled = activeTools.some((tool) => tool.def.name === "search_project");
 
@@ -860,8 +919,9 @@ export class AiTurnExecutor {
         turnId,
         pipeline,
         "failed",
-        error instanceof Error ? error.message : "Image preparation failed",
+        aiTurnFailureFromThrown(error, "Image preparation failed"),
         "chat",
+        promptLocale,
       );
       return;
     }
@@ -910,6 +970,7 @@ export class AiTurnExecutor {
           actor: capabilityAuthority?.actor ?? toolActor,
           staticTools: activeTools,
           allowedTools,
+          unofferedTools,
           runtimeContext: dynamicToolRuntimeContext,
           store: toolStore,
           ...(capabilityAuthority ? { listRegistry: listCapabilities } : {}),
@@ -1073,32 +1134,57 @@ export class AiTurnExecutor {
       memory: memory?.text,
       timeZone,
       locale: promptLocale,
+      interactive: !config.background,
+      skillCreatorAvailable: availableSkills.some((skill) => skill.name === "skill-creator"),
     });
-    const priorToolRounds = toolRoundState(loopMessages);
+    // The turn policy counts the whole turn, including rounds that compaction archived.
+    const turnMessages = await aiConversations.listTurnMessages({ conversationId, loopId: turnId, includeCompacted: true });
+    const turnBlocks = buildBlocksFromMessages(turnMessages);
+    const priorToolRounds = toolRoundState(turnMessages);
     const quotaSubject = accessSubjectForActor(material.actor);
     const deadline = claim.turn.deadline ? Date.parse(claim.turn.deadline) : null;
-    const toolRoundPolicy = applyToolRoundPolicy({
-      provider: retryTransientProviderErrors(
-        assistantQuotaProvider(resolved.provider, config, quotaSubject, resolved.profile, turnId, conversationId),
-        {
-          deadline,
-          delaysMs: this.config.providerRetryDelaysMs,
-          onRetry: async ({ retry, delayMs, issue }) => {
-            log.warn("AI provider call retried", { conversationId, turnId, retry, delayMs, kind: issue.kind, message: issue.message });
-            await pipeline.emitProviderRetry();
+    // The reason a failed turn names: the one the current model call or the turn's own checks gave.
+    const failureReason: { current: AiTurnFailureReason | null } = { current: null };
+    const remember = (reason: AiTurnFailureReason | null) => {
+      failureReason.current = reason;
+    };
+    const turnPolicy = applyAiTurnPolicy({
+      provider: acceptCanonicalToolNames(
+        retryTransientProviderErrors(
+          rememberProviderErrors(
+            answerOpenToolCalls(assistantQuotaProvider(resolved.provider, config, quotaSubject, resolved.profile, turnId, conversationId)),
+            remember,
+          ),
+          {
+            deadline,
+            delaysMs: this.config.providerRetryDelaysMs,
+            onRetry: async ({ retry, delayMs, issue }) => {
+              log.warn("AI provider call retried", { conversationId, turnId, retry, delayMs, kind: issue.kind, message: issue.message });
+              await pipeline.emitProviderRetry();
+            },
           },
-        },
+        ),
+        prepared.canonicalNames,
       ),
       tools,
       maxToolRounds: resolved.profile.maxToolRounds,
       issuedToolRounds: priorToolRounds.issued,
       completedToolRounds: priorToolRounds.completed,
+      deadline,
+      runBudgetMs: claim.turn.runBudgetMs ?? null,
+      finishedToolCalls: turnBlocks
+        .slice(turnBlocks.findLastIndex((block) => block.kind === "steer_applied") + 1)
+        .flatMap((block) => (block.kind === "tool" ? [block] : [])),
+      onDecision: (decision) =>
+        decision.kind === "hint"
+          ? log.warn("AI turn got a loop hint", { conversationId, turnId, hints: decision.hints })
+          : log.info("AI turn answers without further tools", { conversationId, turnId, reason: decision.reason }),
     });
     const loop = nessi({
       agentId: "cloud",
       loopId: turnId,
       ...(isFresh ? { input: turnInput } : {}),
-      provider: toolRoundPolicy.provider,
+      provider: turnPolicy.provider,
       systemPrompt,
       store,
       steering: async ({ signal: steeringSignal }) => {
@@ -1109,12 +1195,22 @@ export class AiTurnExecutor {
           leaseOwner: this.config.leaseOwner,
         });
         appliedSteers.push(...steers);
-        return steers.length > 0 ? steers.map((steer) => steer.text) : undefined;
+        if (steers.length === 0) return undefined;
+        turnPolicy.noteSteering();
+        return steers.map((steer) => steer.text);
+      },
+      tools: async () => {
+        try {
+          return await turnPolicy.tools();
+        } catch (error) {
+          remember(aiTurnReasonFromThrown(error));
+          throw error;
+        }
       },
-      tools: toolRoundPolicy.tools,
-      ...(toolRoundPolicy.maxTurns === undefined ? {} : { maxTurns: toolRoundPolicy.maxTurns }),
+      ...(turnPolicy.maxTurns === undefined ? {} : { maxTurns: turnPolicy.maxTurns }),
       temperature: resolved.profile.temperature,
       maxOutputTokens: resolved.profile.maxOutputTokens,
+      reasoningEffort: resolved.profile.reasoningEffort,
       coalesce: { ms: AI_COALESCE_MS, maxChars: AI_COALESCE_MAX_CHARS },
       compact: config.background
         ? undefined
@@ -1150,7 +1246,9 @@ export class AiTurnExecutor {
       rememberableCapabilityApprovals,
       capabilityActionReviews,
       appliedSteers,
-      noteToolRound: toolRoundPolicy.noteToolRound,
+      noteToolRound: turnPolicy.noteToolRound,
+      noteToolCall: turnPolicy.noteToolCall,
+      failureReason,
       onBackgroundBlocked: (message) => {
         backgroundError = message;
       },
@@ -1175,15 +1273,17 @@ export class AiTurnExecutor {
           : null;
     if (timeout) {
       outcome.status = "failed";
-      outcome.error = timeout.messageFor(promptLocale);
+      outcome.failure = { error: timeout.turnError(), detail: "Run time limit reached." };
     }
     const finalized = await this.finalize(
       conversationId,
       turnId,
       pipeline,
       backgroundError ? "failed" : outcome.status,
-      backgroundError ?? outcome.error,
+      // A background run keeps Cloud's own words for what its mandate blocked.
+      backgroundError ? { error: { code: "not_allowed" }, detail: backgroundError, message: backgroundError } : outcome.failure,
       "chat",
+      promptLocale,
     );
     if (finalized === "pending_steering" && outcome.status === "completed" && !signal.aborted) {
       await this.runChat(conversationId, turnId, claim, config, pipeline, signal, true);
@@ -1216,6 +1316,13 @@ export class AiTurnExecutor {
     capabilityActionReviews: ReadonlyMap<string, CapabilityActionReview>;
     appliedSteers: AiTurnSteer[];
     noteToolRound: () => void;
+    noteToolCall: (call: AiTurnPolicyToolCall) => void;
+    /**
+     * Why the turn would fail now, as a model call or the turn's own checks said. A new model call starts without one,
+     * so a context overflow that compaction resolved never names a later failure. Only the model calls and checks set
+     * it, in the order they run; the events here arrive later than that.
+     */
+    failureReason: { current: AiTurnFailureReason | null };
     onBackgroundBlocked?: (message: string) => void;
   }): Promise<AttemptOutcome> {
     const {
@@ -1231,6 +1338,8 @@ export class AiTurnExecutor {
       capabilityActionReviews,
       appliedSteers,
       noteToolRound,
+      noteToolCall,
+      failureReason,
     } = input;
     const stopHeartbeat = this.startHeartbeat(conversationId, turnId, abortController);
     let lastIssueMessage: string | null = null;
@@ -1289,6 +1398,12 @@ export class AiTurnExecutor {
             .noteToolCompleted({ turnId, callId: event.callId, isError: event.isError })
             .catch(() => log.warn("AI tool audit write failed", { code: "tool_audit_complete_failed", turnId, callId: event.callId }));
           const toolBlock = pipeline.blocks.find((block) => block.kind === "tool" && block.callId === event.callId);
+          // The policy keys calls by the name the model called, as the persisted calls it seeds from.
+          noteToolCall(
+            toolBlock?.kind === "tool"
+              ? { ...toolBlock, name: event.name }
+              : { name: event.name, status: event.isError ? "failed" : "completed", result: event.result },
+          );
           await indexConversationToolSource({
             conversationId,
             turnId,
@@ -1311,25 +1426,24 @@ export class AiTurnExecutor {
               .catch(() => undefined);
           }
           const timing = aggregate.timing;
-          if (event.reason === "aborted") return { kind: "finished", status: "aborted", error: null, timing };
-          if (event.reason === "stop") return { kind: "finished", status: "completed", error: null, timing };
-          if (event.reason === "max_turns") {
-            return {
-              kind: "finished",
-              status: "failed",
-              error: "The model did not produce a final answer within its tool-round limit.",
-              timing,
-            };
-          }
-          return { kind: "finished", status: "failed", error: lastIssueMessage ?? `AI turn ended: ${event.reason}`, timing };
+          if (event.reason === "aborted") return { kind: "finished", status: "aborted", failure: null, timing };
+          if (event.reason === "stop") return { kind: "finished", status: "completed", failure: null, timing };
+          const detail = lastIssueMessage ?? `AI turn ended: ${event.reason}`;
+          const reason: AiTurnFailureReason =
+            event.reason === "max_turns"
+              ? { error: { code: "step_limit" } }
+              : event.reason === "context_overflow"
+                ? { error: { code: "context_full" } }
+                : event.reason === "no_credits"
+                  ? { error: { code: "quota_exhausted" } }
+                  : (failureReason.current ?? { error: { code: "failed" } });
+          return { kind: "finished", status: "failed", failure: { ...reason, detail }, timing };
         }
       }
-      return { kind: "finished", status: abortController.signal.aborted ? "aborted" : "completed", error: null };
+      return { kind: "finished", status: abortController.signal.aborted ? "aborted" : "completed", failure: null };
     } catch (error) {
-      if (abortController.signal.aborted) return { kind: "finished", status: "aborted", error: null };
-      const message = error instanceof Error ? error.message : "AI turn failed";
-      await pipeline.emitError(message).catch(() => undefined);
-      return { kind: "finished", status: "failed", error: message };
+      if (abortController.signal.aborted) return { kind: "finished", status: "aborted", failure: null };
+      return { kind: "finished", status: "failed", failure: aiTurnFailureFromThrown(error, "AI turn failed") };
     } finally {
       stopHeartbeat();
       await pipeline.flush().catch(() => undefined);
@@ -1521,14 +1635,7 @@ export class AiTurnExecutor {
       });
     } catch (error) {
       signal.removeEventListener("abort", onSignal);
-      await this.finalize(
-        conversationId,
-        turnId,
-        pipeline,
-        "failed",
-        error instanceof Error ? error.message : "AI compaction failed",
-        "compact",
-      );
+      await this.finalize(conversationId, turnId, pipeline, "failed", aiTurnFailureFromThrown(error, "AI compaction failed"), "compact");
       return;
     }
     const { settings, resolved } = validated;
@@ -1539,17 +1646,23 @@ export class AiTurnExecutor {
       turnId,
       leaseOwner: this.config.leaseOwner,
     });
+    const reason: { current: AiTurnFailureReason | null } = { current: null };
     const loop = compact({
       agentId: "cloud",
       loopId: turnId,
       store,
-      provider: inferenceProvider(resolved.provider, resolved.profile, {
-        kind: "background",
-        task: "chat-compaction",
-        conversationId,
-        turnId,
-        appId: "core",
-      }),
+      provider: rememberProviderErrors(
+        inferenceProvider(resolved.provider, resolved.profile, {
+          kind: "background",
+          task: "chat-compaction",
+          conversationId,
+          turnId,
+          appId: "core",
+        }),
+        (remembered) => {
+          reason.current = remembered;
+        },
+      ),
       force: true,
       signal: abortController.signal,
       compact: createCloudCompactFn({
@@ -1568,15 +1681,21 @@ export class AiTurnExecutor {
 
     const stopHeartbeat = this.startHeartbeat(conversationId, turnId, abortController);
     let status: "completed" | "failed" | "aborted" = "failed";
-    let error: string | null = null;
+    let failure: AiTurnFailureInfo | null = null;
+    let issueMessage: string | null = null;
     try {
       for await (const event of loop as AsyncIterable<CompactEvent>) {
         if (event.type === "compaction_start") await pipeline.applyCompaction("running");
         else if (event.type === "compaction_end") await pipeline.applyCompaction("completed");
-        else if (event.type === "issue") error = event.issue.message;
+        else if (event.type === "issue") issueMessage = event.issue.message;
         else if (event.type === "loop_end") {
           status = event.reason === "stop" ? "completed" : event.reason === "aborted" ? "aborted" : "failed";
           await pipeline.applyCompaction(status === "failed" ? "failed" : "completed", event.result);
+          if (status === "failed")
+            failure = {
+              ...(reason.current ?? { error: { code: "failed" } }),
+              detail: issueMessage ?? `AI compaction ended: ${event.reason}`,
+            };
         }
       }
     } catch (err) {
@@ -1584,8 +1703,8 @@ export class AiTurnExecutor {
         status = "aborted";
       } else {
         status = "failed";
-        error = err instanceof Error ? err.message : "AI compaction failed";
-        await pipeline.emitError(error).catch(() => undefined);
+        const thrown = aiTurnFailureFromThrown(err, "AI compaction failed");
+        failure = reason.current ? { ...reason.current, detail: thrown.detail } : thrown;
       }
     } finally {
       stopHeartbeat();
@@ -1594,9 +1713,9 @@ export class AiTurnExecutor {
 
     if (abortController.signal.reason instanceof AiRunTimeout) {
       status = "failed";
-      error = abortController.signal.reason.messageFor();
+      failure = { error: abortController.signal.reason.turnError(), detail: "Run time limit reached." };
     }
-    await this.finalize(conversationId, turnId, pipeline, status, error, "compact");
+    await this.finalize(conversationId, turnId, pipeline, status, failure, "compact");
   }
 }
 
@@ -1620,6 +1739,9 @@ class StreamPipeline {
   readonly timing: ReturnType<typeof createTurnTimingRecorder>;
   private lastSnapshotAt = 0;
   private snapshotDirty = false;
+  private snapshotTimer: ReturnType<typeof setTimeout> | undefined;
+  /** The newest save of the live state. Saves run one after another, so an older one never lands last. */
+  private saving: Promise<void> = Promise.resolve();
   private chain: Promise<void> = Promise.resolve();
 
   constructor(input: {
@@ -1651,6 +1773,8 @@ class StreamPipeline {
 
   private nextSeq(): number {
     this.seq += 1;
+    // The saved state follows every event, so a reader that reloads it catches up with the live stream.
+    this.snapshotDirty = true;
     return this.seq;
   }
 
@@ -1699,12 +1823,14 @@ class StreamPipeline {
       const seq = this.nextSeq();
       await this.publish(this.envelope({ type: "block_set" as const, seq, block }) as AiWireEvent);
     }
-    this.snapshotDirty = this.blocks.length > 0;
+    // A new attempt's baseline is saved at once: a stream that reloads the turn must not wait for the first model event.
+    await this.maybeSnapshot();
   }
 
   async emitMessage(message: AiStoredMessage): Promise<void> {
     const seq = this.nextSeq();
     await this.publish(this.envelope({ type: "message_saved" as const, seq, message }));
+    await this.maybeSnapshot();
   }
 
   async emitTurnStarted(modelProfileId: string): Promise<void> {
@@ -1764,38 +1890,43 @@ class StreamPipeline {
     await this.publish(event);
   }
 
+  /**
+   * Saves the live state at most once per interval. A change inside the interval is saved when it ends, even if no
+   * event follows, so the saved state lags the live stream by at most one interval.
+   */
   private async maybeSnapshot(): Promise<void> {
     if (!this.snapshotDirty) return;
-    if (Date.now() - this.lastSnapshotAt < AI_SNAPSHOT_INTERVAL_MS) return;
+    const wait = AI_LIVE_SNAPSHOT_INTERVAL_MS - (Date.now() - this.lastSnapshotAt);
+    if (wait > 0) {
+      this.snapshotTimer ??= setTimeout(() => {
+        this.snapshotTimer = undefined;
+        void this.maybeSnapshot();
+      }, wait);
+      return;
+    }
     await this.persistSnapshot();
   }
 
   async persistSnapshot(): Promise<void> {
+    this.cancelSnapshotTimer();
     this.lastSnapshotAt = Date.now();
     this.snapshotDirty = false;
-    await aiConversations
-      .saveTurnLiveState({
-        conversationId: this.conversationId,
-        turnId: this.turnId,
-        leaseOwner: this.leaseOwner,
-        blocks: this.blocks,
-        seq: this.seq,
-      })
-      .catch(() => undefined);
-  }
-
-  async emitError(message: string): Promise<void> {
-    const seq = this.nextSeq();
-    const block: AiTurnBlock = { id: `error-${this.attempt}-${seq}`, kind: "text", text: `⚠️ ${message}` };
-    const event = this.envelope({ type: "block_set" as const, seq, block }) as AiWireEvent;
-    this.blocks = applyWireEventToBlocks(this.blocks, event);
-    await this.publish(event);
+    const blocks = this.blocks;
+    const seq = this.seq;
+    this.saving = this.saving.then(() =>
+      aiConversations
+        .saveTurnLiveState({ conversationId: this.conversationId, turnId: this.turnId, leaseOwner: this.leaseOwner, blocks, seq })
+        .then(() => undefined)
+        .catch(() => undefined),
+    );
+    await this.saving;
   }
 
   /** Transient: says a model call is waiting to be retried. Snapshots never carry it. */
   async emitProviderRetry(): Promise<void> {
     const seq = this.nextSeq();
     await this.publish(this.envelope({ type: "provider_retry" as const, seq }));
+    await this.maybeSnapshot();
   }
 
   async emitTurnFinished(status: "completed" | "failed" | "aborted", error: string | null): Promise<void> {
@@ -1808,15 +1939,24 @@ class StreamPipeline {
     return this.ordered(() => publishAiWireEvent(event).catch(() => undefined));
   }
 
+  private cancelSnapshotTimer(): void {
+    if (this.snapshotTimer) clearTimeout(this.snapshotTimer);
+    this.snapshotTimer = undefined;
+  }
+
+  /**
+   * Waits for every publish and save. The attempt ends here: a later save would overwrite what suspension or the next
+   * attempt saved.
+   */
   async flush(): Promise<void> {
-    await this.chain;
+    this.cancelSnapshotTimer();
+    await Promise.all([this.chain, this.saving]);
   }
 }
 
 export const __aiExecutorTest = {
   indexConversationToolSource,
   StreamPipeline,
-  applyToolRoundPolicy,
   createEventMapper,
   rebuildAttemptBaseline,
   rebuildBlocksFromMessages,