@k2b/cloud 0.27.0 → 0.29.0

package/src/ai/executor.ts

@@ -1,10 +1,12 @@
-import type { CompactEvent, LoopAggregate, NessiLoop, OutboundEvent } from "@k2b/nessi";
+import type { AssistantMessage, CompactEvent, LoopAggregate, NessiLoop, OutboundEvent } from "@k2b/nessi";
 import { compact, nessi } from "@k2b/nessi";
 import { listCapabilities } from "../_internal/registry";
 import type { CapabilityActionReview } from "../contracts/capabilities";
 import type { AccessSubject, RequestActor } from "../server";
 import { createHelpReader } from "../services/help";
 import { logger } from "../services/logging";
+import { getMandate } from "../services/mandates";
+import type { MandatePolicyV1 } from "../services/mandates/policy";
 import { coreSettings } from "../services/settings/api";
 import { normalizeLocale } from "../shared/locale";
 import {
@@ -14,11 +16,13 @@ import {
   aiTurnAllowsRememberedApprovals,
   hasRememberedAiToolApproval,
 } from "./approvals";
-import { isAssistantChatTurn } from "./assistant-models";
+import { aiChatAccessSubject, isAssistantChatTurn, resolveAssistantAudioModel } from "./assistant-models";
 import { CODE_RUNTIME_TOOL_NAMES } from "./browser-code-contracts";
-import { createAiToolResolver, createRunToolStore } from "./capabilities";
+import { type AiCapabilityCatalogEntry, createAiToolResolver, createRunToolStore } from "./capabilities";
 import { AiCapabilityExecutionError, executeAiCapability, resolveAiCapabilityActor, reviewAiCapability } from "./capability-execution";
-import { aiChatTasks } from "./chat-tasks";
+import { aiChatMessages } from "./chat/messages";
+import { aiTurnErrorText } from "./chat/turn-error";
+import { AiChatTaskAuthorityError, aiChatTasks } from "./chat-tasks";
 import { createCloudCompactFn } from "./compaction";
 import { createCloudAiCodeTools, createCloudAiLocalBashTool, createConfiguredDefaultCloudAiTools } from "./default-tools";
 import { aiFileStore } from "./files-store";
@@ -26,6 +30,7 @@ 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";
@@ -57,6 +62,16 @@ 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 { AiTranscriptionError } from "./transcription";
+import {
+  AiTurnFailure,
+  type AiTurnFailureInfo,
+  type AiTurnFailureReason,
+  aiTurnFailureFromThrown,
+  aiTurnReasonFromThrown,
+  rememberProviderErrors,
+} from "./turn-failure";
+import { type AiTurnGuidance, loadAiTurnGuidance } from "./turn-guidance";
 import { type AiTurnPolicyToolCall, applyAiTurnPolicy } from "./turn-policy";
 import { createTurnTimingRecorder, withDurableTurnTiming } from "./turn-timing";
 import type {
@@ -80,10 +95,17 @@ const AI_COALESCE_MS = 25;
 const AI_COALESCE_MAX_CHARS = 512;
 const AI_ACTION_BUDGET_MS = 24 * 60 * 60_000;
 
+// Failed generation can contain calls that nessi deliberately never executes or resumes.
+const isToolRound = (message: AssistantMessage): boolean =>
+  message.stopReason !== "error" &&
+  message.stopReason !== "interrupted" &&
+  message.stopReason !== "aborted" &&
+  message.content.some((block) => block.type === "tool_call");
+
 const toolRoundState = (messages: AiStoredMessage[]): { issued: number; completed: number } => {
   const completedCallIds = new Set(messages.flatMap(({ message }) => (message.role === "tool_result" ? [message.callId] : [])));
   const rounds = messages.flatMap(({ message }) => {
-    if (message.role !== "assistant") return [];
+    if (message.role !== "assistant" || !isToolRound(message)) return [];
     const callIds = message.content.flatMap((block) => (block.type === "tool_call" ? [block.id] : []));
     return callIds.length > 0 ? [callIds] : [];
   });
@@ -546,7 +568,10 @@ const materializeChatConfig = async (config: AiChatTurnRunConfig, signal: AbortS
     tools:
       source.kind === "default"
         ? [
-            ...(await createConfiguredDefaultCloudAiTools()),
+            ...(await createConfiguredDefaultCloudAiTools({
+              accessSubject: aiChatAccessSubject(config.actor),
+              allowedDataBoundaries: config.modelPolicy?.allowedDataBoundaries,
+            })),
             // 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),
@@ -564,7 +589,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 {
@@ -587,7 +612,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;
     }
 
@@ -611,8 +643,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;
     }
@@ -622,16 +655,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) {
@@ -686,7 +742,7 @@ export class AiTurnExecutor {
         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;
       }
@@ -709,7 +765,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;
@@ -732,8 +796,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;
     }
@@ -801,6 +869,20 @@ export class AiTurnExecutor {
           (tool) => (!allowed || allowed.has(tool.def.name)) && !(config.mandate && ["code_open", "code_secret"].includes(tool.def.name)),
         )
       : [];
+    let audioUnavailableInstruction: string | undefined;
+    if (
+      defaultToolSource &&
+      toolsSupported &&
+      [...(config.files?.attached ?? []), ...(config.files?.available ?? [])].some((file) => file.mediaType.startsWith("audio/")) &&
+      !sourceToolNames.includes("transcribe_audio")
+    ) {
+      try {
+        await resolveAssistantAudioModel(aiChatAccessSubject(config.actor), material.modelPolicy?.allowedDataBoundaries);
+      } catch (error) {
+        const reason = error instanceof AiTranscriptionError ? error.message : "Audio transcription is not available right now.";
+        audioUnavailableInstruction = `Audio files in this conversation cannot be transcribed: ${reason} Tell the user this reason when they ask about audio content.`;
+      }
+    }
     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.
@@ -865,8 +947,9 @@ export class AiTurnExecutor {
         turnId,
         pipeline,
         "failed",
-        error instanceof Error ? error.message : "Image preparation failed",
+        aiTurnFailureFromThrown(error, "Image preparation failed"),
         "chat",
+        promptLocale,
       );
       return;
     }
@@ -908,6 +991,52 @@ export class AiTurnExecutor {
 
     const appliedSteers: AiTurnSteer[] = [];
 
+    let mandatePolicy: MandatePolicyV1 | null | undefined;
+    if (config.background && config.mandate) {
+      mandatePolicy = null;
+      try {
+        const mandate = await getMandate(config.mandate.id);
+        if (mandate && mandate.state === "active" && mandate.revision === config.mandate.revision) {
+          mandatePolicy = mandate.policy;
+        } else {
+          backgroundError = "Scheduled task mandate is unavailable or changed; recreate or update the task.";
+        }
+      } catch {
+        backgroundError = "Scheduled task mandate could not be loaded; retry or update the task.";
+      }
+    }
+    if (backgroundError) {
+      signal.removeEventListener("abort", onSignal);
+      await this.finalize(
+        conversationId,
+        turnId,
+        pipeline,
+        "failed",
+        { error: { code: "not_allowed" }, detail: backgroundError, message: backgroundError },
+        "chat",
+        promptLocale,
+      );
+      return;
+    }
+    const authorizeBackground =
+      config.background && config.mandate
+        ? async (entry: AiCapabilityCatalogEntry, args: unknown) => {
+            try {
+              await aiChatTasks.authorizeCapability({
+                mandate: config.mandate!,
+                appId: entry.appId,
+                capabilityId: entry.operation.localId,
+                kind: entry.kind,
+                input: args,
+                approval: entry.kind === "action" && "approval" in entry.operation ? entry.operation.approval : undefined,
+              });
+            } catch (error) {
+              if (!(error instanceof AiChatTaskAuthorityError && error.code === "MANDATE_POLICY_DENIED"))
+                backgroundError = error instanceof Error ? error.message : "Background capability access denied";
+              throw error;
+            }
+          }
+        : undefined;
     const toolStore = config.background ? createRunToolStore(await aiConversations.getLoadedTools({ conversationId })) : aiConversations;
     const tools = toolActor
       ? createAiToolResolver({
@@ -915,6 +1044,7 @@ export class AiTurnExecutor {
           actor: capabilityAuthority?.actor ?? toolActor,
           staticTools: activeTools,
           allowedTools,
+          mandatePolicy,
           unofferedTools,
           runtimeContext: dynamicToolRuntimeContext,
           store: toolStore,
@@ -940,25 +1070,7 @@ export class AiTurnExecutor {
                   }),
               }
             : {}),
-          ...(config.background && config.mandate
-            ? {
-                authorizeBackground: async (entry, args) => {
-                  try {
-                    await aiChatTasks.authorizeCapability({
-                      mandate: config.mandate!,
-                      appId: entry.appId,
-                      capabilityId: entry.operation.localId,
-                      kind: entry.kind,
-                      input: args,
-                      approval: entry.kind === "action" && "approval" in entry.operation ? entry.operation.approval : undefined,
-                    });
-                  } catch (error) {
-                    backgroundError = error instanceof Error ? error.message : "Background capability access denied";
-                    throw error;
-                  }
-                },
-              }
-            : {}),
+          authorizeBackground,
           onReview: (callId, review) => {
             capabilityActionReviews.set(callId, review);
             if (review.approvalScope) rememberableCapabilityApprovals.set(callId, review.approvalScope);
@@ -967,16 +1079,7 @@ export class AiTurnExecutor {
             ? {
                 execute: async (entry, args, context) => {
                   try {
-                    if (config.background && config.mandate) {
-                      await aiChatTasks.authorizeCapability({
-                        mandate: config.mandate,
-                        appId: entry.appId,
-                        capabilityId: entry.operation.localId,
-                        kind: entry.kind,
-                        input: args,
-                        approval: entry.kind === "action" && "approval" in entry.operation ? entry.operation.approval : undefined,
-                      });
-                    }
+                    await authorizeBackground?.(entry, args);
                     const result = await executeAiCapability({
                       conversationId,
                       turnId,
@@ -1046,12 +1149,43 @@ export class AiTurnExecutor {
       skillSubject,
       activeTools.some((tool) => tool.def.name === "load_skill"),
     );
-    const workingPlan = (await aiConversations.getConversation({ conversationId }))?.todoPlan;
+    const chat = await aiConversations.getConversation({ conversationId });
+    const workingPlan = chat?.todoPlan;
+    const skillCatalogOffered = activeTools.some((tool) => tool.def.name === "load_skill");
+    const skillCreatorAvailable = availableSkills.some((skill) => skill.name === "skill-creator");
+    // Offer hints and the recent-work summary only guide a fresh turn a person follows; a resumed
+    // attempt after an approval or a scheduled run gets neither.
+    let guidance: AiTurnGuidance = {};
+    if (isFresh && !config.background && defaultToolSource && user && chat) {
+      try {
+        guidance = await loadAiTurnGuidance(
+          {
+            chat,
+            turnId,
+            ownerUserId: user.id,
+            input: config.input,
+            instructions: [settings.globalInstructions, config.project?.instructions, memory?.text],
+            skillOffers: skillCatalogOffered && skillCreatorAvailable && loadedSkills.length === 0,
+            memoryOffers: memoryToolEnabled,
+            hasAttachments: Boolean(config.files?.attached.length),
+          },
+          aiConversations,
+        );
+      } catch (error) {
+        log.warn("AI turn guidance unavailable; continuing without it", {
+          conversationId,
+          turnId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
     const systemPrompt = composeAiSystemPrompt({
       globalInstructions: settings.globalInstructions,
       loadedSkills,
       turnInstructions: [
         material.systemPrompt,
+        audioUnavailableInstruction,
+        guidance.offerHint,
         workingPlan
           ? `Current working plan (new todo_write results supersede this):\n${JSON.stringify({ todos: workingPlan.todos })}`
           : undefined,
@@ -1067,7 +1201,7 @@ export class AiTurnExecutor {
       project: config.project,
       files: config.files,
       projectToolEnabled,
-      skills: activeTools.some((tool) => tool.def.name === "load_skill") ? skillCatalog.skills : undefined,
+      skills: skillCatalogOffered ? skillCatalog.skills : undefined,
       omittedSkillCount: activeTools.some((tool) => tool.def.name === "search_skills") ? skillCatalog.omitted : 0,
       user,
       memoryEnabled: memoryActive,
@@ -1080,18 +1214,34 @@ export class AiTurnExecutor {
       timeZone,
       locale: promptLocale,
       interactive: !config.background,
-      skillCreatorAvailable: availableSkills.some((skill) => skill.name === "skill-creator"),
+      skillCreatorAvailable,
+      recentWork: guidance.recentWork,
     });
     // 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 providerNamesByCallId = new Map(
+      turnMessages.flatMap(({ message }) =>
+        message.role === "assistant"
+          ? message.content.flatMap((part) => (part.type === "tool_call" ? [[part.id, part.name] as const] : []))
+          : [],
+      ),
+    );
     const priorToolRounds = toolRoundState(turnMessages);
     const quotaSubject = accessSubjectForActor(material.actor);
     const deadline = claim.turn.deadline ? Date.parse(claim.turn.deadline) : null;
+    // 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(
-          assistantQuotaProvider(resolved.provider, config, quotaSubject, resolved.profile, turnId, conversationId),
+          rememberProviderErrors(
+            answerOpenToolCalls(assistantQuotaProvider(resolved.provider, config, quotaSubject, resolved.profile, turnId, conversationId)),
+            remember,
+          ),
           {
             deadline,
             delaysMs: this.config.providerRetryDelaysMs,
@@ -1111,7 +1261,7 @@ export class AiTurnExecutor {
       runBudgetMs: claim.turn.runBudgetMs ?? null,
       finishedToolCalls: turnBlocks
         .slice(turnBlocks.findLastIndex((block) => block.kind === "steer_applied") + 1)
-        .flatMap((block) => (block.kind === "tool" ? [block] : [])),
+        .flatMap((block) => (block.kind === "tool" ? [{ ...block, name: providerNamesByCallId.get(block.callId) ?? block.name }] : [])),
       onDecision: (decision) =>
         decision.kind === "hint"
           ? log.warn("AI turn got a loop hint", { conversationId, turnId, hints: decision.hints })
@@ -1136,7 +1286,14 @@ export class AiTurnExecutor {
         turnPolicy.noteSteering();
         return steers.map((steer) => steer.text);
       },
-      tools: turnPolicy.tools,
+      tools: async () => {
+        try {
+          return await turnPolicy.tools();
+        } catch (error) {
+          remember(aiTurnReasonFromThrown(error));
+          throw error;
+        }
+      },
       ...(turnPolicy.maxTurns === undefined ? {} : { maxTurns: turnPolicy.maxTurns }),
       temperature: resolved.profile.temperature,
       maxOutputTokens: resolved.profile.maxOutputTokens,
@@ -1178,6 +1335,7 @@ export class AiTurnExecutor {
       appliedSteers,
       noteToolRound: turnPolicy.noteToolRound,
       noteToolCall: turnPolicy.noteToolCall,
+      failureReason,
       onBackgroundBlocked: (message) => {
         backgroundError = message;
       },
@@ -1202,15 +1360,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);
@@ -1244,6 +1404,12 @@ export class AiTurnExecutor {
     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 {
@@ -1260,6 +1426,7 @@ export class AiTurnExecutor {
       appliedSteers,
       noteToolRound,
       noteToolCall,
+      failureReason,
     } = input;
     const stopHeartbeat = this.startHeartbeat(conversationId, turnId, abortController);
     let lastIssueMessage: string | null = null;
@@ -1333,7 +1500,7 @@ export class AiTurnExecutor {
             result: event.result,
             isError: event.isError === true,
           });
-        } else if (event.type === "turn_end" && event.message.content.some((block) => block.type === "tool_call")) {
+        } else if (event.type === "turn_end" && !abortController.signal.aborted && isToolRound(event.message)) {
           noteToolRound();
         } else if (event.type === "issue") {
           lastIssueMessage = event.issue.message;
@@ -1346,25 +1513,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);
@@ -1556,14 +1722,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;
@@ -1574,17 +1733,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({
@@ -1603,15 +1768,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) {
@@ -1619,8 +1790,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();
@@ -1629,9 +1800,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");
   }
 }
 
@@ -1838,14 +2009,6 @@ class StreamPipeline {
     await this.saving;
   }
 
-  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);
-  }
-
   /** Transient: says a model call is waiting to be retried. Snapshots never carry it. */
   async emitProviderRetry(): Promise<void> {
     const seq = this.nextSeq();

package/src/ai/file-media-type.ts

@@ -38,3 +38,7 @@ export const guessAiMediaType = (path: string): string => {
   const ext = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
   return MEDIA_TYPES[ext] ?? "application/octet-stream";
 };
+
+/** Image classification includes filenames when clients send a generic media type. */
+export const isAiImage = (path: string, mediaType: string): boolean =>
+  mediaType.startsWith("image/") || guessAiMediaType(path).startsWith("image/");