@k2b/cloud 0.25.0 → 0.27.0

package/src/ai/executor.ts

@@ -1,4 +1,4 @@
-import type { CompactEvent, LoopAggregate, NessiLoop, OutboundEvent, Provider, Tool, ToolResolver } from "@k2b/nessi";
+import type { CompactEvent, LoopAggregate, NessiLoop, OutboundEvent } from "@k2b/nessi";
 import { compact, nessi } from "@k2b/nessi";
 import { listCapabilities } from "../_internal/registry";
 import type { CapabilityActionReview } from "../contracts/capabilities";
@@ -15,6 +15,7 @@ import {
   hasRememberedAiToolApproval,
 } from "./approvals";
 import { isAssistantChatTurn } from "./assistant-models";
+import { CODE_RUNTIME_TOOL_NAMES } from "./browser-code-contracts";
 import { createAiToolResolver, createRunToolStore } from "./capabilities";
 import { AiCapabilityExecutionError, executeAiCapability, resolveAiCapabilityActor, reviewAiCapability } from "./capability-execution";
 import { aiChatTasks } from "./chat-tasks";
@@ -29,6 +30,7 @@ import { type AiUserPrefs, aiActorUser, aiUserPrefs } from "./prefs";
 import { createCloudAiReadProjectKnowledgeTool, createCloudAiSearchProjectTool } from "./project-tool";
 import { aiProjects } from "./projects";
 import {
+  AI_TURN_LEASE_MS,
   type AiTurnBlock,
   type AiWireEvent,
   applyWireEventToBlocks,
@@ -40,6 +42,7 @@ import {
   streamBlockId,
   toolBlockId,
 } from "./protocol";
+import { retryTransientProviderErrors } from "./provider-retry";
 import { assistantQuotaProvider, inferenceProvider } from "./quota-provider";
 import { collectConversationResourceObservations } from "./resource-refs";
 import { AiRunTimeout } from "./run-timeout";
@@ -48,11 +51,13 @@ import { selectAiSkillCatalog } from "./skill-catalog";
 import { createCloudAiLoadSkillTool, createCloudAiSearchSkillsTool, loadSelectedAiSkills } from "./skill-tool";
 import { aiSkills } from "./skills";
 import { aiConversations } from "./store";
-import { publishAiWireEvent } from "./stream";
+import { AI_LIVE_SNAPSHOT_INTERVAL_MS, publishAiWireEvent } from "./stream";
 import { composeAiSystemPrompt } from "./system-prompt";
 import { aiToolAudit } from "./tool-audit";
+import { acceptCanonicalToolNames } from "./tool-call-names";
 import { resolveAiToolResultMaxChars } from "./tool-result-budget";
 import { aiToolPromptHints, type PreparedAiTools, prepareAiTools } from "./tools";
+import { type AiTurnPolicyToolCall, applyAiTurnPolicy } from "./turn-policy";
 import { createTurnTimingRecorder, withDurableTurnTiming } from "./turn-timing";
 import type {
   AiChatTurnRunConfig,
@@ -71,13 +76,9 @@ import { validateAiTurnRequest } from "./validate";
 
 const log = logger("ai:executor");
 
-const AI_TURN_LEASE_MS = 45_000;
 const AI_COALESCE_MS = 25;
 const AI_COALESCE_MAX_CHARS = 512;
-const AI_SNAPSHOT_INTERVAL_MS = 1_000;
 const AI_ACTION_BUDGET_MS = 24 * 60 * 60_000;
-const AI_FINAL_TOOL_ROUND_PROMPT = `# Final response
-The configured tool-round budget has been reached, so no more tools are available in this turn. Answer the user's request now with the best result supported by the evidence already gathered. State any material uncertainty or incomplete part clearly.`;
 
 const toolRoundState = (messages: AiStoredMessage[]): { issued: number; completed: number } => {
   const completedCallIds = new Set(messages.flatMap(({ message }) => (message.role === "tool_result" ? [message.callId] : [])));
@@ -92,50 +93,6 @@ const toolRoundState = (messages: AiStoredMessage[]): { issued: number; complete
   };
 };
 
-const applyToolRoundPolicy = (input: {
-  provider: Provider;
-  tools: Tool[] | ToolResolver;
-  maxToolRounds?: number;
-  issuedToolRounds: number;
-  completedToolRounds: number;
-}): { provider: Provider; tools: Tool[] | ToolResolver; maxTurns?: number; noteToolRound: () => void } => {
-  const limit = Math.floor(input.maxToolRounds ?? 0);
-  if (limit <= 0) return { provider: input.provider, tools: input.tools, noteToolRound: () => undefined };
-
-  const issuedAtStart = Math.max(0, Math.floor(input.issuedToolRounds));
-  let completed = Math.max(0, Math.floor(input.completedToolRounds));
-  let finalSynthesis = completed >= limit;
-  const tools: ToolResolver = async () => {
-    finalSynthesis = completed >= limit;
-    if (finalSynthesis) return [];
-    return typeof input.tools === "function" ? input.tools() : input.tools;
-  };
-  const provider: Provider = {
-    name: input.provider.name,
-    family: input.provider.family,
-    model: input.provider.model,
-    contextWindow: input.provider.contextWindow,
-    capabilities: input.provider.capabilities,
-    complete: (request) => input.provider.complete(request),
-    stream: async function* (request) {
-      yield* input.provider.stream(
-        finalSynthesis ? { ...request, systemPrompt: `${request.systemPrompt ?? ""}\n\n${AI_FINAL_TOOL_ROUND_PROMPT}`.trim() } : request,
-      );
-    },
-  };
-
-  // Nessi checks this before provider calls. The extra round is the tool-free
-  // synthesis call after the last allowed tool-using round.
-  return {
-    provider,
-    tools,
-    maxTurns: Math.max(1, limit - issuedAtStart + 1),
-    noteToolRound: () => {
-      completed += 1;
-    },
-  };
-};
-
 const indexConversationResources = async (input: Parameters<typeof aiConversations.indexConversationResources>[0]): Promise<void> => {
   try {
     await aiConversations.indexConversationResources(input);
@@ -161,6 +118,10 @@ const recordMemoryWorkflowEvidence = async (input: Parameters<typeof recordAiMem
   }
 };
 
+/**
+ * Indexes what a finished tool call read or delivered; never throws. A browser tool ends here too, once the turn
+ * continues with the result the browser reported.
+ */
 const indexConversationToolSource = async (input: {
   conversationId: string;
   turnId: string;
@@ -183,10 +144,45 @@ const indexConversationToolSource = async (input: {
         });
     }
     let source: Parameters<typeof aiConversations.indexConversationSource>[0]["source"] | null = null;
+    const args = typeof input.args === "object" && input.args !== null ? (input.args as Record<string, unknown>) : {};
+    const text = (value: unknown) => (typeof value === "string" ? value.trim() : "");
+    const result = typeof input.result === "object" && input.result !== null ? (input.result as Record<string, unknown>) : {};
     if (input.name === "web_search") {
-      const args = input.args;
-      const query = typeof args === "object" && args !== null && "query" in args && typeof args.query === "string" ? args.query.trim() : "";
-      source = { kind: "activity", key: "web_search", title: query || "Web search", preview: "Searched the web", icon: "ti ti-world" };
+      const query = text(args.query);
+      // One entry per query: each search is something the user may want to see that the assistant looked up.
+      const key = query ? `web_search:${query.replace(/\s+/gu, " ").toLocaleLowerCase()}` : "web_search";
+      source = { kind: "activity", key, title: query || "Web search", preview: "Searched the web", icon: "ti ti-world" };
+    } else if (input.name === "present" && text(result.path)) {
+      const path = text(result.path);
+      source = {
+        kind: "result",
+        key: path,
+        title: text(args.title) || path.slice(path.lastIndexOf("/") + 1),
+        preview: text(args.description) || undefined,
+        icon: "ti ti-file",
+      };
+    } else if (
+      input.name === "code_open" &&
+      text(args.id) &&
+      typeof input.result === "object" &&
+      input.result !== null &&
+      !("error" in input.result)
+    ) {
+      // The browser reports a failure as a result with an error, which reaches this point without isError.
+      source = {
+        kind: "result",
+        key: `assistant.artifact:${text(args.id)}`,
+        title: "Studio app",
+        icon: "ti ti-app-window",
+        ref: { type: "assistant.artifact", id: text(args.id) },
+      };
+    } else if (input.name === "code_present" && text(result.presentationId)) {
+      source = {
+        kind: "result",
+        key: `code_present:${input.callId}`,
+        title: text(args.title) || text(result.title) || "Visualization",
+        icon: "ti ti-chart-dots",
+      };
     } else if (input.name === "web_extract" && typeof input.result === "object" && input.result !== null) {
       const result = input.result as Record<string, unknown>;
       if (typeof result.url === "string" && result.url.trim()) {
@@ -249,6 +245,8 @@ export type ExecutorConfig = {
   validateTurn?: typeof validateAiTurnRequest;
   /** Runs after the durable turn state and final wire event are flushed. */
   onTurnFinalized?: (event: AiTurnFinalizedEvent) => Promise<void>;
+  /** Waits before retrying a transient provider failure without Retry-After; tests shorten them. */
+  providerRetryDelaysMs?: readonly number[];
 };
 
 type ResolvedModel = Awaited<ReturnType<typeof resolveAiModel>>;
@@ -392,6 +390,10 @@ const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowReme
   const setRejectedCallIds = (items: Set<string>) => {
     rejectedCallIds = items;
   };
+  let approvedCallIds = new Set<string>();
+  const setApprovedCallIds = (items: Set<string>) => {
+    approvedCallIds = items;
+  };
   /** nessi stream block ids (turn-scoped) that belong to tool_call blocks — their deltas are raw args JSON. */
   const toolStreamIds = new Set<string>();
   /** kind per open Cloud stream block id, for delta create-if-missing. */
@@ -414,6 +416,7 @@ const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowReme
       approval: approval && !allowRememberedApprovals ? { ...approval, allowAlways: false } : approval,
       frontendMode: patch.frontendMode ?? existing?.frontendMode,
       presentation: patch.presentation ?? existing?.presentation ?? presentations.get(rawName) ?? presentations.get(name),
+      ...(approvedCallIds.has(callId) || approvedCallIds.has(displayCallId) || existing?.approved ? { approved: true } : {}),
     };
     toolBlocks.set(callId, block);
     return { type: "block_set", block };
@@ -518,6 +521,7 @@ const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowReme
     setApprovalPolicies,
     setApprovalReviews,
     setRejectedCallIds,
+    setApprovedCallIds,
   };
 };
 
@@ -543,8 +547,10 @@ const materializeChatConfig = async (config: AiChatTurnRunConfig, signal: AbortS
       source.kind === "default"
         ? [
             ...(await createConfiguredDefaultCloudAiTools()),
-            ...(config.clientToolIds?.includes("local_bash") ? [createCloudAiLocalBashTool()] : []),
-            ...createCloudAiCodeTools().filter((tool) => config.clientToolIds?.some((name) => name === tool.def.name)),
+            // Cloud runs the code tools itself; only tools a client must run wait for that client to declare them.
+            ...[createCloudAiLocalBashTool(), ...createCloudAiCodeTools()].filter(
+              (tool) => tool.location === "server" || config.clientToolIds?.some((name) => name === tool.def.name),
+            ),
           ]
         : [],
     toolApprovalContext: config.toolApprovalContext,
@@ -662,6 +668,7 @@ export class AiTurnExecutor {
     let resolvedProjectId: string | null = null;
     let chatId = config.chatId ?? "";
     let allowedTools: string[] | null = null;
+    let sourceToolNames: string[] = [];
     try {
       if (config.background && !config.mandate) throw new Error("Background execution requires its task mandate.");
       const [nextMaterial, conversation] = await Promise.all([
@@ -672,6 +679,7 @@ export class AiTurnExecutor {
       if (!conversation) throw new Error("Conversation is no longer available.");
       allowedTools = conversation.allowedTools ?? null;
       const allowed = allowedTools === null ? null : new Set(allowedTools);
+      sourceToolNames = material.tools.map((tool) => tool.def.name);
       if (allowed) material.tools = material.tools.filter((tool) => allowed.has(tool.def.name));
       chatId ||= conversation?.shortId ?? "";
       if (config.project) {
@@ -793,6 +801,12 @@ export class AiTurnExecutor {
           (tool) => (!allowed || allowed.has(tool.def.name)) && !(config.mandate && ["code_open", "code_secret"].includes(tool.def.name)),
         )
       : [];
+    const offeredToolNames = new Set(activeTools.map((tool) => tool.def.name));
+    // Built-ins that exist but this turn does not offer: client tools without their client, tools a
+    // task cannot use, and tools outside the conversation's fixed scope. load_tools explains each one.
+    const unofferedTools = [
+      ...new Set([...sourceToolNames, ...runtimeTools.map((tool) => tool.def.name), ...CODE_RUNTIME_TOOL_NAMES, "local_bash"]),
+    ].filter((name) => !offeredToolNames.has(name));
     const memoryToolEnabled = activeTools.some((tool) => tool.def.name === "memory");
     const projectToolEnabled = activeTools.some((tool) => tool.def.name === "search_project");
 
@@ -829,6 +843,7 @@ export class AiTurnExecutor {
     pipeline.setApprovalPolicies(prepared.approvalPolicies);
     const toolPresentations = new Map<string, AiToolPresentation>();
     const rejectedToolCallIds = new Set<string>();
+    const approvedToolCallIds = new Set<string>();
     pipeline.setPresentations(toolPresentations);
     pipeline.setApprovalReviews(capabilityActionReviews);
     let turnInput = config.input;
@@ -868,17 +883,19 @@ export class AiTurnExecutor {
       turnInput,
       toolPresentations,
       rejectedToolCallIds,
+      approvedToolCallIds,
     });
 
     const { loopMessages, pendingRecords, resolvedRecords, turnSteers } =
       attemptState ?? (await loadChatAttemptState(conversationId, turnId));
     for (const action of resolvedRecords) {
-      if (action.resolvedEvent?.type !== "approval_response" || action.resolvedEvent.approved) continue;
-      rejectedToolCallIds.add(
-        action.kind === "custom_approval" ? (customApprovalParentCallId(action.callId) ?? action.callId) : action.callId,
-      );
+      if (action.resolvedEvent?.type !== "approval_response") continue;
+      // A decision on a custom approval belongs to the call that asked for it.
+      const callId = action.kind === "custom_approval" ? (customApprovalParentCallId(action.callId) ?? action.callId) : action.callId;
+      (action.resolvedEvent.approved ? approvedToolCallIds : rejectedToolCallIds).add(callId);
     }
     pipeline.setRejectedCallIds(rejectedToolCallIds);
+    pipeline.setApprovedCallIds(approvedToolCallIds);
     const assistantMessages = loopMessages.filter((message) => message.message.role !== "user");
     const isFresh = assistantMessages.length === 0 && resolvedRecords.length === 0 && !skipResolvedActions;
 
@@ -898,6 +915,7 @@ export class AiTurnExecutor {
           actor: capabilityAuthority?.actor ?? toolActor,
           staticTools: activeTools,
           allowedTools,
+          unofferedTools,
           runtimeContext: dynamicToolRuntimeContext,
           store: toolStore,
           ...(capabilityAuthority ? { listRegistry: listCapabilities } : {}),
@@ -1061,21 +1079,49 @@ export class AiTurnExecutor {
       memory: memory?.text,
       timeZone,
       locale: promptLocale,
+      interactive: !config.background,
+      skillCreatorAvailable: availableSkills.some((skill) => skill.name === "skill-creator"),
     });
-    const priorToolRounds = toolRoundState(loopMessages);
+    // The turn policy counts the whole turn, including rounds that compaction archived.
+    const turnMessages = await aiConversations.listTurnMessages({ conversationId, loopId: turnId, includeCompacted: true });
+    const turnBlocks = buildBlocksFromMessages(turnMessages);
+    const priorToolRounds = toolRoundState(turnMessages);
     const quotaSubject = accessSubjectForActor(material.actor);
-    const toolRoundPolicy = applyToolRoundPolicy({
-      provider: assistantQuotaProvider(resolved.provider, config, quotaSubject, resolved.profile, turnId, conversationId),
+    const deadline = claim.turn.deadline ? Date.parse(claim.turn.deadline) : null;
+    const turnPolicy = applyAiTurnPolicy({
+      provider: acceptCanonicalToolNames(
+        retryTransientProviderErrors(
+          assistantQuotaProvider(resolved.provider, config, quotaSubject, resolved.profile, turnId, conversationId),
+          {
+            deadline,
+            delaysMs: this.config.providerRetryDelaysMs,
+            onRetry: async ({ retry, delayMs, issue }) => {
+              log.warn("AI provider call retried", { conversationId, turnId, retry, delayMs, kind: issue.kind, message: issue.message });
+              await pipeline.emitProviderRetry();
+            },
+          },
+        ),
+        prepared.canonicalNames,
+      ),
       tools,
       maxToolRounds: resolved.profile.maxToolRounds,
       issuedToolRounds: priorToolRounds.issued,
       completedToolRounds: priorToolRounds.completed,
+      deadline,
+      runBudgetMs: claim.turn.runBudgetMs ?? null,
+      finishedToolCalls: turnBlocks
+        .slice(turnBlocks.findLastIndex((block) => block.kind === "steer_applied") + 1)
+        .flatMap((block) => (block.kind === "tool" ? [block] : [])),
+      onDecision: (decision) =>
+        decision.kind === "hint"
+          ? log.warn("AI turn got a loop hint", { conversationId, turnId, hints: decision.hints })
+          : log.info("AI turn answers without further tools", { conversationId, turnId, reason: decision.reason }),
     });
     const loop = nessi({
       agentId: "cloud",
       loopId: turnId,
       ...(isFresh ? { input: turnInput } : {}),
-      provider: toolRoundPolicy.provider,
+      provider: turnPolicy.provider,
       systemPrompt,
       store,
       steering: async ({ signal: steeringSignal }) => {
@@ -1086,12 +1132,15 @@ export class AiTurnExecutor {
           leaseOwner: this.config.leaseOwner,
         });
         appliedSteers.push(...steers);
-        return steers.length > 0 ? steers.map((steer) => steer.text) : undefined;
+        if (steers.length === 0) return undefined;
+        turnPolicy.noteSteering();
+        return steers.map((steer) => steer.text);
       },
-      tools: toolRoundPolicy.tools,
-      ...(toolRoundPolicy.maxTurns === undefined ? {} : { maxTurns: toolRoundPolicy.maxTurns }),
+      tools: turnPolicy.tools,
+      ...(turnPolicy.maxTurns === undefined ? {} : { maxTurns: turnPolicy.maxTurns }),
       temperature: resolved.profile.temperature,
       maxOutputTokens: resolved.profile.maxOutputTokens,
+      reasoningEffort: resolved.profile.reasoningEffort,
       coalesce: { ms: AI_COALESCE_MS, maxChars: AI_COALESCE_MAX_CHARS },
       compact: config.background
         ? undefined
@@ -1127,7 +1176,8 @@ export class AiTurnExecutor {
       rememberableCapabilityApprovals,
       capabilityActionReviews,
       appliedSteers,
-      noteToolRound: toolRoundPolicy.noteToolRound,
+      noteToolRound: turnPolicy.noteToolRound,
+      noteToolCall: turnPolicy.noteToolCall,
       onBackgroundBlocked: (message) => {
         backgroundError = message;
       },
@@ -1193,6 +1243,7 @@ export class AiTurnExecutor {
     capabilityActionReviews: ReadonlyMap<string, CapabilityActionReview>;
     appliedSteers: AiTurnSteer[];
     noteToolRound: () => void;
+    noteToolCall: (call: AiTurnPolicyToolCall) => void;
     onBackgroundBlocked?: (message: string) => void;
   }): Promise<AttemptOutcome> {
     const {
@@ -1208,6 +1259,7 @@ export class AiTurnExecutor {
       capabilityActionReviews,
       appliedSteers,
       noteToolRound,
+      noteToolCall,
     } = input;
     const stopHeartbeat = this.startHeartbeat(conversationId, turnId, abortController);
     let lastIssueMessage: string | null = null;
@@ -1266,6 +1318,12 @@ export class AiTurnExecutor {
             .noteToolCompleted({ turnId, callId: event.callId, isError: event.isError })
             .catch(() => log.warn("AI tool audit write failed", { code: "tool_audit_complete_failed", turnId, callId: event.callId }));
           const toolBlock = pipeline.blocks.find((block) => block.kind === "tool" && block.callId === event.callId);
+          // The policy keys calls by the name the model called, as the persisted calls it seeds from.
+          noteToolCall(
+            toolBlock?.kind === "tool"
+              ? { ...toolBlock, name: event.name }
+              : { name: event.name, status: event.isError ? "failed" : "completed", result: event.result },
+          );
           await indexConversationToolSource({
             conversationId,
             turnId,
@@ -1597,6 +1655,9 @@ class StreamPipeline {
   readonly timing: ReturnType<typeof createTurnTimingRecorder>;
   private lastSnapshotAt = 0;
   private snapshotDirty = false;
+  private snapshotTimer: ReturnType<typeof setTimeout> | undefined;
+  /** The newest save of the live state. Saves run one after another, so an older one never lands last. */
+  private saving: Promise<void> = Promise.resolve();
   private chain: Promise<void> = Promise.resolve();
 
   constructor(input: {
@@ -1628,6 +1689,8 @@ class StreamPipeline {
 
   private nextSeq(): number {
     this.seq += 1;
+    // The saved state follows every event, so a reader that reloads it catches up with the live stream.
+    this.snapshotDirty = true;
     return this.seq;
   }
 
@@ -1667,17 +1730,23 @@ class StreamPipeline {
     this.mapper.setRejectedCallIds(callIds);
   }
 
+  setApprovedCallIds(callIds: Set<string>): void {
+    this.mapper.setApprovedCallIds(callIds);
+  }
+
   async emitBaseline(): Promise<void> {
     for (const block of this.blocks) {
       const seq = this.nextSeq();
       await this.publish(this.envelope({ type: "block_set" as const, seq, block }) as AiWireEvent);
     }
-    this.snapshotDirty = this.blocks.length > 0;
+    // A new attempt's baseline is saved at once: a stream that reloads the turn must not wait for the first model event.
+    await this.maybeSnapshot();
   }
 
   async emitMessage(message: AiStoredMessage): Promise<void> {
     const seq = this.nextSeq();
     await this.publish(this.envelope({ type: "message_saved" as const, seq, message }));
+    await this.maybeSnapshot();
   }
 
   async emitTurnStarted(modelProfileId: string): Promise<void> {
@@ -1737,24 +1806,36 @@ class StreamPipeline {
     await this.publish(event);
   }
 
+  /**
+   * Saves the live state at most once per interval. A change inside the interval is saved when it ends, even if no
+   * event follows, so the saved state lags the live stream by at most one interval.
+   */
   private async maybeSnapshot(): Promise<void> {
     if (!this.snapshotDirty) return;
-    if (Date.now() - this.lastSnapshotAt < AI_SNAPSHOT_INTERVAL_MS) return;
+    const wait = AI_LIVE_SNAPSHOT_INTERVAL_MS - (Date.now() - this.lastSnapshotAt);
+    if (wait > 0) {
+      this.snapshotTimer ??= setTimeout(() => {
+        this.snapshotTimer = undefined;
+        void this.maybeSnapshot();
+      }, wait);
+      return;
+    }
     await this.persistSnapshot();
   }
 
   async persistSnapshot(): Promise<void> {
+    this.cancelSnapshotTimer();
     this.lastSnapshotAt = Date.now();
     this.snapshotDirty = false;
-    await aiConversations
-      .saveTurnLiveState({
-        conversationId: this.conversationId,
-        turnId: this.turnId,
-        leaseOwner: this.leaseOwner,
-        blocks: this.blocks,
-        seq: this.seq,
-      })
-      .catch(() => undefined);
+    const blocks = this.blocks;
+    const seq = this.seq;
+    this.saving = this.saving.then(() =>
+      aiConversations
+        .saveTurnLiveState({ conversationId: this.conversationId, turnId: this.turnId, leaseOwner: this.leaseOwner, blocks, seq })
+        .then(() => undefined)
+        .catch(() => undefined),
+    );
+    await this.saving;
   }
 
   async emitError(message: string): Promise<void> {
@@ -1765,6 +1846,13 @@ class StreamPipeline {
     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();
+    await this.publish(this.envelope({ type: "provider_retry" as const, seq }));
+    await this.maybeSnapshot();
+  }
+
   async emitTurnFinished(status: "completed" | "failed" | "aborted", error: string | null): Promise<void> {
     const seq = this.nextSeq();
     await this.publish(this.envelope({ type: "turn_finished" as const, seq, status, error }) as AiWireEvent);
@@ -1775,15 +1863,24 @@ class StreamPipeline {
     return this.ordered(() => publishAiWireEvent(event).catch(() => undefined));
   }
 
+  private cancelSnapshotTimer(): void {
+    if (this.snapshotTimer) clearTimeout(this.snapshotTimer);
+    this.snapshotTimer = undefined;
+  }
+
+  /**
+   * Waits for every publish and save. The attempt ends here: a later save would overwrite what suspension or the next
+   * attempt saved.
+   */
   async flush(): Promise<void> {
-    await this.chain;
+    this.cancelSnapshotTimer();
+    await Promise.all([this.chain, this.saving]);
   }
 }
 
 export const __aiExecutorTest = {
   indexConversationToolSource,
   StreamPipeline,
-  applyToolRoundPolicy,
   createEventMapper,
   rebuildAttemptBaseline,
   rebuildBlocksFromMessages,

package/src/ai/file-context.ts

@@ -1,6 +1,6 @@
 import type { Message } from "@k2b/nessi";
 import { canonicalizeAiAttachmentMarkers, parseAiAttachmentMarkers } from "./attachments";
-import { aiFileStore } from "./files-store";
+import { type AiFileStat, aiFileStore, isAiWorkingFilePath } from "./files-store";
 import {
   AI_FILE_MANIFEST_MAX_ITEMS,
   AI_IMAGE_INPUT_MAX_BYTES,
@@ -52,9 +52,21 @@ export const snapshotAiConversationFiles = async (
     throw new Error("Attached images exceed the 40 MB total image input limit.");
   }
   if (all.length === 0 && attached.length === 0) return undefined;
-  return { attached, available: all.slice(0, AI_FILE_MANIFEST_MAX_ITEMS), total: all.length };
+  return { attached, ...aiConversationFileManifest(all) };
 };
 
+/**
+ * The chat files a turn lists for the model, at most `AI_FILE_MANIFEST_MAX_ITEMS`. Working files below `/temp/` come
+ * last, so intermediate steps never push uploads and results out of the list.
+ */
+export const aiConversationFileManifest = (files: readonly AiFileStat[]): { available: AiFileStat[]; total: number } => ({
+  available: [...files.filter((file) => !isAiWorkingFilePath(file.path)), ...files.filter((file) => isAiWorkingFilePath(file.path))].slice(
+    0,
+    AI_FILE_MANIFEST_MAX_ITEMS,
+  ),
+  total: files.length,
+});
+
 export const canonicalizeAiConversationAttachments = <T extends Message>(
   message: T,
   snapshot: AiConversationFileSnapshot | undefined,

package/src/ai/file-tools.ts

@@ -14,7 +14,7 @@ import {
   mountAiProjectFilePath,
   mountAiSkillFilePath,
 } from "./file-mount";
-import { aiFileStore, guessAiMediaType, normalizeAiFilePath } from "./files-store";
+import { aiFileStore, guessAiMediaType, isAiWorkingFilePath, normalizeAiFilePath } from "./files-store";
 import { defineAiTool } from "./tools";
 
 const FILE_READ_MAX_BYTES = 64 * 1024;
@@ -123,7 +123,7 @@ export const createCloudAiListFilesTool = () =>
   defineAiTool({
     name: "list_files",
     description:
-      "List persistent conversation files, shared Project files, and loaded skill files. Project files are read-only below /project; loaded skills are read-only below /skills/<name>. Files are ordered newest first.",
+      "List persistent conversation files, shared Project files, and loaded skill files. Project files are read-only below /project; loaded skills are read-only below /skills/<name>. Files are ordered newest first; working files below /temp follow all other files. List /temp to see only them.",
     inputSchema: CloudAiListFilesInputSchema,
     outputSchema: CloudAiListFilesOutputSchema,
     approval: "never",
@@ -150,7 +150,12 @@ export const createCloudAiListFilesTool = () =>
       ...skillFiles
         .filter((file) => projectPathMatchesPrefix(file.path, skillPrefix ?? ""))
         .map((file) => ({ ...file, path: mountAiSkillFilePath(file.path), origin: "skill" as const })),
-    ].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.path.localeCompare(b.path));
+    ].sort(
+      (a, b) =>
+        Number(isAiWorkingFilePath(a.path)) - Number(isAiWorkingFilePath(b.path)) ||
+        b.updatedAt.localeCompare(a.updatedAt) ||
+        a.path.localeCompare(b.path),
+    );
     return { files: files.slice(0, 200), truncated: files.length > 200 };
   });
 
@@ -341,6 +346,15 @@ export const createCloudAiWriteFileTool = () =>
 export const CloudAiPresentInputSchema = z.object({
   path: z.string().trim().min(1).describe("Absolute conversation file path."),
   title: z.string().trim().min(1).max(120).optional(),
+  description: z
+    .string()
+    .trim()
+    .min(1)
+    .max(160)
+    .optional()
+    .describe(
+      "One sentence in the user's language that says what the file is and what it is for, without repeating its name. Shown next to the file in the chat's results.",
+    ),
 });
 export const CloudAiPresentOutputSchema = z.object({ path: z.string(), size: z.number(), mediaType: z.string() });