@k2b/cloud 0.27.0 → 0.28.0

package/src/ai/code-runtime-tools.ts

@@ -100,7 +100,11 @@ export const runManagedCodeTool =
       const headers = new Headers({ authorization: `Bearer ${signed.token}`, "content-type": "application/json" });
       headers.set(CODE_CAPABILITY_TOKEN_HEADER, callback.token);
       if (context.locale) headers.set(LOCALE_HEADER, context.locale);
-      if (context.timeZone) headers.set("cookie", `${TIMEZONE_COOKIE}=${encodeURIComponent(context.timeZone)}`);
+      const timeZone = runConfig.timeZone ?? context.timeZone;
+      headers.set(
+        "cookie",
+        [`theme=${runConfig.theme ?? "light"}`, ...(timeZone ? [`${TIMEZONE_COOKIE}=${encodeURIComponent(timeZone)}`] : [])].join("; "),
+      );
       const response = await fetch(new URL(`/_internal/assistant/tools/${name}`, app.baseUrl), {
         method: "POST",
         headers,

package/src/ai/code-source-contracts.ts

@@ -41,7 +41,7 @@ const DatabaseSql = z.object({
 
 const CodeWriteInput = Id.extend({
   expectedRevision: z.number().int().positive(),
-  entry: ArtifactPath.optional(),
+  entry: ArtifactPath.optional().describe("index.html for an app with an interface, or the script that code_run executes."),
   files: z
     .array(z.union([ArtifactFile, z.object({ path: ArtifactPath, fromFile: AiFileReference }).strict()]))
     .min(1)
@@ -302,7 +302,7 @@ export const CODE_SOURCE_TOOLS = {
   },
   code_create: {
     description:
-      "Create a private reusable App with an optional UI, published actions and optional persistence. For one-off analysis, use code_run with code instead. Returns id and entry path; write source with code_write. Optional icon uses the complete class, e.g. ti ti-chart-bar; omit it when unsure. Does not run or share anything.",
+      "Create a private reusable App: an index.html interface with optional style.css and app.js, published actions and optional persistence. Starts with a minimal index.html. For one-off analysis, use code_run with code instead. Returns id and entry path; write source with code_write. Optional icon uses the complete class, e.g. ti ti-chart-bar; omit it when unsure. Does not run or share anything.",
     input: ArtifactCreate.pick({ title: true, description: true, icon: true }),
   },
   code_write: {

package/src/ai/data-analysis-skill.ts

@@ -2,9 +2,9 @@
 import type { AiSkillTemplate } from "./skills";
 export const ASSISTANT_DATA_ANALYSIS_SKILL = {
   "key": "assistant:data-analysis",
-  "version": 7,
+  "version": 8,
   "name": "assistant-data-analysis",
-  "description": "Analyze source data, explain metrics and comparisons, and build evidence-backed reports or interactive dashboards in Assistant Code Mode. Use for multi-step analysis, data exploration, and dashboards; a simple chart only needs the Code Mode charts reference.",
-  "instructions": "# Analyze data and deliver an inspectable result\n\nStart with the question the reader needs to answer. Choose a direct answer,\nan interactive visualization in this chat, an exported file, or a reusable Studio app accordingly.\nFor a one-time visual analysis, prefer a chat visualization; filters and buttons\ndo not by themselves require a Studio App.\nLoad `assistant-code-mode` for execution and read its `references/analytics.md`\nfor the built-in UI. Loading this skill does not install a library or grant access.\n\n## Keep a working plan\n\nFor work with several real steps, use `todo_write` to keep a short chat plan.\nReplace the full `todos` list each time; give each item a stable `id`, actionable\n`content`, and `status` (`pending`, `in_progress`, `completed`, or `cancelled`).\nAt most one step is active. Update as work changes, including user corrections;\nmark a step completed only after doing and checking it. Preserve exact commands\nwhen they matter. Skip this tool for a simple calculation or conversational reply.\n\nFor analysis, useful steps are reconcile source data, build the analysis, and\nverify totals, filters and conclusions. A rendered dashboard alone is not proof\nthat its numbers are correct. Keep blocked source work open and explain why.\n\n## Establish the data\n\nIdentify the actual source, unit of observation, time window, timezone, and\nlatest complete period. Read files or discover the relevant Cloud capabilities\nbefore selecting fields. External APIs use `cloud.http.fetch`; credentials are entered\nonly through the trusted `code_secret` dialog.\n\nInspect a bounded sample, missing values, duplicate keys, types, and coverage.\nReconcile totals and join cardinalities before drawing conclusions. Keep raw\nnumbers separate from display formatting. Distinguish zero from unavailable data;\nstate exclusions and denominator choices. Do not substitute fixture data for a\nblocked source unless the user requested a mockup.\n\nKeep the source query or transformation in the saved source or an accompanying\nfile so another run can reproduce the result. Preserve the source identity and\nretrieval timestamp, without credentials or credential-bearing URLs.\n\n## Build one consistent analysis\n\nDerive charts, metrics, and tables from the same reviewed data. Aggregate large\ninputs before crossing the UI bridge. Chart Explorer rows identify selectable\nentities with stable string keys; derived bins and groups need explicit mark\nmappings. Shared keys across charts mean the same entity, not equal values.\n\nChoose the simplest chart that answers the question. Use tables for exact\nrecords, bars for category comparisons, lines for ordered trends, and distributions\nfor spread. State units, comparison windows, and whether a percent is a fraction\nor an already scaled number. Do not imply causation from correlation.\n\nLead reports with the finding, then supporting evidence and limitations.\nLead dashboards with the important measurements, then trends and diagnostic\nbreakdowns. Use shared filters only when they affect all claimed views. Keep the\ninitial view useful without interaction. Avoid unrelated metrics added merely to\nfill a grid.\n\nAttach source context to Explorer data: `mode`, `asOf`, `sources`, and relevant\n`status`/`note`. A timestamp records when the data was retrieved; it does not prove\nthat the upstream source is complete. Label partial or fixture data visibly.\n\n## Validate before delivery\n\nRun the actual source with `code_run`. Inspect the result; use `code_interact`\nwith structured UI events to test filters, chart/table switching, selection,\nempty results, and recovery from a failed load. Reconcile displayed values with\nthe reviewed totals and check that filters describe the data actually displayed.\nA successful schema validation does not establish analytical correctness.\n\nValidate the actual presented source (the saved revision for Apps), rather than pasting its formulas into a\nsecond test script. Keep an independent expectation from the input data: row\ncounts, unmatched joins, totals and representative boundary cases. For targets,\nstate their grain (for example month × region) and aggregate each target once;\nmultiple selected regions must sum their distinct targets. Compare inspected raw\nKPI values and plotted series with independent expectations. A formatted value\nmatching after rounding does not validate the raw ratio. Never round fractions\nbefore passing them to percent-formatted controls. Preserve precision\nuntil display formatting. Test reset, one/multiple/all selections, empty results,\nand complete versus partial periods. A newly generated timestamp is not source\nfreshness: keep the real retrieval or file-snapshot timestamp stable.\n\nFor a Studio App data snapshot, export the validated dataset with `cloud.download` and\n`code_export`, then copy its exact path/version into the resource with\n`code_write({id,expectedRevision,files:[{path:\"data.json\",fromFile:reference}]})`.\nObtain the exact reference with `code_file_stat`; importing private files into\nApp source receives fresh review.\nImport that file in the app. Never rebuild a truncated dataset by copying tool\noutput. Keep transformations and source identity alongside the snapshot.\n\nHuman approval and uncertain HTTP outcomes follow the Code Mode HTTP contract.\nDo not replay an external mutation to refresh a chart. Separate local filtering\nfrom external loading; an Apply button can avoid a request for every slider move.\n\n## Save, share, and hand off\n\nFor chat visualizations, test `code_run` and relevant `code_interact` controls,\nthen deliver with `code_present({runId,title})`. A successful run alone is not\nvisible to the user. Retain source identity, reviewed input data and their real\nretrieval timestamp. Put writes and external reloads behind explicit buttons;\nopening an old result must not repeat earlier actions. The user can download the\ncurrent view as PDF/HTML or an individual chart as SVG.\n\nFor reusable Studio Apps, reuse one Cloud resource for later revisions of the same report or dashboard.\nSave its source, test that revision, and use the normal Code Mode publication\nworkflow when publication is requested. Publishing a version and granting reader\naccess are separate operations. Preserve existing access; a dashboard request\ndoes not authorize broadening it. Personal secrets are never copied to readers.\n\nA published source version is not automatically a frozen data snapshot. A frozen\nreport must retain the reviewed data explicitly in its authorized resource or\noutput file. A live app must implement its loader and display the retrieval time;\nloading once is not continuous monitoring. No background refresh exists unless\nimplemented through an appropriate supported workflow.\n\nPresent the chat visualization, resource link or exported file, the data timestamp, and material\ncoverage limitations. Say whether it is a snapshot or reloads from its sources.\nIf publication fails, retain the tested resource and report the failed stage;\ndo not claim success or create a different public destination. Sites-specific\nhosting, access policies, and editor storage are not part of this Cloud workflow.",
+  "description": "Analyze source data, explain metrics and comparisons, and build evidence-backed reports or HTML dashboards in Assistant Code Mode. Use for multi-step analysis, data exploration, and dashboards; a simple chart only needs the Code Mode charts reference.",
+  "instructions": "# Analyze data and deliver an inspectable result\n\nStart with the question the reader needs to answer. Choose a direct answer,\nan app shown in this chat, an exported file, or a reusable Studio app accordingly.\nFor a one-time visual analysis, prefer a chat app; filters and buttons do not by\nthemselves require a Studio App. Load `assistant-code-mode` for execution and read\nits `references/apps.md` and `references/charts.md` for interfaces and charts.\nLoading this skill does not install a library or grant access.\n\n## Keep a working plan\n\nFor work with several real steps, use `todo_write` to keep a short chat plan.\nReplace the full `todos` list each time; give each item a stable `id`, actionable\n`content`, and `status` (`pending`, `in_progress`, `completed`, or `cancelled`).\nAt most one step is active. Update as work changes, including user corrections;\nmark a step completed only after doing and checking it. Preserve exact commands\nwhen they matter. Skip this tool for a simple calculation or conversational reply.\n\nFor analysis, useful steps are reconcile source data, build the analysis, and\nverify totals, filters and conclusions. A rendered dashboard alone is not proof\nthat its numbers are correct. Keep blocked source work open and explain why.\n\n## Establish the data\n\nIdentify the actual source, unit of observation, time window, timezone, and\nlatest complete period. Read files or discover the relevant Cloud capabilities\nbefore selecting fields. External APIs use `cloud.http.fetch`; credentials are entered\nonly through the trusted `code_secret` dialog.\n\nInspect a bounded sample, missing values, duplicate keys, types, and coverage.\nReconcile totals and join cardinalities before drawing conclusions. Keep raw\nnumbers separate from display formatting. Distinguish zero from unavailable data;\nstate exclusions and denominator choices. Do not substitute fixture data for a\nblocked source unless the user requested a mockup.\n\nKeep the source query or transformation in the saved source or an accompanying\nfile so another run can reproduce the result. Preserve the source identity and\nretrieval timestamp, without credentials or credential-bearing URLs.\n\n## Build one consistent analysis\n\nDerive charts, metrics, and tables from the same reviewed data. Aggregate large\ninputs in a script before they reach an app; an app shows aggregates, not raw\nexports. Give exact values a table, for example in a `<details>` element under\nthe chart.\n\nChoose the simplest chart that answers the question. Use tables for exact\nrecords, bars for category comparisons, lines for ordered trends, and distributions\nfor spread. State units, comparison windows, and whether a percent is a fraction\nor an already scaled number. Do not imply causation from correlation.\n\nLead reports with the finding, then supporting evidence and limitations.\nLead dashboards with the important measurements, then trends and diagnostic\nbreakdowns. Use shared filters only when they affect all claimed views. Keep the\ninitial view useful without interaction. Avoid unrelated metrics added merely to\nfill a grid.\n\nShow the source context in the app: whether it is a snapshot, when the data was\nretrieved, its sources, and relevant notes. A timestamp records when the data\nwas retrieved; it does not prove that the upstream source is complete. Label\npartial or fixture data visibly.\n\n## Validate before delivery\n\nCompute in a script with `code_run` and inspect the result. Put the filter and\naggregation logic of an app into a module the script can import too\n(`lib/totals.js`), and test it there with filters, empty results and failed\nloads. Reconcile the values the app will show with the reviewed totals and check\nthat filters describe the data actually displayed. A successful schema\nvalidation does not establish analytical correctness. Apps are not rendered in\na test yet; read the static findings of `code_write` and `code_present`, and say\nwhat the person should check.\n\nValidate the logic the app actually uses, rather than pasting its formulas into a\nsecond test script. Keep an independent expectation from the input data: row\ncounts, unmatched joins, totals and representative boundary cases. For targets,\nstate their grain (for example month × region) and aggregate each target once;\nmultiple selected regions must sum their distinct targets. Compare inspected raw\nKPI values and plotted series with independent expectations. A formatted value\nmatching after rounding does not validate the raw ratio. Never round fractions before formatting them as percent. Preserve precision\nuntil display formatting. Test reset, one/multiple/all selections, empty results,\nand complete versus partial periods. A newly generated timestamp is not source\nfreshness: keep the real retrieval or file-snapshot timestamp stable.\n\nFor a Studio App data snapshot, export the validated dataset with `cloud.download` and\n`code_export`, then copy its exact path/version into the App's files with\n`code_file_copy` (see the Code Mode file transfers reference); importing private\nfiles into an App receives fresh review. Read it in the app with\n`JSON.parse(await (await cloud.files.read(\"data.json\")).text())`. Never rebuild a\ntruncated dataset by copying tool output. Keep transformations and source\nidentity alongside the snapshot.\n\nHuman approval and uncertain HTTP outcomes follow the Code Mode HTTP contract.\nDo not replay an external mutation to refresh a chart. Separate local filtering\nfrom external loading; an Apply button can avoid a request for every slider move.\n\n## Save, share, and hand off\n\nFor chat apps, test the numbers with `code_run`, then deliver with\n`code_present({title, files})`. A successful run alone is not visible to the\nuser. Retain source identity, reviewed input data and their real retrieval\ntimestamp. Put writes and external reloads behind explicit buttons; opening an\nold result must not repeat earlier actions. The user can download the current\nview as PDF or static HTML.\n\nFor reusable Studio Apps, reuse one Cloud resource for later revisions of the same report or dashboard.\nSave its source, test that revision, and use the normal Code Mode publication\nworkflow when publication is requested. Publishing a version and granting reader\naccess are separate operations. Preserve existing access; a dashboard request\ndoes not authorize broadening it. Personal secrets are never copied to readers.\n\nA published source version is not automatically a frozen data snapshot. A frozen\nreport must retain the reviewed data explicitly in its authorized resource or\noutput file. A live app must implement its loader and display the retrieval time;\nloading once is not continuous monitoring. No background refresh exists unless\nimplemented through an appropriate supported workflow.\n\nPresent the chat app, resource link or exported file, the data timestamp, and material\ncoverage limitations. Say whether it is a snapshot or reloads from its sources.\nIf publication fails, retain the tested resource and report the failed stage;\ndo not claim success or create a different public destination. Sites-specific\nhosting, access policies, and editor storage are not part of this Cloud workflow.",
   "extraFrontmatter": {}
 } satisfies AiSkillTemplate;

package/src/ai/default-tools.ts

@@ -3,9 +3,9 @@ import { createCloudAiTranscribeAudioTool } from "./audio-tool";
 import {
   CODE_RUNTIME_TOOL_NAMES,
   CodeActionInput,
+  CodeCheckInput,
   CodeExportInput,
   CodeInspectInput,
-  CodeInteractInput,
   CodeOpenInput,
   CodePresentInput,
   CodeRunInput,
@@ -110,7 +110,7 @@ export const createCloudAiCodeTools = () => [
   defineAiTool({
     name: "code_secret",
     description:
-      "Open a trusted Secret input dialog. The user enters the value directly into encrypted Assistant storage; only configured/name returns. Never ask for a credential in chat, survey, app controls or code_interact. Personal secrets are scoped to this chat or resource and bound to the exact HTTPS origin, header and prefix. Use cloud.http.secret(name,{prefix}) in cloud.http.fetch headers; load assistant-code-mode for HTTP details. Web UI required for secret entry; stored secrets also work from CLI.",
+      "Open a trusted Secret input dialog. The user enters the value directly into encrypted Assistant storage; only configured/name returns. Never ask for a credential in chat, survey or app fields. Personal secrets are scoped to this chat or resource and bound to the exact HTTPS origin, header and prefix. Use cloud.http.secret(name,{prefix}) in cloud.http.fetch headers; load assistant-code-mode for HTTP details. Web UI required for secret entry; stored secrets also work from CLI.",
     inputSchema: CodeSecretInput,
     outputSchema: z.object({ configured: z.boolean(), name: z.string() }),
     approval: "never",
@@ -128,27 +128,18 @@ export const createCloudAiCodeTools = () => [
     promptHint:
       "For file analysis, data transformations or combining Cloud data, run a short one-off script with code_run. Load assistant-code-mode for its runtime APIs; no saved app is required.",
     description:
-      "Run a saved resource id OR one-off code in the isolated worker. Optional resourceId binds one-off code to existing app data (Manage required), without editing its source. Includes cloud.capabilities.run(name,input) to chain Cloud capabilities in JavaScript; load assistant-code-mode for its runtime APIs. Scripts accept current chat inputPaths; app test runs use them only as explicit picker fixtures. Returns output, logs and UI state for agent inspection only; use code_present to show a one-off visualization to the user. Test runs use the app’s real shared and personal data; database writes and capability effects keep normal permissions and approvals.",
+      "Run one-off script code OR a saved script resource in the isolated worker. Optional resourceId binds one-off code to existing app data (Manage required), without editing its source. Includes cloud.capabilities.run(name,input) to chain Cloud capabilities in JavaScript; load assistant-code-mode for its runtime APIs. Scripts read explicit chat inputPaths. Returns output, logs and captured files for agent inspection only. Apps with an index.html interface do not run here: show them with code_open or code_present. Runs use real shared and personal data; database writes and capability effects keep normal permissions and approvals.",
     inputSchema: CodeRunInput,
     outputSchema: z.json(),
     approval: "never",
   }).server(runManagedCodeTool("code_run")),
   defineAiTool({
     name: "code_inspect",
-    description:
-      "Inspect a test run: errors, logs, output, controls and pending modal. Use nodeId to inspect table rows or list items; follow pagination only as needed.",
+    description: "Inspect a script run: status, progress, errors, logs, output and captured files. Use waitMs to wait for background work.",
     inputSchema: CodeInspectInput,
     outputSchema: z.json(),
     approval: "never",
   }).server(runManagedCodeTool("code_inspect")),
-  defineAiTool({
-    name: "code_interact",
-    description:
-      "Operate a control or answer a pending modal using its exact snapshot ID. Buttons need only id; controls use event:{type:change,value:...} or event:{type:select,key:...}. Use answer for modal replies, or answer:null to cancel. Copy an interactions example from code_inspect; never send JSON as a string. Use steps:[{id,event?},...] for up to three known sequential interactions; stops on errors, modals or background work. Returns one resulting state with completedSteps and nextStep.",
-    inputSchema: CodeInteractInput,
-    outputSchema: z.json(),
-    approval: "never",
-  }).server(runManagedCodeTool("code_interact")),
   defineAiTool({
     name: "code_stop",
     description: "Stop and release an isolated test run.",
@@ -158,15 +149,24 @@ export const createCloudAiCodeTools = () => [
   }).server(runManagedCodeTool("code_stop")),
   defineAiTool({
     name: "code_open",
-    description: "Show the app beside the chat without starting it. For one-off calculations, return the result instead of opening an app.",
+    description:
+      "Show the app beside the chat without starting it; HTML apps require a passing code_check for the current files and tables. For one-off calculations, return the result instead of opening an app.",
     inputSchema: CodeOpenInput,
     outputSchema: z.json(),
     approval: "never",
   }).client(),
+  defineAiTool({
+    name: "code_check",
+    description:
+      "Mandatory HTML app self-test: write files and steps.json (at most 20 main-flow steps), call code_check({id} OR {files}), look at EVERY screenshot with view_image, fix and check again, then code_open/code_present/code_publish. Runs desktop 1280×800 and phone 390×844 in opposite themes on separate throwaway copies of database, shared KV/files and only your own KV.user. Steps run in both views; reload keeps the copy. Match accessible role/name, label or text exactly, then case-insensitively, then by substring; ambiguous targets fail with candidates, placeholders are never names. Fill numbers with a dot. Upload file is an app-relative source path or chat file path/name. AI runs for real; HTTP, capability effects and approvals are unavailable; read-only granted capabilities run except in background turns. Returns passed, content hash (files, steps and tables), height, issues, calls, captured downloads, three PNG chat paths and an untrusted aria tree (4 KiB). Passing means not broken: inspect screenshots for cut-off, red, tight or doubled content. Self-test is a workflow guard, not a security mechanism. Aborting closes pages and discards copies. Bounded to 45 seconds, 1000 copied rows/16 MiB (schema only beyond), 64 downloads/250 MiB total/50 MiB per file.",
+    inputSchema: CodeCheckInput,
+    outputSchema: z.json(),
+    approval: "never",
+  }).server(runManagedCodeTool("code_check")),
   defineAiTool({
     name: "code_present",
     description:
-      "Present a successful one-off run as a persistent interactive visualization in this chat. Requires code_run with code, without resourceId or saved app id. Saves source, selected inputs and UI preview. Users can activate controls and download the current view. Test runs are not visible until this succeeds. For reusable apps use code_open instead.",
+      "Show an HTML app as a card in this chat after a passing code_check for exactly these files and table definitions. Pass files (index.html plus optional style.css and app.js) for a one-off app without saved data, or the id of a saved app to run it live with its data. The person starts the card with a click. Static problems such as CDN scripts, inline handlers or a missing index.html are rejected before anything is saved. For a reusable app beside the chat use code_open.",
     inputSchema: CodePresentInput,
     outputSchema: z.json(),
     approval: "never",
@@ -193,7 +193,6 @@ export const CLOUD_AI_DEFERRED_BUILTIN_TOOL_NAMES = new Set<string>([
   "markdown_to_pdf",
   "html_to_pdf",
   "present",
-  "calculate",
   "read_cloud_resource",
 ]);
 

package/src/ai/executor.ts

@@ -18,6 +18,8 @@ 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";
@@ -26,6 +28,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 +60,14 @@ 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 {
@@ -564,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 {
@@ -587,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;
     }
 
@@ -611,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;
     }
@@ -622,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) {
@@ -686,7 +728,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 +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;
@@ -732,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;
     }
@@ -865,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;
     }
@@ -1088,10 +1143,18 @@ export class AiTurnExecutor {
     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,
@@ -1136,7 +1199,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 +1248,7 @@ export class AiTurnExecutor {
       appliedSteers,
       noteToolRound: turnPolicy.noteToolRound,
       noteToolCall: turnPolicy.noteToolCall,
+      failureReason,
       onBackgroundBlocked: (message) => {
         backgroundError = message;
       },
@@ -1202,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);
@@ -1244,6 +1317,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 +1339,7 @@ export class AiTurnExecutor {
       appliedSteers,
       noteToolRound,
       noteToolCall,
+      failureReason,
     } = input;
     const stopHeartbeat = this.startHeartbeat(conversationId, turnId, abortController);
     let lastIssueMessage: string | null = null;
@@ -1346,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);
@@ -1556,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;
@@ -1574,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({
@@ -1603,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) {
@@ -1619,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();
@@ -1629,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");
   }
 }
 
@@ -1838,14 +1922,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/index.ts

@@ -345,6 +345,8 @@ export type {
   AiToolPresentation,
   AiToolRuntime,
   AiTurn,
+  AiTurnError,
+  AiTurnErrorCode,
   AiTurnFinalizedEvent,
   AiTurnStatus,
   AiTurnToolSource,