@k2b/cloud 0.31.0 → 0.32.0

package/src/ai/default-tools.ts

@@ -18,6 +18,7 @@ import { runManagedCodeTool } from "./code-runtime-tools";
 import { CODE_SOURCE_TOOLS } from "./code-source-contracts";
 import { createCodeSourceTools } from "./code-source-tools";
 import {
+  CLOUD_AI_GROUP_MAX_CHARTS,
   CloudAiCardInputSchema,
   CloudAiCardOutputSchema,
   CloudAiChartInputSchema,
@@ -39,6 +40,22 @@ import {
 } from "./file-tools";
 import { createCloudAiWebExtractTool, createCloudAiWebSearchTool, isCloudAiFirecrawlConfigured } from "./firecrawl-tools";
 import { createCloudAiHtmlToPdfTool } from "./html-pdf-tool";
+import {
+  CloudAiLoadLocalSkillInputSchema,
+  CloudAiLoadLocalSkillOutputSchema,
+  CloudAiLocalDownloadInputSchema,
+  CloudAiLocalDownloadOutputSchema,
+  CloudAiLocalListInputSchema,
+  CloudAiLocalListOutputSchema,
+  CloudAiLocalMoveInputSchema,
+  CloudAiLocalMoveOutputSchema,
+  CloudAiLocalReadInputSchema,
+  CloudAiLocalReadOutputSchema,
+  CloudAiLocalUploadInputSchema,
+  CloudAiLocalUploadOutputSchema,
+  CloudAiLocalWriteInputSchema,
+  CloudAiLocalWriteOutputSchema,
+} from "./local-tool-contracts";
 import { createCloudAiMarkdownToPdfTool } from "./markdown-pdf-tool";
 import { createAiTodoTool } from "./todo-tool";
 import { defineAiTool } from "./tools";
@@ -72,23 +89,22 @@ export const createCloudAiCardTool = () =>
   defineAiTool({
     name: "card",
     description:
-      "Render one compact visual highlight card in the chat. Use it only for a single status, metric, KPI, or short result. Use normal markdown for tables, lists, comparisons, and longer explanations. Keep all fields flat; do not pass arrays or nested objects.",
+      "Show one highlight figure you already have, such as a status, metric or short result, as a stat tile in the chat. Keep the value to a short figure or status and the caption to one line. Several figures computed in code_run go through cloud.view.stats in the run, not several card calls; tables, lists and longer explanations stay Markdown. Keep all fields flat; do not pass arrays or nested objects.",
     inputSchema: CloudAiCardInputSchema,
     outputSchema: CloudAiCardOutputSchema,
     approval: "never",
-    promptHint: "show one compact highlight card (metric, KPI, status) — not for tables, lists, or long text.",
+    promptHint: "show one highlight figure already known; several computed figures use cloud.view.stats in code_run.",
   }).clientView();
 
 export const createCloudAiChartTool = () =>
   defineAiTool({
     name: "chart",
-    description:
-      "Show one chart in the chat from data you already have: bar, line (area: true fills it), scatter, pie, donut, histogram, gauge or sparkline. Cloud draws it with the renderer of cloud.chart() in Studio apps and gives the reader a data table and Copy data; no code, sandbox or app check is involved. Aggregate first. Compute derived numbers with calculate or code_run before charting them. Say what the chart shows in title and put the unit, period or source in subtitle. The chart has no state, filters or actions: for interaction show an app in the chat with code_present, and build a saved Studio App only when data must be kept or the app reused. After the chart, state the finding instead of repeating its values.",
+    description: `Show one chart in the chat from a few values you already have that did not come from a code run, such as figures from the conversation, a web page or a small capability result: bar, line (area: true fills it), scatter, pie, donut, histogram, gauge, sparkline, boxplot, heatmap, barGauge or stat. Several related measures go into one call as a group of small charts (charts, at most ${CLOUD_AI_GROUP_MAX_CHARTS}); linkX shares the x cursor between line charts with the same kind of x. There is no second y axis: compare measures with different units as a group. Cloud draws it with the renderer of cloud.chart() and gives the reader a data table and Copy data; no code, sandbox or app check is involved. Values computed in code_run never go here: the script shows them itself with cloud.view.chart, cloud.view.group, cloud.view.table, cloud.view.stats, cloud.view.details or cloud.view.explorer, and you present the returned path. Aggregate first. Say what the chart shows in title and put the unit, period or source in subtitle; formats are data ({ style: "percent" } takes fractions). The chart has no state, filters or actions: filters, steps and comparison over computed rows come from cloud.view.explorer in code_run; for other interaction show an app in the chat with code_present, and build a saved Studio App only when data must be kept or the app reused. After the chart, state the finding instead of repeating its values.`,
     inputSchema: CloudAiChartInputSchema,
     outputSchema: CloudAiChartOutputSchema,
     approval: "never",
     promptHint:
-      "show data you already have as a chart in the chat, without code. For interaction use a chat app (code_present); for kept data or reuse, a saved Studio App.",
+      "show a few values you already have (not from a code run) as a chart in the chat. Code results use cloud.view.* and present; filters, steps and comparison use cloud.view.explorer in code_run; interaction beyond that needs a chat app (code_present).",
   }).clientView();
 
 export const createCloudAiSurveyTool = () =>
@@ -118,14 +134,73 @@ export const createCloudAiLocalBashTool = () =>
   defineAiTool({
     name: "local_bash",
     description:
-      "Run one Bash command on the user's local CLI computer after the CLI shows the exact command and the user confirms it. Use only when local computer interaction is necessary. The command runs from the CLI's startup directory as the current OS user. Inspect the returned status, exit code, stdout, and stderr before continuing.",
+      "Run one Bash command in the workspace folder on the user's computer, as the user's OS account. Use it only when no file or Cloud tool fits; the client may ask the user first, and a run does not prove that the user saw the command.",
     inputSchema: CloudAiLocalBashInputSchema,
     outputSchema: CloudAiLocalBashOutputSchema,
     approval: "never",
-    promptHint:
-      "use local_bash only when work on the user's local CLI computer is necessary; every command requires local confirmation and its result must be checked.",
+    promptHint: "use local_bash only when no local file tool or Cloud tool fits; check status, exit code, and output.",
   }).client();
 
+/** File tools a local client runs in the user's workspace folder; the client applies its path rules and questions. */
+export const createCloudAiLocalTools = () => [
+  defineAiTool({
+    name: "local_list",
+    description:
+      "List files and folders in the user's local workspace, optionally recursive or filtered by a case-insensitive glob such as **/*.pdf, in pages of up to 1000 entries with size and modification time. Folders outside the workspace ask the user first.",
+    inputSchema: CloudAiLocalListInputSchema,
+    outputSchema: CloudAiLocalListOutputSchema,
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "local_read",
+    description:
+      "Read a local text file with line numbers, 16 KiB by default and 64 KiB at most per call; continue with nextOffset. PDFs, images, and office or spreadsheet files are uploaded to this chat instead, and the result names the chat path for read_file or view_image.",
+    inputSchema: CloudAiLocalReadInputSchema,
+    outputSchema: CloudAiLocalReadOutputSchema,
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "local_upload",
+    description:
+      "Upload up to 64 local files to this chat and return their chat paths, so Cloud tools such as read_file, view_image, and code mode can use them. Uploads stay in the chat until it is deleted; each file can have up to 50 MB.",
+    inputSchema: CloudAiLocalUploadInputSchema,
+    outputSchema: CloudAiLocalUploadOutputSchema,
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "local_download",
+    description:
+      "Save a chat file, text or binary, into the local workspace and create missing folders. It never overwrites an existing file unless replace is true, which asks the user.",
+    inputSchema: CloudAiLocalDownloadInputSchema,
+    outputSchema: CloudAiLocalDownloadOutputSchema,
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "local_write",
+    description:
+      "Write a local text file of up to 100 KiB: create makes a new file and fails if one exists, append adds to an existing file, and replace overwrites one. Append and replace ask the user.",
+    inputSchema: CloudAiLocalWriteInputSchema,
+    outputSchema: CloudAiLocalWriteOutputSchema,
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "local_move",
+    description:
+      "Rename or move up to 64 files or folders inside the workspace in one batch, which the user confirms once as a list. It never overwrites: if a target exists, nothing moves and the result names the conflicts.",
+    inputSchema: CloudAiLocalMoveInputSchema,
+    outputSchema: CloudAiLocalMoveOutputSchema,
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "load_local_skill",
+    description:
+      "Load a Skill marked [local] in the Skills section by its exact name. Returns its instructions, folder, and file list; read referenced files with local_read.",
+    inputSchema: CloudAiLoadLocalSkillInputSchema,
+    outputSchema: CloudAiLoadLocalSkillOutputSchema,
+    approval: "never",
+  }).client(),
+];
+
 export const createCloudAiCodeTools = () => [
   defineAiTool({
     name: "code_secret",
@@ -146,16 +221,17 @@ export const createCloudAiCodeTools = () => [
   defineAiTool({
     name: "code_run",
     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.",
+      "For file analysis, data transformations or combining Cloud data, run a short one-off script with code_run; its computed views come from cloud.view.* in the script and present. Load assistant-code-mode for its runtime APIs; no saved app is required.",
     description:
-      "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.",
+      "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, captured files and view references for agent inspection only. Show computed views with cloud.view.chart, cloud.view.group, cloud.view.table, cloud.view.stats, cloud.view.details or cloud.view.explorer in the script, then present({path}) each returned view; never retype run values into chart arguments, files or Markdown. 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 script run: status, progress, errors, logs, output and captured files. Use waitMs to wait for background work.",
+    description:
+      "Inspect a script run: status, progress, errors, logs, output, captured files and view references. Use waitMs to wait for background work.",
     inputSchema: CodeInspectInput,
     outputSchema: z.json(),
     approval: "never",

package/src/ai/executor.ts

@@ -1,4 +1,4 @@
-import type { AssistantMessage, CompactEvent, LoopAggregate, NessiLoop, OutboundEvent } from "@k2b/nessi";
+import type { AssistantMessage, CompactEvent, LoopAggregate, Message, NessiLoop, OutboundEvent } from "@k2b/nessi";
 import { compact, nessi } from "@k2b/nessi";
 import { listCapabilities } from "../_internal/registry";
 import type { CapabilityActionReview } from "../contracts/capabilities";
@@ -26,8 +26,21 @@ 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 {
+  createCloudAiCodeTools,
+  createCloudAiLocalBashTool,
+  createCloudAiLocalTools,
+  createConfiguredDefaultCloudAiTools,
+} from "./default-tools";
 import { aiFileStore } from "./files-store";
+import { AI_LOCAL_TOOL_NAMES } from "./local-tool-contracts";
+import {
+  countMalformedToolCallRepairs,
+  createMalformedToolCallRepair,
+  isMalformedToolCallId,
+  withMalformedToolCallRepair,
+  withMalformedToolCallResults,
+} from "./malformed-tool-call-repair";
 import { aiMemories } from "./memories";
 import { createCloudAiMemoryTool } from "./memory-tool";
 import { recordAiMemoryWorkflowEvidence } from "./memory-workflow-evidence";
@@ -42,6 +55,7 @@ import {
   type AiWireEvent,
   applyWireEventToBlocks,
   buildBlocksFromMessages,
+  canonicalToolName,
   compactionBlockId,
   reconcileResolvedTurnActions,
   steerAppliedBlockId,
@@ -54,7 +68,7 @@ import { assistantQuotaProvider, inferenceProvider } from "./quota-provider";
 import { collectConversationResourceObservations } from "./resource-refs";
 import { AiRunTimeout } from "./run-timeout";
 import { isAiVisionModelConfigured, type resolveAiModel } from "./settings";
-import { selectAiSkillCatalog } from "./skill-catalog";
+import { mergeAiSkillCatalog, selectAiSkillCatalog } from "./skill-catalog";
 import { createCloudAiLoadSkillTool, createCloudAiSearchSkillsTool, loadSelectedAiSkills } from "./skill-tool";
 import { aiSkills } from "./skills";
 import { aiConversations, recordAiWebsiteReceipts } from "./store";
@@ -100,17 +114,18 @@ 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.
+// Cloud's repair calls are skipped too: the live run never counts them.
 const isToolRound = (message: AssistantMessage): boolean =>
   message.stopReason !== "error" &&
   message.stopReason !== "interrupted" &&
   message.stopReason !== "aborted" &&
-  message.content.some((block) => block.type === "tool_call");
+  message.content.some((block) => block.type === "tool_call" && !isMalformedToolCallId(block.id));
 
 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" || !isToolRound(message)) return [];
-    const callIds = message.content.flatMap((block) => (block.type === "tool_call" ? [block.id] : []));
+    const callIds = message.content.flatMap((block) => (block.type === "tool_call" && !isMalformedToolCallId(block.id) ? [block.id] : []));
     return callIds.length > 0 ? [callIds] : [];
   });
   return {
@@ -271,6 +286,7 @@ export type ExecutorConfig = {
   validateTurn?: typeof validateAiTurnRequest;
   /** Runs after the durable turn state and final wire event are flushed. */
   onTurnFinalized?: (event: AiTurnFinalizedEvent) => Promise<void>;
+  onApprovalRequested?: (event: { approvalId: string }) => Promise<void>;
   /** Waits before retrying a transient provider failure without Retry-After; tests shorten them. */
   providerRetryDelaysMs?: readonly number[];
 };
@@ -278,6 +294,29 @@ export type ExecutorConfig = {
 type ResolvedModel = Awaited<ReturnType<typeof resolveAiModel>>;
 type ValidatedTurn = { settings: Awaited<ReturnType<typeof validateAiTurnRequest>>["settings"]; resolved: ResolvedModel };
 
+// One entry per steering text returned to nessi, including repairs that have no user steer to acknowledge.
+const createChatSteering =
+  (input: {
+    repair: ReturnType<typeof createMalformedToolCallRepair>;
+    appliedSteers: (AiTurnSteer | null)[];
+    takePendingSteers: () => Promise<AiTurnSteer[]>;
+    noteSteering: () => void;
+  }) =>
+  async ({ signal }: { signal: AbortSignal }) => {
+    if (signal.aborted) return undefined;
+    // Exhaustion fails before consuming any pending user input.
+    const repairText = input.repair.takeSteering();
+    const steers = await input.takePendingSteers();
+    input.appliedSteers.push(...steers);
+    if (steers.length > 0) input.noteSteering();
+    const texts = steers.map((steer) => steer.text);
+    if (repairText) {
+      texts.push(repairText);
+      input.appliedSteers.push(null);
+    }
+    return texts.length > 0 ? texts : undefined;
+  };
+
 // ---------------------------------------------------------------------------
 // Baseline rebuild — reconstruct the full active-turn view from persisted rounds
 // ---------------------------------------------------------------------------
@@ -465,6 +504,7 @@ const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowReme
       name,
       args: "args" in patch ? patch.args : existing?.args,
       status: patch.status ?? existing?.status ?? "running",
+      at: patch.at ?? existing?.at,
       result: "result" in patch ? patch.result : existing?.result,
       isError: "isError" in patch ? patch.isError : existing?.isError,
       approval: approval && !allowRememberedApprovals ? { ...approval, allowAlways: false, allowChat: false } : approval,
@@ -548,6 +588,7 @@ const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowReme
           setTool(event.callId, {
             name: event.name,
             status: rejectedCallIds.has(event.callId) ? "rejected" : event.isError ? "failed" : "completed",
+            at: new Date().toISOString(),
             result: event.result,
             isError: Boolean(event.isError),
             clearApproval: true,
@@ -559,7 +600,15 @@ const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowReme
         if (callId && toolBlocks.has(callId)) {
           const existing = toolBlocks.get(callId);
           if (existing && existing.status !== "completed" && existing.status !== "failed") {
-            return [setTool(callId, { status: "failed", result: event.issue.message, isError: true, clearApproval: true })];
+            return [
+              setTool(callId, {
+                status: "failed",
+                at: new Date().toISOString(),
+                result: event.issue.message,
+                isError: true,
+                clearApproval: true,
+              }),
+            ];
           }
         }
         return [];
@@ -573,8 +622,24 @@ const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowReme
     }
   };
 
+  const storedMessage = (message: Message, at: string): BlockOp[] =>
+    message.role === "tool_result" && isMalformedToolCallId(message.callId)
+      ? [
+          setTool(message.callId, {
+            name: canonicalToolName(message.name),
+            args: {},
+            status: "failed",
+            at,
+            result: message.result,
+            isError: true,
+            clearApproval: true,
+          }),
+        ]
+      : [];
+
   return {
     translate,
+    storedMessage,
     compaction,
     setFrontendModes,
     setPresentations,
@@ -614,7 +679,7 @@ const materializeChatConfig = async (config: AiChatTurnRunConfig, signal: AbortS
               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(
+            ...[createCloudAiLocalBashTool(), ...createCloudAiLocalTools(), ...createCloudAiCodeTools()].filter(
               (tool) => tool.location === "server" || config.clientToolIds?.some((name) => name === tool.def.name),
             ),
           ]
@@ -866,7 +931,22 @@ export class AiTurnExecutor {
     const skillSubject =
       defaultToolSource && resolved.profile.capabilities.includes("tools") ? accessSubjectForActor(material.actor) : null;
     const availableSkills = skillSubject ? (await aiSkills.list(skillSubject)).filter((skill) => skill.enabled) : [];
-    const skillCatalog = selectAiSkillCatalog(availableSkills, resolved.provider.contextWindow ?? 0, query);
+    const localClient = !config.background && !config.mandate ? config.client : undefined;
+    const localContext = localClient ? config.localContext : undefined;
+    const localSkills = (localContext?.skills ?? []).map((skill) => ({
+      name: skill.name,
+      description: skill.description,
+      manualOnly: skill.manualOnly,
+      source: "local" as const,
+    }));
+    const skillCatalog = selectAiSkillCatalog(
+      mergeAiSkillCatalog(
+        availableSkills.map(({ name, description, manualOnly }) => ({ name, description, manualOnly })),
+        localSkills,
+      ),
+      resolved.provider.contextWindow ?? 0,
+      query,
+    );
     const projectFiles =
       project && resolvedProjectId && projectSubject
         ? {
@@ -895,7 +975,7 @@ export class AiTurnExecutor {
       ...material.tools,
       ...(memoryActive ? [createCloudAiMemoryTool(query)] : []),
       ...(skillSubject && availableSkills.length ? [createCloudAiLoadSkillTool(skillSubject)] : []),
-      ...(skillSubject && skillCatalog.omitted > 0 ? [createCloudAiSearchSkillsTool(skillSubject)] : []),
+      ...(skillCatalog.omitted > 0 ? [createCloudAiSearchSkillsTool(skillSubject, localSkills)] : []),
       ...(config.project && resolvedProjectId && projectSubject
         ? [
             createCloudAiSearchProjectTool(resolvedProjectId, projectSubject),
@@ -928,7 +1008,13 @@ export class AiTurnExecutor {
     // 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"]),
+      ...new Set([
+        ...sourceToolNames,
+        ...runtimeTools.map((tool) => tool.def.name),
+        ...CODE_RUNTIME_TOOL_NAMES,
+        "local_bash",
+        ...AI_LOCAL_TOOL_NAMES,
+      ]),
     ].filter((name) => !offeredToolNames.has(name));
     const memoryToolEnabled = activeTools.some((tool) => tool.def.name === "memory");
     const projectToolEnabled = activeTools.some((tool) => tool.def.name === "search_project");
@@ -948,6 +1034,7 @@ export class AiTurnExecutor {
       turnId,
       reportToolProgress: (callId: string, message: string) => pipeline.reportToolProgress(callId, message),
       reportWebsiteReceipts: (callId: string, receipts: AiWebsiteReceipt[]) => pipeline.reportWebsiteReceipts(callId, receipts),
+      localToolsEnabled: activeTools.some((tool) => tool.def.name === "local_upload"),
       attachedFilePaths: new Set(config.files?.attached.map((file) => file.path) ?? []),
       allowedDataBoundaries: material.modelPolicy?.allowedDataBoundaries,
       projectFiles,
@@ -1064,7 +1151,7 @@ export class AiTurnExecutor {
       await pipeline.emitBaseline();
     }
 
-    const appliedSteers: AiTurnSteer[] = [];
+    const appliedSteers: (AiTurnSteer | null)[] = [];
 
     let mandatePolicy: MandatePolicyV1 | null | undefined;
     if (config.background && config.mandate) {
@@ -1118,6 +1205,7 @@ export class AiTurnExecutor {
           conversationId,
           actor: capabilityAuthority?.actor ?? toolActor,
           staticTools: activeTools,
+          ...(activeTools.some((tool) => tool.def.name === "load_skill") ? { skillNames: availableSkills.map((skill) => skill.name) } : {}),
           allowedTools,
           mandatePolicy,
           unofferedTools,
@@ -1226,8 +1314,8 @@ export class AiTurnExecutor {
     );
     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");
+    const skillCatalogOffered = activeTools.some((tool) => ["load_skill", "load_local_skill"].includes(tool.def.name));
+    const skillCreatorAvailable = availableSkills.some((skill) => skill.name === "skill-creator" && !skill.manualOnly);
     // 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 = {};
@@ -1256,7 +1344,16 @@ export class AiTurnExecutor {
     }
     const systemPrompt = composeAiSystemPrompt({
       globalInstructions: settings.globalInstructions,
-      loadedSkills,
+      loadedSkills: [...loadedSkills, ...(localContext?.selectedSkills ?? []).map((skill) => ({ ...skill, source: "local" as const }))],
+      localClient: localClient
+        ? {
+            client: localClient,
+            cloudUrl: (await coreSettings.get<string>("app.url")) || "",
+            instructions: settings.localClientInstructions,
+          }
+        : undefined,
+      workspaceInstructions: localContext?.instructions,
+      localSkillsAvailable: skillCatalogOffered && localSkills.some((skill) => !skill.manualOnly),
       turnInstructions: [
         material.systemPrompt,
         audioUnavailableInstruction,
@@ -1292,8 +1389,9 @@ export class AiTurnExecutor {
       skillCreatorAvailable,
       recentWork: guidance.recentWork,
     });
-    // The turn policy counts the whole turn, including rounds that compaction archived.
+    // The turn policy and repair budget count the whole turn, including rounds that compaction archived.
     const turnMessages = await aiConversations.listTurnMessages({ conversationId, loopId: turnId, includeCompacted: true });
+    const malformedToolCallRepair = createMalformedToolCallRepair(countMalformedToolCallRepairs(turnMessages));
     const turnBlocks = buildBlocksFromMessages(turnMessages);
     const providerNamesByCallId = new Map(
       turnMessages.flatMap(({ message }) =>
@@ -1336,7 +1434,11 @@ 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, name: providerNamesByCallId.get(block.callId) ?? block.name }] : [])),
+        .flatMap((block) =>
+          block.kind === "tool" && !isMalformedToolCallId(block.callId)
+            ? [{ ...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 })
@@ -1346,21 +1448,20 @@ export class AiTurnExecutor {
       agentId: "cloud",
       loopId: turnId,
       ...(isFresh ? { input: turnInput } : {}),
-      provider: turnPolicy.provider,
+      provider: withMalformedToolCallRepair(turnPolicy.provider, malformedToolCallRepair),
       systemPrompt,
-      store,
-      steering: async ({ signal: steeringSignal }) => {
-        if (steeringSignal.aborted) return undefined;
-        const steers = await aiConversations.takePendingTurnSteers({
-          conversationId,
-          turnId,
-          leaseOwner: this.config.leaseOwner,
-        });
-        appliedSteers.push(...steers);
-        if (steers.length === 0) return undefined;
-        turnPolicy.noteSteering();
-        return steers.map((steer) => steer.text);
-      },
+      store: withMalformedToolCallResults(store, malformedToolCallRepair),
+      steering: createChatSteering({
+        repair: malformedToolCallRepair,
+        appliedSteers,
+        takePendingSteers: () =>
+          aiConversations.takePendingTurnSteers({
+            conversationId,
+            turnId,
+            leaseOwner: this.config.leaseOwner,
+          }),
+        noteSteering: turnPolicy.noteSteering,
+      }),
       tools: async () => {
         try {
           return await turnPolicy.tools();
@@ -1482,7 +1583,7 @@ export class AiTurnExecutor {
     approvalTargets: ReadonlyMap<string, AiApprovalTarget>;
     linkedApprovals: ReadonlyMap<string, string>;
     freshApprovalRequired?: ReadonlySet<string>;
-    appliedSteers: AiTurnSteer[];
+    appliedSteers: (AiTurnSteer | null)[];
     noteToolRound: () => void;
     noteToolCall: (call: AiTurnPolicyToolCall) => void;
     /**
@@ -1532,6 +1633,7 @@ export class AiTurnExecutor {
             linkedApprovals: input.linkedApprovals,
             freshApprovalRequired: input.freshApprovalRequired,
             onBackgroundBlocked: input.onBackgroundBlocked,
+            signal: abortController.signal,
           });
           if (suspended) {
             abortController.abort();
@@ -1638,6 +1740,7 @@ export class AiTurnExecutor {
     linkedApprovals: ReadonlyMap<string, string>;
     freshApprovalRequired?: ReadonlySet<string>;
     onBackgroundBlocked?: (message: string) => void;
+    signal: AbortSignal;
   }): Promise<boolean> {
     const {
       event,
@@ -1790,6 +1893,32 @@ export class AiTurnExecutor {
     }
 
     await pipeline.apply(presented);
+    if (
+      event.kind === "client_tool" &&
+      frontendMode === "client" &&
+      (toolName === "local_bash" || AI_LOCAL_TOOL_NAMES.some((name) => name === toolName))
+    ) {
+      await pipeline.flush();
+      // One wait stays inside a heartbeat interval, keeping lease renewal and abort detection on their cadence.
+      const deadline = performance.now() + this.config.heartbeatMs / 2;
+      while (!input.signal.aborted && performance.now() < deadline) {
+        const action = await aiConversations.getPendingTurnAction({ conversationId, turnId, callId: event.callId });
+        if (action?.status === "resolved" && action.resolvedEvent) {
+          await aiConversations.markPendingTurnActionConsumedInline({ conversationId, turnId, callId: event.callId });
+          loop.push(action.resolvedEvent);
+          return false;
+        }
+        await new Promise<void>((resolve) => {
+          const done = () => {
+            clearTimeout(timer);
+            input.signal.removeEventListener("abort", done);
+            resolve();
+          };
+          const timer = setTimeout(done, 10);
+          input.signal.addEventListener("abort", done, { once: true });
+        });
+      }
+    }
     const suspended = await aiConversations.suspendTurn({
       conversationId,
       turnId,
@@ -1799,6 +1928,16 @@ export class AiTurnExecutor {
       waitingBudgetMs: AI_ACTION_BUDGET_MS,
     });
     await pipeline.flush().catch(() => undefined);
+    if (suspended && approvalId && this.config.onApprovalRequested) {
+      await this.config.onApprovalRequested({ approvalId }).catch((error) => {
+        log.warn("AI approval requested hook failed", {
+          conversationId,
+          turnId,
+          approvalId,
+          error: error instanceof Error ? error.message : "AI approval requested hook failed",
+        });
+      });
+    }
     return suspended;
   }
 
@@ -2055,6 +2194,8 @@ class StreamPipeline {
   }
 
   async emitMessage(message: AiStoredMessage): Promise<void> {
+    // A malformed call shows once its error result is saved, at the end of its response as in history.
+    for (const op of this.mapper.storedMessage(message.message, message.createdAt)) await this.emitOp(op);
     const seq = this.nextSeq();
     await this.publish(this.envelope({ type: "message_saved" as const, seq, message }));
     await this.maybeSnapshot();
@@ -2196,6 +2337,7 @@ class StreamPipeline {
 }
 
 export const __aiExecutorTest = {
+  createChatSteering,
   indexConversationToolSource,
   StreamPipeline,
   createEventMapper,

package/src/ai/file-error.ts

@@ -0,0 +1,2 @@
+export const aiMissingChatFileError = (path: string, localToolsEnabled?: boolean, message = `No such file: ${path}`): Error =>
+  new Error(`${message}${localToolsEnabled ? " This is a chat path. Upload local files with local_upload first." : ""}`);