@dexto/core 1.7.1 → 1.8.0

package/dist/llm/executor/turn-executor.js

@@ -1,7 +1,4 @@
-import {
-  __callDispose,
-  __using
-} from "../../chunk-PTJYTZNU.js";
+import "../../chunk-C6A6W6XS.js";
 import {
   streamText,
   generateText,
@@ -9,20 +6,155 @@ import {
   jsonSchema,
   APICallError
 } from "ai";
+import { z } from "zod";
 import { trace } from "@opentelemetry/api";
+import { sanitizeToolResult } from "../../context/utils.js";
 import { StreamProcessor } from "./stream-processor.js";
+import { truncateToolResult } from "./tool-output-truncator.js";
 import { buildProviderOptions, getEffectiveReasoningBudgetTokens } from "./provider-options.js";
 import { DextoLogComponent } from "../../logger/v2/types.js";
-import { defer } from "../../utils/defer.js";
 import { DextoRuntimeError } from "../../errors/DextoRuntimeError.js";
 import { ErrorScope, ErrorType } from "../../errors/types.js";
 import { LLMErrorCode } from "../error-codes.js";
 import { toError } from "../../utils/error-conversion.js";
 import { isCodexBaseURL } from "../providers/codex-base-url.js";
+import { createModelToolDefinitions } from "./tool-definitions.js";
+import { ApprovalStatus } from "../../approval/types.js";
+const MCP_TOOL_PREFIX = "mcp--";
+const MODEL_REQUEST_MAX_RETRIES = 2;
+const LLMFinishReasonStateSchema = z.enum([
+  "stop",
+  "tool-calls",
+  "length",
+  "content-filter",
+  "error",
+  "other",
+  "unknown",
+  "cancelled",
+  "max-steps"
+]);
+const TokenUsageStateSchema = z.object({
+  inputTokens: z.number().optional(),
+  outputTokens: z.number().optional(),
+  reasoningTokens: z.number().optional(),
+  totalTokens: z.number().optional(),
+  cacheReadTokens: z.number().optional(),
+  cacheWriteTokens: z.number().optional()
+}).strict().transform((parsed) => {
+  const usage = {};
+  if (parsed.inputTokens !== void 0) usage.inputTokens = parsed.inputTokens;
+  if (parsed.outputTokens !== void 0) usage.outputTokens = parsed.outputTokens;
+  if (parsed.reasoningTokens !== void 0) usage.reasoningTokens = parsed.reasoningTokens;
+  if (parsed.totalTokens !== void 0) usage.totalTokens = parsed.totalTokens;
+  if (parsed.cacheReadTokens !== void 0) usage.cacheReadTokens = parsed.cacheReadTokens;
+  if (parsed.cacheWriteTokens !== void 0) usage.cacheWriteTokens = parsed.cacheWriteTokens;
+  return usage;
+});
+const ModelToolCallStateSchema = z.object({
+  toolCallId: z.string(),
+  toolName: z.string(),
+  input: z.unknown()
+}).strict();
+const ModelStepResultStateSchema = z.object({
+  text: z.string(),
+  finishReason: LLMFinishReasonStateSchema,
+  usage: TokenUsageStateSchema,
+  toolCalls: z.array(ModelToolCallStateSchema)
+}).strict();
+const JsonValueSchema = z.json();
+const ProviderOptionsStateSchema = z.record(
+  z.string(),
+  z.record(z.string(), JsonValueSchema)
+);
+const JsonSchemaStateSchema = z.custom(
+  (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+);
+const ToolSetEntryStateSchema = z.object({
+  name: z.string().optional(),
+  description: z.string().optional(),
+  parameters: JsonSchemaStateSchema,
+  _meta: z.record(z.string(), JsonValueSchema).optional()
+}).strict().transform((parsed) => {
+  const tool = { parameters: parsed.parameters };
+  if (parsed.name !== void 0) tool.name = parsed.name;
+  if (parsed.description !== void 0) tool.description = parsed.description;
+  if (parsed._meta !== void 0) tool._meta = parsed._meta;
+  return tool;
+});
+const ToolSetStateSchema = z.record(z.string(), ToolSetEntryStateSchema);
+const ModelStepRequestStateSchema = z.object({
+  messages: z.array(
+    z.custom(
+      (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+    )
+  ),
+  estimatedInputTokens: z.number().int().nonnegative(),
+  toolDefinitions: ToolSetStateSchema,
+  reasoning: z.object({
+    reasoningVariant: z.string().optional(),
+    reasoningBudgetTokens: z.number().int().positive().optional()
+  }).strict().optional(),
+  providerOptions: ProviderOptionsStateSchema.optional(),
+  streaming: z.boolean()
+}).strict();
+const TurnDriverStateSchema = z.discriminatedUnion("phase", [
+  z.object({
+    phase: z.literal("ready-for-model"),
+    stepCount: z.number().int().nonnegative(),
+    startedAtMs: z.number().int().nonnegative(),
+    supportsTools: z.boolean(),
+    lastText: z.string(),
+    lastUsage: TokenUsageStateSchema.nullable(),
+    lastFinishReason: LLMFinishReasonStateSchema
+  }).strict(),
+  z.object({
+    phase: z.literal("model-step-prepared"),
+    stepCount: z.number().int().nonnegative(),
+    startedAtMs: z.number().int().nonnegative(),
+    supportsTools: z.boolean(),
+    modelStepId: z.string(),
+    request: ModelStepRequestStateSchema,
+    lastText: z.string(),
+    lastUsage: TokenUsageStateSchema.nullable(),
+    lastFinishReason: LLMFinishReasonStateSchema
+  }).strict(),
+  z.object({
+    phase: z.literal("model-step-complete"),
+    stepCount: z.number().int().nonnegative(),
+    startedAtMs: z.number().int().nonnegative(),
+    supportsTools: z.boolean(),
+    modelStepId: z.string(),
+    result: ModelStepResultStateSchema,
+    toolCallsExecuted: z.boolean()
+  }).strict(),
+  z.object({
+    phase: z.literal("stopped"),
+    stepCount: z.number().int().nonnegative(),
+    startedAtMs: z.number().int().nonnegative(),
+    supportsTools: z.boolean(),
+    lastText: z.string(),
+    lastUsage: TokenUsageStateSchema.nullable(),
+    lastFinishReason: LLMFinishReasonStateSchema,
+    finished: z.boolean()
+  }).strict()
+]);
+function parseTurnDriverState(input) {
+  return TurnDriverStateSchema.parse(input);
+}
+function toModelStepRequestState(request) {
+  return {
+    messages: structuredClone(request.messages),
+    estimatedInputTokens: request.estimatedInputTokens,
+    toolDefinitions: structuredClone(request.toolDefinitions),
+    ...request.reasoning === void 0 ? {} : { reasoning: structuredClone(request.reasoning) },
+    ...request.providerOptions === void 0 ? {} : { providerOptions: structuredClone(request.providerOptions) },
+    streaming: request.streaming
+  };
+}
 const toolSupportCache = /* @__PURE__ */ new Map();
 const LOCAL_PROVIDERS = ["ollama", "local"];
 class TurnExecutor {
-  constructor(model, toolManager, contextManager, eventBus, resourceManager, sessionId, config, llmContext, logger, messageQueue, modelLimits, externalSignal, compactionStrategy = null, runContext) {
+  constructor(model, toolManager, contextManager, eventBus, resourceManager, sessionId, config, llmContext, logger, steerQueue, followUpQueue, modelLimits, externalSignal, compactionStrategy = null, runContext) {
     this.model = model;
     this.toolManager = toolManager;
     this.contextManager = contextManager;
@@ -31,7 +163,8 @@ class TurnExecutor {
     this.sessionId = sessionId;
     this.config = config;
     this.llmContext = llmContext;
-    this.messageQueue = messageQueue;
+    this.steerQueue = steerQueue;
+    this.followUpQueue = followUpQueue;
     this.modelLimits = modelLimits;
     this.externalSignal = externalSignal;
     this.runContext = runContext;
@@ -46,11 +179,7 @@ class TurnExecutor {
    */
   stepAbortController;
   compactionStrategy = null;
-  /**
-   * Map to track tool-call metadata by toolCallId.
-   * Used to pass execution-time info (approval + presentation snapshot) to result persistence.
-   */
-  toolCallMetadata = /* @__PURE__ */ new Map();
+  currentModelStepId = "in-memory-model-step-0";
   /**
    * Get StreamProcessor config from TurnExecutor state.
    * @param estimatedInputTokens Optional estimated input tokens for analytics
@@ -79,238 +208,300 @@ class TurnExecutor {
    * @param streaming If true, emits llm:chunk events during streaming. Default true.
    */
   async execute(contributorContext, streaming = true) {
-    var _stack = [];
+    const driver = await this.createDriver(contributorContext, { streaming });
     try {
-      const _ = __using(_stack, defer(() => this.cleanup()));
-      const startTime = Date.now();
-      let stepCount = 0;
-      let lastStepTokens = null;
-      let lastFinishReason = "unknown";
-      let lastText = "";
-      this.eventBus.emit("llm:thinking", {});
-      const supportsTools = await this.validateToolSupport();
-      if (!supportsTools) {
-        const modelKey = `${this.llmContext.provider}:${this.llmContext.model}`;
-        this.eventBus.emit("llm:unsupported-input", {
-          errors: [
-            `Model '${modelKey}' does not support tool calling.`,
-            "You can still chat, but the model will not be able to use tools or execute commands."
-          ],
-          provider: this.llmContext.provider,
-          model: this.llmContext.model,
-          details: {
-            feature: "tool-calling",
-            supported: false
-          }
-        });
-        this.logger.warn(
-          `Model ${modelKey} does not support tools - continuing without tool calling`
-        );
-      }
-      let currentAbortHandler = null;
+      let stopped = false;
       try {
-        while (true) {
-          if (currentAbortHandler && this.externalSignal) {
-            this.externalSignal.removeEventListener("abort", currentAbortHandler);
-          }
-          this.stepAbortController = new AbortController();
-          currentAbortHandler = () => this.stepAbortController.abort();
-          if (this.externalSignal && !this.externalSignal.aborted) {
-            this.externalSignal.addEventListener("abort", currentAbortHandler, {
-              once: true
-            });
+        while (!stopped) {
+          const modelStep = await driver.runNextModelStep();
+          if (modelStep.result.finishReason === "tool-calls") {
+            await driver.executeToolCalls();
           }
-          const coalesced = await this.messageQueue.dequeueAll();
-          if (coalesced) {
-            await this.injectQueuedMessages(coalesced);
+          const nextStep = await driver.decideNextStep();
+          if (nextStep.kind === "stop") {
+            stopped = true;
           }
-          await this.pruneOldToolOutputs();
-          let prepared = await this.contextManager.getFormattedMessagesForLLM(
+        }
+      } catch (error) {
+        return await driver.fail(error);
+      }
+      return await driver.finish();
+    } finally {
+      driver.dispose();
+    }
+  }
+  async createDriver(contributorContext, options = { streaming: true }) {
+    const now = Date.now();
+    const state = options.state ?? {
+      phase: "ready-for-model",
+      stepCount: 0,
+      startedAtMs: now,
+      supportsTools: await this.validateInitialToolSupport(),
+      lastText: "",
+      lastUsage: null,
+      lastFinishReason: "unknown"
+    };
+    const startTime = state.startedAtMs;
+    let stepCount = state.stepCount;
+    let lastStepTokens = state.phase === "model-step-complete" ? structuredClone(state.result.usage) : structuredClone(state.lastUsage);
+    let lastFinishReason = state.phase === "model-step-complete" ? state.result.finishReason : state.lastFinishReason;
+    let lastText = state.phase === "model-step-complete" ? state.result.text : state.lastText;
+    let currentStepScope = null;
+    let currentResult = state.phase === "model-step-complete" ? structuredClone(state.result) : null;
+    let preparedModelRequest = state.phase === "model-step-prepared" ? await this.restorePreparedModelRequest(state.request, state.supportsTools) : null;
+    let currentToolCallsExecuted = state.phase === "model-step-complete" ? state.toolCallsExecuted : false;
+    let modelStepPreparing = false;
+    let modelStepRunning = false;
+    let toolCallsRunning = false;
+    let stopped = state.phase === "stopped";
+    let finished = state.phase === "stopped" ? state.finished : false;
+    let disposed = false;
+    const turn = { supportsTools: state.supportsTools };
+    if (state.phase === "model-step-prepared" || state.phase === "model-step-complete") {
+      this.currentModelStepId = state.modelStepId;
+      currentStepScope = this.startModelStepScope();
+    }
+    const closeCurrentStepScope = () => {
+      currentStepScope?.[Symbol.dispose]();
+      currentStepScope = null;
+    };
+    const getState = () => {
+      if (modelStepPreparing) {
+        throw new Error("Turn driver cannot checkpoint during model preparation");
+      }
+      if (modelStepRunning) {
+        throw new Error("Turn driver cannot checkpoint during a model step");
+      }
+      if (toolCallsRunning) {
+        throw new Error("Turn driver cannot checkpoint during tool execution");
+      }
+      if (stopped) {
+        return {
+          phase: "stopped",
+          stepCount,
+          startedAtMs: startTime,
+          supportsTools: turn.supportsTools,
+          lastText,
+          lastUsage: structuredClone(lastStepTokens),
+          lastFinishReason,
+          finished
+        };
+      }
+      if (preparedModelRequest !== null) {
+        return {
+          phase: "model-step-prepared",
+          stepCount,
+          startedAtMs: startTime,
+          supportsTools: turn.supportsTools,
+          modelStepId: this.currentModelStepId,
+          request: toModelStepRequestState(preparedModelRequest),
+          lastText,
+          lastUsage: structuredClone(lastStepTokens),
+          lastFinishReason
+        };
+      }
+      if (currentResult !== null) {
+        return {
+          phase: "model-step-complete",
+          stepCount,
+          startedAtMs: startTime,
+          supportsTools: turn.supportsTools,
+          modelStepId: this.currentModelStepId,
+          result: {
+            text: currentResult.text,
+            finishReason: currentResult.finishReason,
+            usage: structuredClone(currentResult.usage),
+            toolCalls: structuredClone(currentResult.toolCalls)
+          },
+          toolCallsExecuted: currentToolCallsExecuted
+        };
+      }
+      return {
+        phase: "ready-for-model",
+        stepCount,
+        startedAtMs: startTime,
+        supportsTools: turn.supportsTools,
+        lastText,
+        lastUsage: structuredClone(lastStepTokens),
+        lastFinishReason
+      };
+    };
+    const assertCanUseDriver = () => {
+      if (disposed) {
+        throw new Error("Turn driver has already been disposed");
+      }
+      if (finished) {
+        throw new Error("Turn driver has already finished");
+      }
+    };
+    return {
+      prepareNextModelStep: async () => {
+        assertCanUseDriver();
+        if (stopped) {
+          throw new Error("Turn driver has already reached a stop decision");
+        }
+        if (preparedModelRequest !== null) {
+          return { stepCount };
+        }
+        if (currentStepScope !== null) {
+          throw new Error("Previous model step has not been decided yet");
+        }
+        currentStepScope = this.startModelStepScope();
+        this.currentModelStepId = `in-memory-model-step-${stepCount}`;
+        modelStepPreparing = true;
+        try {
+          preparedModelRequest = await this.prepareNextModelRequest({
             contributorContext,
-            this.llmContext
-          );
-          const toolDefinitions = supportsTools ? this.toolManager.filterToolsForSession(
-            await this.toolManager.getAllTools(),
-            this.sessionId
-          ) : {};
-          let estimatedTokens = await this.contextManager.getEstimatedNextInputTokens(
-            prepared.systemPrompt,
-            prepared.preparedHistory,
-            toolDefinitions
-          );
-          if (this.shouldCompact(estimatedTokens)) {
-            this.logger.debug(
-              `Pre-check: estimated ${estimatedTokens} tokens exceeds threshold, compacting`
-            );
-            const didCompact = await this.compactContext(
-              estimatedTokens,
-              contributorContext,
-              toolDefinitions
-            );
-            if (didCompact) {
-              prepared = await this.contextManager.getFormattedMessagesForLLM(
-                contributorContext,
-                this.llmContext
-              );
-              estimatedTokens = await this.contextManager.getEstimatedNextInputTokens(
-                prepared.systemPrompt,
-                prepared.preparedHistory,
-                toolDefinitions
-              );
-              this.logger.debug(
-                `Post-compaction: recomputed estimate is ${estimatedTokens} tokens`
-              );
+            supportsTools: turn.supportsTools,
+            streaming: options.streaming
+          });
+        } catch (error) {
+          currentStepScope[Symbol.dispose]();
+          currentStepScope = null;
+          throw error;
+        } finally {
+          modelStepPreparing = false;
+        }
+        return { stepCount };
+      },
+      runNextModelStep: async () => {
+        assertCanUseDriver();
+        if (stopped) {
+          throw new Error("Turn driver has already reached a stop decision");
+        }
+        if (currentResult !== null) {
+          throw new Error("Previous model step has not been decided yet");
+        }
+        modelStepRunning = true;
+        try {
+          if (preparedModelRequest === null) {
+            if (currentStepScope !== null) {
+              throw new Error("Previous model step has not been decided yet");
             }
+            currentStepScope = this.startModelStepScope();
+            this.currentModelStepId = `in-memory-model-step-${stepCount}`;
+            preparedModelRequest = await this.prepareNextModelRequest({
+              contributorContext,
+              supportsTools: turn.supportsTools,
+              streaming: options.streaming
+            });
+          }
+          const modelStepRequest = preparedModelRequest;
+          if (currentStepScope === null || modelStepRequest === null) {
+            throw new Error("Model step request was not prepared");
           }
           this.logger.debug(`Step ${stepCount}: Starting`);
-          const tools = supportsTools ? await this.createTools() : {};
-          const providerOptions = buildProviderOptions({
-            provider: this.llmContext.provider,
-            model: this.llmContext.model,
-            reasoning: this.config.reasoning
-          });
-          this.logger.debug("LLM request options", {
-            provider: this.llmContext.provider,
-            model: this.llmContext.model,
-            requestedReasoning: {
-              variant: this.config.reasoning?.variant,
-              budgetTokens: this.config.reasoning?.budgetTokens
-            },
-            providerOptions
-          });
-          const reasoningVariant = this.config.reasoning?.variant;
-          const reasoningBudgetTokens = getEffectiveReasoningBudgetTokens(providerOptions);
-          const reasoningForStream = reasoningVariant !== void 0 || reasoningBudgetTokens !== void 0 ? {
-            ...reasoningVariant !== void 0 && { reasoningVariant },
-            ...reasoningBudgetTokens !== void 0 && { reasoningBudgetTokens }
-          } : void 0;
-          const streamProcessor = new StreamProcessor(
-            this.contextManager,
-            this.eventBus,
-            this.resourceManager,
-            this.stepAbortController.signal,
-            this.getStreamProcessorConfig(estimatedTokens, reasoningForStream),
-            this.logger,
-            streaming,
-            this.toolCallMetadata
-          );
-          const result = await streamProcessor.process(
-            () => streamText({
-              model: this.model,
-              stopWhen: stepCountIs(1),
-              tools,
-              abortSignal: this.stepAbortController.signal,
-              messages: prepared.formattedMessages,
-              ...this.config.maxOutputTokens !== void 0 && {
-                maxOutputTokens: this.config.maxOutputTokens
-              },
-              ...this.config.temperature !== void 0 && {
-                temperature: this.config.temperature
-              },
-              // Provider-specific options (caching, reasoning, etc.)
-              ...providerOptions !== void 0 && {
-                providerOptions
-              },
-              // Log stream-level errors (tool errors, API errors during streaming)
-              onError: (error) => {
-                this.logger.error("Stream error", { error });
-              }
-            })
-          );
+          const result = await this.runModelStepWithRetry(modelStepRequest);
+          currentResult = result;
+          currentToolCallsExecuted = result.finishReason !== "tool-calls";
+          preparedModelRequest = null;
           lastStepTokens = result.usage;
           lastFinishReason = result.finishReason;
           lastText = result.text;
           this.logger.debug(
             `Step ${stepCount}: Finished with reason="${result.finishReason}", tokens=${JSON.stringify(result.usage)}`
           );
-          if (result.finishReason === "cancelled") {
-            this.logger.info(
-              `Context estimation (cancelled): keeping last known actuals, partial response (${result.text.length} chars) will be estimated`
-            );
-          } else if (result.usage?.inputTokens !== void 0) {
-            const contextInputTokens2 = this.getContextInputTokens(result.usage);
-            const actualInputTokens = contextInputTokens2 ?? result.usage.inputTokens;
-            const diff = estimatedTokens - actualInputTokens;
-            const diffPercent = actualInputTokens > 0 ? (diff / actualInputTokens * 100).toFixed(1) : "0.0";
-            this.logger.info(
-              `Context estimation accuracy: estimated=${estimatedTokens}, actual=${actualInputTokens}, error=${diff} (${diffPercent}%)`
-            );
-            this.contextManager.setLastActualInputTokens(actualInputTokens);
-            if (result.usage?.outputTokens !== void 0) {
-              this.contextManager.setLastActualOutputTokens(result.usage.outputTokens);
-            }
-            await this.contextManager.recordLastCallMessageCount();
-          }
-          const contextInputTokens = result.usage ? this.getContextInputTokens(result.usage) : null;
-          if (contextInputTokens && this.shouldCompactFromActual(contextInputTokens)) {
-            this.logger.debug(
-              `Post-response: actual ${contextInputTokens} tokens exceeds threshold, compacting`
-            );
-            await this.compactContext(
-              contextInputTokens,
-              contributorContext,
-              toolDefinitions
-            );
-          }
-          if (result.finishReason !== "tool-calls") {
-            const queuedOnTerminate = await this.messageQueue.dequeueAll();
-            if (queuedOnTerminate) {
-              this.logger.debug(
-                `Continuing: ${queuedOnTerminate.messages.length} queued message(s) to process`
-              );
-              await this.injectQueuedMessages(queuedOnTerminate);
-              continue;
-            }
-            this.logger.debug(`Terminating: finishReason is "${result.finishReason}"`);
-            break;
-          }
-          if (this.externalSignal?.aborted && !this.messageQueue.hasPending()) {
-            this.logger.debug("Terminating: hard cancel - external abort signal received");
-            lastFinishReason = "cancelled";
-            break;
-          }
-          stepCount++;
-          if (this.config.maxSteps !== void 0 && stepCount >= this.config.maxSteps) {
-            this.logger.debug(`Terminating: reached maxSteps (${this.config.maxSteps})`);
-            lastFinishReason = "max-steps";
-            break;
+          await this.applyModelStepResult({
+            result,
+            request: modelStepRequest,
+            contributorContext
+          });
+          return {
+            result,
+            stepCount
+          };
+        } finally {
+          modelStepRunning = false;
+        }
+      },
+      executeToolCalls: async () => {
+        assertCanUseDriver();
+        if (currentStepScope === null) {
+          throw new Error("No active model step is available for tool execution");
+        }
+        const result = currentResult;
+        if (result === null) {
+          throw new Error("No model step result is available for tool execution");
+        }
+        if (currentToolCallsExecuted) {
+          throw new Error("Tool calls for the current model step have already run");
+        }
+        if (result.finishReason === "tool-calls") {
+          toolCallsRunning = true;
+          currentToolCallsExecuted = true;
+          try {
+            await this.executeModelToolCalls(result.toolCalls);
+          } catch (error) {
+            currentToolCallsExecuted = false;
+            throw error;
+          } finally {
+            toolCallsRunning = false;
           }
         }
-      } catch (error) {
-        const mappedError = this.mapProviderError(error);
-        this.logger.error("TurnExecutor failed", { error: mappedError });
-        this.eventBus.emit("llm:error", {
-          error: mappedError,
-          context: "TurnExecutor",
-          recoverable: false
-        });
-        await this.contextManager.flush();
-        this.eventBus.emit("run:complete", {
-          finishReason: "error",
+      },
+      decideNextStep: async () => {
+        assertCanUseDriver();
+        if (currentStepScope === null) {
+          throw new Error("No active model step is available to decide");
+        }
+        const result = currentResult;
+        if (result === null) {
+          throw new Error("No model step result is available to decide");
+        }
+        if (result.finishReason === "tool-calls" && !currentToolCallsExecuted) {
+          throw new Error("Tool calls must finish before deciding the next model step");
+        }
+        const nextStep = await this.decideNextStep(result, stepCount);
+        stepCount = nextStep.stepCount;
+        currentResult = null;
+        currentToolCallsExecuted = false;
+        closeCurrentStepScope();
+        if (nextStep.kind === "stop") {
+          lastFinishReason = nextStep.finishReason;
+          stopped = true;
+          return {
+            kind: "stop",
+            stepCount,
+            finishReason: lastFinishReason
+          };
+        }
+        return {
+          kind: "continue",
+          stepCount
+        };
+      },
+      finish: async () => {
+        assertCanUseDriver();
+        if (!stopped) {
+          throw new Error("Turn driver cannot finish before a stop decision");
+        }
+        const result = await this.finishTurn({
+          startTime,
           stepCount,
-          durationMs: Date.now() - startTime,
-          error: mappedError
+          text: lastText,
+          usage: lastStepTokens,
+          finishReason: lastFinishReason
         });
-        throw mappedError;
+        finished = true;
+        return result;
+      },
+      fail: async (error) => {
+        closeCurrentStepScope();
+        return this.failTurn(error, stepCount, startTime);
+      },
+      getState,
+      checkpoint: () => {
+        const state2 = getState();
+        disposed = true;
+        closeCurrentStepScope();
+        return state2;
+      },
+      dispose: () => {
+        disposed = true;
+        closeCurrentStepScope();
+        this.cleanup();
       }
-      await this.contextManager.flush();
-      this.setTelemetryAttributes(lastStepTokens);
-      this.eventBus.emit("run:complete", {
-        finishReason: lastFinishReason,
-        stepCount,
-        durationMs: Date.now() - startTime
-      });
-      return {
-        text: lastText,
-        stepCount,
-        usage: lastStepTokens,
-        finishReason: lastFinishReason
-      };
-    } catch (_2) {
-      var _error = _2, _hasError = true;
-    } finally {
-      __callDispose(_stack, _error, _hasError);
-    }
+    };
   }
   /**
    * Abort the current step execution.
@@ -319,6 +510,170 @@ class TurnExecutor {
   abort() {
     this.stepAbortController.abort();
   }
+  async validateInitialToolSupport() {
+    try {
+      return (await this.startTurn()).supportsTools;
+    } catch (error) {
+      this.cleanup();
+      throw error;
+    }
+  }
+  async startTurn() {
+    this.eventBus.emit("llm:thinking", {});
+    const supportsTools = await this.validateToolSupport();
+    if (!supportsTools) {
+      const modelKey = `${this.llmContext.provider}:${this.llmContext.model}`;
+      this.eventBus.emit("llm:unsupported-input", {
+        errors: [
+          `Model '${modelKey}' does not support tool calling.`,
+          "You can still chat, but the model will not be able to use tools or execute commands."
+        ],
+        provider: this.llmContext.provider,
+        model: this.llmContext.model,
+        details: {
+          feature: "tool-calling",
+          supported: false
+        }
+      });
+      this.logger.warn(
+        `Model ${modelKey} does not support tools - continuing without tool calling`
+      );
+    }
+    return { supportsTools };
+  }
+  startModelStepScope() {
+    this.stepAbortController = new AbortController();
+    const abortHandler = () => this.stepAbortController.abort();
+    if (this.externalSignal?.aborted) {
+      this.stepAbortController.abort();
+    } else if (this.externalSignal) {
+      this.externalSignal.addEventListener("abort", abortHandler, { once: true });
+    }
+    return {
+      [Symbol.dispose]: () => {
+        this.externalSignal?.removeEventListener("abort", abortHandler);
+      }
+    };
+  }
+  async finishTurn(input) {
+    await this.contextManager.flush();
+    this.setTelemetryAttributes(input.usage);
+    this.eventBus.emit("run:complete", {
+      finishReason: input.finishReason,
+      stepCount: input.stepCount,
+      durationMs: Date.now() - input.startTime
+    });
+    return {
+      text: input.text,
+      stepCount: input.stepCount,
+      usage: input.usage,
+      finishReason: input.finishReason
+    };
+  }
+  async failTurn(error, stepCount, startTime) {
+    const mappedError = this.mapProviderError(error);
+    this.logger.error("TurnExecutor failed", { error: mappedError });
+    this.eventBus.emit("llm:error", {
+      error: mappedError,
+      context: "TurnExecutor",
+      recoverable: false
+    });
+    await this.contextManager.flush();
+    this.eventBus.emit("run:complete", {
+      finishReason: "error",
+      stepCount,
+      durationMs: Date.now() - startTime,
+      error: mappedError
+    });
+    throw mappedError;
+  }
+  advanceStep(stepCount) {
+    const nextStepCount = stepCount + 1;
+    if (this.config.maxSteps !== void 0 && nextStepCount >= this.config.maxSteps) {
+      return {
+        kind: "stop",
+        stepCount: nextStepCount,
+        finishReason: "max-steps"
+      };
+    }
+    return {
+      kind: "continue",
+      stepCount: nextStepCount
+    };
+  }
+  async continueWithQueuedInput(kind, queue, stepCount, finishReason) {
+    const label = kind === "late-steer" ? "late steer" : "follow-up";
+    if (this.externalSignal?.aborted || finishReason === "cancelled") {
+      this.logger.debug(`Terminating: cancel received before ${label}`);
+      return {
+        kind: "stop",
+        stepCount,
+        finishReason: "cancelled"
+      };
+    }
+    const stepAdvance = this.advanceStep(stepCount);
+    if (stepAdvance.kind === "stop") {
+      this.logger.debug(`Terminating: reached maxSteps (${this.config.maxSteps})`);
+      return stepAdvance;
+    }
+    const queued = await queue.dequeueAll();
+    if (!queued) {
+      this.logger.debug(`Terminating: finishReason is "${finishReason}"`);
+      return {
+        kind: "stop",
+        stepCount: stepAdvance.stepCount,
+        finishReason
+      };
+    }
+    const messageName = kind === "late-steer" ? "steer" : "follow-up";
+    const suffix = kind === "late-steer" ? " at end of turn" : "";
+    this.logger.debug(
+      `Continuing: ${queued.messages.length} ${messageName} message(s) to process${suffix}`
+    );
+    await this.injectQueuedMessages(queued);
+    return {
+      kind: "continue",
+      stepCount: stepAdvance.stepCount
+    };
+  }
+  async decideNextStep(result, stepCount) {
+    if (result.finishReason === "tool-calls") {
+      await this.steerQueue.refresh();
+      if (this.externalSignal?.aborted && !this.steerQueue.hasPending()) {
+        this.logger.debug("Terminating: hard cancel - external abort signal received");
+        return {
+          kind: "stop",
+          stepCount,
+          finishReason: "cancelled"
+        };
+      }
+      return this.advanceStep(stepCount);
+    }
+    await this.steerQueue.refresh();
+    if (this.steerQueue.hasPending()) {
+      return this.continueWithQueuedInput(
+        "late-steer",
+        this.steerQueue,
+        stepCount,
+        result.finishReason
+      );
+    }
+    await this.followUpQueue.refresh();
+    if (this.followUpQueue.hasPending()) {
+      return this.continueWithQueuedInput(
+        "follow-up",
+        this.followUpQueue,
+        stepCount,
+        result.finishReason
+      );
+    }
+    this.logger.debug(`Terminating: finishReason is "${result.finishReason}"`);
+    return {
+      kind: "stop",
+      stepCount,
+      finishReason: result.finishReason
+    };
+  }
   /**
    * Inject coalesced queued messages into the context as a single user message.
    * This enables mid-task user guidance.
@@ -412,210 +767,526 @@ class TurnExecutor {
       return true;
     }
   }
-  /**
-   * Creates tools with execute callbacks and toModelOutput.
-   *
-   * Key design decisions:
-   * - execute() returns raw result with inline images (async)
-   * - toModelOutput() formats for LLM consumption (sync)
-   * - StreamProcessor handles persistence via tool-result events
-   */
-  async createTools() {
-    const tools = this.toolManager.filterToolsForSession(
+  async prepareNextModelRequest(input) {
+    const coalesced = await this.steerQueue.dequeueAll();
+    if (coalesced) {
+      await this.injectQueuedMessages(coalesced);
+    }
+    await this.pruneOldToolOutputs();
+    let prepared = await this.contextManager.getFormattedMessagesForLLM(
+      input.contributorContext,
+      this.llmContext
+    );
+    const toolDefinitions = input.supportsTools ? this.toolManager.filterToolsForSession(
       await this.toolManager.getAllTools(),
       this.sessionId
+    ) : {};
+    let estimatedInputTokens = await this.contextManager.getEstimatedNextInputTokens(
+      prepared.systemPrompt,
+      prepared.preparedHistory,
+      toolDefinitions
     );
-    return Object.fromEntries(
-      Object.entries(tools).map(([name, tool]) => [
-        name,
-        {
-          inputSchema: jsonSchema(tool.parameters),
-          ...tool.description && { description: tool.description },
-          /**
-           * Execute callback - runs the tool and returns raw result.
-           * Does NOT persist - StreamProcessor handles that on tool-result event.
-           *
-           * Uses Promise.race to ensure we return quickly on abort, even if the
-           * underlying tool (especially MCP tools we don't control) keeps running.
-           */
-          execute: async (args, options) => {
-            this.logger.debug(
-              `Executing tool: ${name} (toolCallId: ${options.toolCallId})`
-            );
-            const abortSignal = this.stepAbortController.signal;
-            if (abortSignal.aborted) {
-              this.logger.debug(`Tool ${name} cancelled before execution`);
-              return { error: "Cancelled by user", cancelled: true };
-            }
-            let abortHandler = null;
-            const abortPromise = new Promise(
-              (resolve) => {
-                abortHandler = () => {
-                  this.logger.debug(`Tool ${name} cancelled during execution`);
-                  resolve({ error: "Cancelled by user", cancelled: true });
-                };
-                abortSignal.addEventListener("abort", abortHandler, { once: true });
-              }
-            );
-            try {
-              const result = await Promise.race([
-                (async () => {
-                  const executionResult = await this.toolManager.executeTool(
-                    name,
-                    args,
-                    options.toolCallId,
-                    {
-                      sessionId: this.sessionId,
-                      abortSignal,
-                      ...this.runContext !== void 0 ? { runContext: this.runContext } : {}
-                    }
-                  );
-                  const metadata = (() => {
-                    const meta = {};
-                    if (executionResult.presentationSnapshot !== void 0) {
-                      meta.presentationSnapshot = executionResult.presentationSnapshot;
-                    }
-                    if (executionResult.meta !== void 0) {
-                      meta.meta = executionResult.meta;
-                    }
-                    if (executionResult.requireApproval !== void 0) {
-                      meta.requireApproval = executionResult.requireApproval;
-                      if (executionResult.approvalStatus !== void 0) {
-                        meta.approvalStatus = executionResult.approvalStatus;
-                      }
-                    }
-                    return Object.keys(meta).length > 0 ? meta : void 0;
-                  })();
-                  if (metadata) {
-                    this.toolCallMetadata.set(options.toolCallId, metadata);
-                  }
-                  return executionResult.result;
-                })(),
-                abortPromise
-              ]);
-              return result;
-            } finally {
-              if (abortHandler) {
-                abortSignal.removeEventListener("abort", abortHandler);
-              }
-            }
-          },
-          /**
-           * toModelOutput - formats raw result for LLM consumption.
-           * Called by Vercel SDK when preparing messages for next LLM call.
-           * SYNC - images are already inline in the raw result.
-           */
-          toModelOutput: (result) => {
-            return this.formatToolResultForLLM(result, name);
-          }
+    if (this.shouldCompact(estimatedInputTokens)) {
+      this.logger.debug(
+        `Pre-check: estimated ${estimatedInputTokens} tokens exceeds threshold, compacting`
+      );
+      const didCompact = await this.compactContext(
+        estimatedInputTokens,
+        input.contributorContext,
+        toolDefinitions
+      );
+      if (didCompact) {
+        prepared = await this.contextManager.getFormattedMessagesForLLM(
+          input.contributorContext,
+          this.llmContext
+        );
+        estimatedInputTokens = await this.contextManager.getEstimatedNextInputTokens(
+          prepared.systemPrompt,
+          prepared.preparedHistory,
+          toolDefinitions
+        );
+        this.logger.debug(
+          `Post-compaction: recomputed estimate is ${estimatedInputTokens} tokens`
+        );
+      }
+    }
+    const providerOptions = buildProviderOptions({
+      provider: this.llmContext.provider,
+      model: this.llmContext.model,
+      reasoning: this.config.reasoning
+    });
+    this.logger.debug("LLM request options", {
+      provider: this.llmContext.provider,
+      model: this.llmContext.model,
+      requestedReasoning: {
+        variant: this.config.reasoning?.variant,
+        budgetTokens: this.config.reasoning?.budgetTokens
+      },
+      providerOptions
+    });
+    const reasoningVariant = this.config.reasoning?.variant;
+    const reasoningBudgetTokens = getEffectiveReasoningBudgetTokens(providerOptions);
+    const reasoning = reasoningVariant !== void 0 || reasoningBudgetTokens !== void 0 ? {
+      ...reasoningVariant !== void 0 && { reasoningVariant },
+      ...reasoningBudgetTokens !== void 0 && { reasoningBudgetTokens }
+    } : void 0;
+    return {
+      messages: prepared.formattedMessages,
+      tools: input.supportsTools ? createModelToolDefinitions(toolDefinitions) : {},
+      toolDefinitions,
+      estimatedInputTokens,
+      reasoning,
+      providerOptions,
+      streaming: input.streaming
+    };
+  }
+  async restorePreparedModelRequest(state, supportsTools) {
+    const toolDefinitions = supportsTools ? structuredClone(state.toolDefinitions) : {};
+    return {
+      messages: structuredClone(state.messages),
+      tools: supportsTools ? createModelToolDefinitions(toolDefinitions) : {},
+      toolDefinitions,
+      estimatedInputTokens: state.estimatedInputTokens,
+      reasoning: state.reasoning === void 0 ? void 0 : {
+        ...state.reasoning.reasoningVariant === void 0 ? {} : { reasoningVariant: state.reasoning.reasoningVariant },
+        ...state.reasoning.reasoningBudgetTokens === void 0 ? {} : { reasoningBudgetTokens: state.reasoning.reasoningBudgetTokens }
+      },
+      providerOptions: state.providerOptions,
+      streaming: state.streaming
+    };
+  }
+  async runModelStep(request) {
+    const streamProcessor = new StreamProcessor(
+      this.contextManager,
+      this.eventBus,
+      this.stepAbortController.signal,
+      this.getStreamProcessorConfig(request.estimatedInputTokens, request.reasoning),
+      this.logger,
+      request.streaming
+    );
+    return streamProcessor.process(
+      () => streamText({
+        model: this.model,
+        stopWhen: stepCountIs(1),
+        maxRetries: 0,
+        tools: request.tools,
+        abortSignal: this.stepAbortController.signal,
+        messages: request.messages,
+        ...this.config.maxOutputTokens !== void 0 && {
+          maxOutputTokens: this.config.maxOutputTokens
+        },
+        ...this.config.temperature !== void 0 && {
+          temperature: this.config.temperature
+        },
+        // Provider-specific options (caching, reasoning, etc.)
+        ...request.providerOptions !== void 0 && {
+          providerOptions: request.providerOptions
+        },
+        // Log stream-level errors (tool errors, API errors during streaming)
+        onError: (error) => {
+          this.logger.error("Stream error", { error });
         }
-      ])
+      })
     );
   }
-  /**
-   * Format tool result for LLM consumption.
-   * Handles multimodal content (text + images).
-   *
-   * This handles RAW tool results - the structure may vary.
-   */
-  formatToolResultForLLM(result, toolName) {
-    if (result && typeof result === "object" && "error" in result) {
-      const errorResult = result;
-      let errorFlags = "";
-      if (errorResult.denied) errorFlags += " (denied)";
-      if (errorResult.timeout) errorFlags += " (timeout)";
+  async runModelStepWithRetry(request) {
+    for (let failedAttempts = 0; ; failedAttempts += 1) {
+      const historyLengthBefore = (await this.contextManager.getHistory()).length;
+      try {
+        return await this.runModelStep(request);
+      } catch (error) {
+        const historyLengthAfter = (await this.contextManager.getHistory()).length;
+        const historyLengthChanged = historyLengthAfter !== historyLengthBefore;
+        if (!this.canRetryModelRequest(error, historyLengthChanged) || failedAttempts >= MODEL_REQUEST_MAX_RETRIES) {
+          throw error;
+        }
+        const mappedError = this.mapProviderError(error);
+        this.eventBus.emit("llm:retrying", {
+          error: mappedError,
+          context: "TurnExecutor.runModelStep",
+          attempt: failedAttempts + 1,
+          maxRetries: MODEL_REQUEST_MAX_RETRIES,
+          provider: this.llmContext.provider,
+          model: this.llmContext.model
+        });
+        this.logger.warn("Retrying model request after transient failure", {
+          attempt: failedAttempts + 1,
+          maxRetries: MODEL_REQUEST_MAX_RETRIES,
+          error: mappedError
+        });
+      }
+    }
+  }
+  canRetryModelRequest(error, historyLengthChanged) {
+    if (historyLengthChanged) return false;
+    if (this.stepAbortController.signal.aborted) return false;
+    if (!APICallError.isInstance?.(error)) return false;
+    return error.isRetryable;
+  }
+  async applyModelStepResult(input) {
+    const { result, request, contributorContext } = input;
+    if (result.finishReason === "cancelled") {
+      this.logger.info(
+        `Context estimation (cancelled): keeping last known actuals, partial response (${result.text.length} chars) will be estimated`
+      );
+      return;
+    }
+    const contextInputTokens = this.getContextInputTokens(result.usage);
+    if (result.usage.inputTokens !== void 0) {
+      const actualInputTokens = contextInputTokens ?? result.usage.inputTokens;
+      const diff = request.estimatedInputTokens - actualInputTokens;
+      const diffPercent = actualInputTokens > 0 ? (diff / actualInputTokens * 100).toFixed(1) : "0.0";
+      this.logger.info(
+        `Context estimation accuracy: estimated=${request.estimatedInputTokens}, actual=${actualInputTokens}, error=${diff} (${diffPercent}%)`
+      );
+      this.contextManager.setLastActualInputTokens(actualInputTokens);
+      if (result.usage.outputTokens !== void 0) {
+        this.contextManager.setLastActualOutputTokens(result.usage.outputTokens);
+      }
+      await this.contextManager.recordLastCallMessageCount();
+    }
+    if (result.finishReason !== "tool-calls" && contextInputTokens && this.shouldCompactFromActual(contextInputTokens)) {
+      this.logger.debug(
+        `Post-response: actual ${contextInputTokens} tokens exceeds threshold, compacting`
+      );
+      await this.compactContext(
+        contextInputTokens,
+        contributorContext,
+        request.toolDefinitions
+      );
+    }
+  }
+  async executeModelToolCalls(toolCalls) {
+    const preparedCalls = [];
+    for (const toolCall of toolCalls) {
+      preparedCalls.push(await this.prepareModelToolCall(toolCall));
+    }
+    const executionResults = await Promise.all(
+      preparedCalls.map((prepared) => this.executePreparedModelToolCall(prepared))
+    );
+    for (let index = 0; index < toolCalls.length; index += 1) {
+      const toolCall = toolCalls[index];
+      const executionResult = executionResults[index];
+      if (toolCall === void 0 || executionResult === void 0) {
+        throw new Error("Tool call result count must match emitted tool call count");
+      }
+      await this.persistModelToolResult(toolCall, executionResult);
+    }
+  }
+  async prepareModelToolCall(toolCall) {
+    if (this.stepAbortController.signal.aborted) {
       return {
-        type: "text",
-        value: `Tool ${toolName} failed${errorFlags}: ${errorResult.error}`
+        kind: "terminal",
+        toolCall,
+        modelVisibleResult: this.cancelledToolResult(
+          this.buildToolCallFallbackSnapshot(toolCall.toolName)
+        )
       };
     }
-    if (this.hasMultimodalContent(result)) {
-      const contentArray = result.content;
-      const contentValue = [];
-      for (const part of contentArray) {
-        if (part.type === "text" && typeof part.text === "string") {
-          contentValue.push({ type: "text", text: part.text });
-        } else if (part.type === "image") {
-          const imageData = this.extractImageData(part);
-          if (imageData) {
-            contentValue.push({
-              type: "media",
-              data: imageData,
-              mediaType: part.mimeType || "image/jpeg"
-            });
-          }
-        } else if (part.type === "file") {
-          const fileData = this.extractFileData(part);
-          if (fileData) {
-            contentValue.push({
-              type: "media",
-              data: fileData,
-              mediaType: part.mimeType || "application/octet-stream"
-            });
-          }
-        }
+    let prepared;
+    try {
+      prepared = await this.toolManager.prepareToolCall({
+        toolName: toolCall.toolName,
+        input: toolCall.input,
+        toolCallId: toolCall.toolCallId,
+        sessionId: this.sessionId,
+        ...this.runContext !== void 0 ? { runContext: this.runContext } : {}
+      });
+    } catch (error) {
+      const modelVisibleResult = this.failedToolResult(
+        toolCall.toolName,
+        error,
+        this.buildToolCallFallbackSnapshot(toolCall.toolName)
+      );
+      this.emitFallbackToolCall(toolCall, modelVisibleResult);
+      return {
+        kind: "terminal",
+        toolCall,
+        modelVisibleResult
+      };
+    }
+    if (prepared.kind === "terminal") {
+      if ("call" in prepared) {
+        this.emitToolCall(toolCall, prepared.call);
+      } else {
+        this.emitFallbackToolCall(toolCall, prepared.modelVisibleResult);
+      }
+    } else {
+      this.emitToolCall(toolCall, prepared.call);
+    }
+    return { kind: "prepared", toolCall, prepared };
+  }
+  async executePreparedModelToolCall(preparedCall) {
+    try {
+      if (preparedCall.kind === "terminal") {
+        return preparedCall.modelVisibleResult;
+      }
+      const { prepared } = preparedCall;
+      if (prepared.kind === "terminal") {
+        return prepared.modelVisibleResult;
+      }
+      if (prepared.kind === "ready") {
+        return this.executePreparedToolCallWithAbort(
+          prepared.call,
+          this.resolveModelToolExecutionIdentity(preparedCall.toolCall.toolCallId)
+        );
+      }
+      const identity = this.resolveToolApprovalIdentity();
+      const recorded = await this.toolManager.recordApprovalRequest(prepared, identity);
+      const approval = await this.requestApprovalDecisionWithAbort(recorded);
+      if (approval.kind === "terminal") {
+        return approval.modelVisibleResult;
       }
-      if (contentValue.length > 0 && contentValue.some((v) => v.type === "media")) {
-        return { type: "content", value: contentValue };
+      const decision = this.toApprovalDecisionInput(approval.response);
+      const applied = await this.toolManager.applyApprovalDecision(
+        recorded,
+        decision,
+        this.runContext
+      );
+      if (applied.kind === "terminal") {
+        return applied.modelVisibleResult;
+      }
+      return this.executePreparedToolCallWithAbort(
+        applied.call,
+        this.resolveModelToolExecutionIdentity(preparedCall.toolCall.toolCallId)
+      );
+    } catch (error) {
+      return this.failedToolResult(
+        preparedCall.toolCall.toolName,
+        error,
+        this.getPreparedToolCallSnapshot(preparedCall)
+      );
+    }
+  }
+  emitFallbackToolCall(toolCall, executionResult) {
+    this.emitToolCall(toolCall, {
+      input: this.getToolCallInputForEvent(toolCall.input),
+      presentationSnapshot: executionResult.presentationSnapshot ?? this.buildToolCallFallbackSnapshot(toolCall.toolName),
+      toolName: toolCall.toolName
+    });
+  }
+  async executePreparedToolCallWithAbort(call, executionIdentity) {
+    const abortSignal = this.stepAbortController.signal;
+    let abortHandler = null;
+    const abortPromise = new Promise((resolve) => {
+      abortHandler = () => {
+        this.logger.debug(`Tool ${call.toolName} cancelled during execution`);
+        resolve(this.cancelledToolResult(call.presentationSnapshot, call));
+      };
+      abortSignal.addEventListener("abort", abortHandler, { once: true });
+    });
+    try {
+      return await Promise.race([
+        this.toolManager.executePreparedToolCall(call, {
+          sessionId: this.sessionId,
+          abortSignal,
+          executionIdentity,
+          ...this.runContext !== void 0 ? { runContext: this.runContext } : {}
+        }),
+        abortPromise
+      ]);
+    } finally {
+      if (abortHandler) {
+        abortSignal.removeEventListener("abort", abortHandler);
       }
-      const textParts = contentArray.filter((p) => p.type === "text" && typeof p.text === "string").map((p) => p.text);
+    }
+  }
+  async requestApprovalDecisionWithAbort(recorded) {
+    const abortSignal = this.stepAbortController.signal;
+    if (abortSignal.aborted) {
       return {
-        type: "text",
-        value: textParts.join("\n") || "[empty result]"
+        kind: "terminal",
+        modelVisibleResult: this.cancelledToolResult(
+          recorded.prepared.call.presentationSnapshot,
+          recorded.prepared.call
+        )
       };
     }
-    if (typeof result === "string") {
-      return { type: "text", value: result };
+    let abortHandler = null;
+    const abortPromise = new Promise((resolve) => {
+      abortHandler = () => {
+        this.logger.debug(
+          `Tool ${recorded.prepared.call.toolName} approval cancelled before execution`
+        );
+        resolve({
+          kind: "terminal",
+          modelVisibleResult: this.cancelledToolResult(
+            recorded.prepared.call.presentationSnapshot,
+            recorded.prepared.call
+          )
+        });
+      };
+      abortSignal.addEventListener("abort", abortHandler, { once: true });
+    });
+    try {
+      return await Promise.race([
+        this.toolManager.requestApprovalDecision(recorded).then((response) => ({ kind: "response", response })),
+        abortPromise
+      ]);
+    } finally {
+      if (abortHandler) {
+        abortSignal.removeEventListener("abort", abortHandler);
+      }
     }
+  }
+  cancelledToolResult(presentationSnapshot, call) {
     return {
-      type: "text",
-      value: typeof result === "object" && result !== null ? JSON.stringify(result) : String(result)
+      result: { error: "Cancelled by user", cancelled: true },
+      presentationSnapshot,
+      ...call?.meta !== void 0 ? { meta: call.meta } : {},
+      ...call?.approval !== void 0 ? call.approval : {}
     };
   }
-  /**
-   * Extract image data from a part, handling various formats.
-   */
-  extractImageData(part) {
-    if (typeof part.image === "string") {
-      return part.image;
-    }
-    if (typeof part.data === "string") {
-      return part.data;
+  failedToolResult(toolName, error, presentationSnapshot) {
+    const message = toError(error, this.logger).message;
+    this.logger.error(`Tool ${toolName} failed before execution result was produced`, {
+      error: message
+    });
+    return {
+      result: { error: message },
+      presentationSnapshot
+    };
+  }
+  getPreparedToolCallSnapshot(preparedCall) {
+    if (preparedCall.kind === "terminal") {
+      return preparedCall.modelVisibleResult.presentationSnapshot ?? this.buildToolCallFallbackSnapshot(preparedCall.toolCall.toolName);
     }
-    if (part.image instanceof Buffer) {
-      return part.image.toString("base64");
+    if ("call" in preparedCall.prepared) {
+      return preparedCall.prepared.call.presentationSnapshot;
     }
-    if (part.data instanceof Buffer) {
-      return part.data.toString("base64");
+    return preparedCall.prepared.modelVisibleResult.presentationSnapshot ?? this.buildToolCallFallbackSnapshot(preparedCall.toolCall.toolName);
+  }
+  async persistModelToolResult(toolCall, executionResult) {
+    const success = this.isToolExecutionSuccessful(executionResult);
+    const sanitized = await sanitizeToolResult(
+      executionResult.result,
+      {
+        artifactStore: this.resourceManager.getArtifactStore(),
+        toolName: toolCall.toolName,
+        toolCallId: toolCall.toolCallId,
+        success
+      },
+      this.logger
+    );
+    const truncated = truncateToolResult(sanitized);
+    const metadata = this.getToolExecutionMetadata(executionResult);
+    const errorMessage = this.getToolExecutionErrorMessage(executionResult.result);
+    await this.contextManager.addToolResult(
+      toolCall.toolCallId,
+      toolCall.toolName,
+      truncated,
+      metadata
+    );
+    this.eventBus.emit("llm:tool-result", {
+      toolName: toolCall.toolName,
+      ...metadata?.presentationSnapshot !== void 0 && {
+        presentationSnapshot: metadata.presentationSnapshot
+      },
+      ...metadata?.meta !== void 0 && {
+        meta: metadata.meta
+      },
+      callId: toolCall.toolCallId,
+      success,
+      sanitized: truncated,
+      rawResult: executionResult.result,
+      ...!success && errorMessage !== null ? { error: errorMessage } : {},
+      ...metadata?.requireApproval !== void 0 && {
+        requireApproval: metadata.requireApproval
+      },
+      ...metadata?.approvalStatus !== void 0 && {
+        approvalStatus: metadata.approvalStatus
+      }
+    });
+  }
+  emitToolCall(toolCall, call) {
+    this.eventBus.emit("llm:tool-call", {
+      toolName: toolCall.toolName,
+      ...call.presentationSnapshot !== void 0 && {
+        presentationSnapshot: call.presentationSnapshot
+      },
+      args: call.input,
+      ...call.meta !== void 0 ? { meta: call.meta } : {},
+      ...call.callDescription !== void 0 && { callDescription: call.callDescription },
+      callId: toolCall.toolCallId,
+      ...this.runContext?.hostRuntime !== void 0 && {
+        hostRuntime: this.runContext.hostRuntime
+      }
+    });
+  }
+  resolveToolApprovalIdentity() {
+    const ids = this.runContext?.hostRuntime?.ids;
+    return {
+      runId: ids?.runId ?? this.sessionId,
+      turnId: ids?.turnId ?? "in-memory-turn",
+      modelStepId: ids?.modelStepId ?? this.currentModelStepId
+    };
+  }
+  resolveModelToolExecutionIdentity(toolCallId) {
+    const ids = this.runContext?.hostRuntime?.ids;
+    return {
+      runId: ids?.runId ?? this.sessionId,
+      turnId: ids?.turnId ?? "in-memory-turn",
+      modelStepId: ids?.modelStepId ?? this.currentModelStepId,
+      toolCallId
+    };
+  }
+  toApprovalDecisionInput(response) {
+    if (response.status === ApprovalStatus.APPROVED) {
+      return {
+        approvalId: response.approvalId,
+        status: ApprovalStatus.APPROVED,
+        ...response.data !== void 0 ? { data: response.data } : {}
+      };
     }
-    if (part.image instanceof ArrayBuffer) {
-      return Buffer.from(new Uint8Array(part.image)).toString("base64");
+    const status = response.status === ApprovalStatus.DENIED ? ApprovalStatus.DENIED : ApprovalStatus.CANCELLED;
+    return {
+      approvalId: response.approvalId,
+      status,
+      ...response.reason !== void 0 ? { reason: response.reason } : {},
+      ...response.message !== void 0 ? { message: response.message } : {},
+      ...response.timeoutMs !== void 0 ? { timeoutMs: response.timeoutMs } : {},
+      ...response.data !== void 0 ? { data: response.data } : {}
+    };
+  }
+  getToolExecutionMetadata(executionResult) {
+    const metadata = {};
+    if (executionResult.presentationSnapshot !== void 0) {
+      metadata.presentationSnapshot = executionResult.presentationSnapshot;
     }
-    if (part.data instanceof ArrayBuffer) {
-      return Buffer.from(new Uint8Array(part.data)).toString("base64");
+    if (executionResult.meta !== void 0) {
+      metadata.meta = executionResult.meta;
     }
-    return null;
-  }
-  /**
-   * Extract file data from a part.
-   */
-  extractFileData(part) {
-    if (typeof part.data === "string") {
-      return part.data;
+    if (executionResult.requireApproval !== void 0) {
+      metadata.requireApproval = executionResult.requireApproval;
     }
-    if (part.data instanceof Buffer) {
-      return part.data.toString("base64");
+    if (executionResult.approvalStatus !== void 0) {
+      metadata.approvalStatus = executionResult.approvalStatus;
     }
-    if (part.data instanceof ArrayBuffer) {
-      return Buffer.from(new Uint8Array(part.data)).toString("base64");
+    return Object.keys(metadata).length > 0 ? metadata : void 0;
+  }
+  isToolExecutionSuccessful(executionResult) {
+    return !this.getToolExecutionErrorMessage(executionResult.result);
+  }
+  getToolExecutionErrorMessage(result) {
+    if (result && typeof result === "object" && "error" in result) {
+      const error = result.error;
+      return typeof error === "string" ? error : String(error);
     }
     return null;
   }
-  /**
-   * Check if result has multimodal content array
-   */
-  hasMultimodalContent(result) {
-    return result !== null && typeof result === "object" && "content" in result && Array.isArray(result.content);
+  getToolCallInputForEvent(input) {
+    return input !== null && typeof input === "object" && !Array.isArray(input) ? input : {};
+  }
+  buildToolCallFallbackSnapshot(toolName) {
+    return {
+      version: 1,
+      source: {
+        type: toolName.startsWith(MCP_TOOL_PREFIX) ? "mcp" : "local"
+      },
+      header: {
+        title: toolName.replace(/[_-]+/g, " ")
+      }
+    };
   }
   /**
    * Constants for pruning thresholds
@@ -686,16 +1357,16 @@ class TurnExecutor {
   }
   /**
    * Cleanup resources when execution scope exits.
-   * Called automatically via defer() on normal exit, throw, or abort.
+   * Called automatically by the turn driver on normal exit, throw, or abort.
    */
   cleanup() {
     this.logger.debug("TurnExecutor cleanup triggered");
     if (!this.stepAbortController.signal.aborted) {
       this.stepAbortController.abort();
     }
-    void this.messageQueue.clear().catch((error) => {
+    void this.steerQueue.clear().catch((error) => {
       this.logger.warn(
-        `Failed to clear queued follow-up messages during cleanup: ${error instanceof Error ? error.message : String(error)}`
+        `Failed to clear queued steer messages during cleanup: ${error instanceof Error ? error.message : String(error)}`
       );
     });
   }
@@ -909,5 +1580,8 @@ class TurnExecutor {
   }
 }
 export {
-  TurnExecutor
+  ModelStepResultStateSchema,
+  TurnDriverStateSchema,
+  TurnExecutor,
+  parseTurnDriverState
 };