@renxqoo/renx-code 0.0.8 → 0.0.10

package/vendor/agent-root/src/agent/agent/index.ts

@@ -1,1772 +0,0 @@
-import { createHash } from 'node:crypto';
-import {
-  Message,
-  AgentInput,
-  AgentCallbacks,
-  AgentContextUsage,
-  CompactionInfo,
-  StreamEvent,
-  ErrorDecision,
-  ToolDecision,
-} from '../types';
-import { ToolManager } from '../tool/tool-manager';
-import { LLMProvider, LLMRequestMessage, Tool, ToolCall } from '../../providers';
-import { EventEmitter } from 'events';
-import {
-  AgentAbortedError,
-  AgentError,
-  AgentUpstreamRetryableError,
-  MaxRetriesError,
-  TimeoutBudgetExceededError,
-  UnknownError,
-} from './error';
-import { mergeAgentLoggers, type AgentLogger } from './logger';
-import { compact, estimateMessagesTokens } from './compaction';
-import { LLMTool, ToolConcurrencyPolicy } from '../tool/types';
-import type { BackoffConfig } from '../../providers';
-import {
-  convertMessageToLLMMessage as toLLMMessage,
-  mergeLLMConfig as mergeLLMRequestConfig,
-  shouldSendMessageToLLM,
-} from './message-utils';
-import { processToolCallPairs } from '../utils/message';
-
-import {
-  createCheckpoint,
-  createDoneEvent,
-  createErrorEvent,
-  createProgressEvent,
-} from './stream-events';
-import {
-  buildExecutionWaves as buildToolExecutionWaves,
-  runWithConcurrencyAndLock as runTasksWithConcurrencyAndLock,
-} from './concurrency';
-import {
-  calculateRetryDelay as calculateRetryDelayWithBackoff,
-  isAbortError as isAbortErrorByMessage,
-  normalizeError as normalizeAgentError,
-} from './error-normalizer';
-import {
-  createExecutionAbortScope as createExecutionBudgetScope,
-  createStageAbortScope as createStageBudgetScope,
-  createTimeoutBudgetState as createBudgetState,
-  type AbortScope,
-  type TimeoutBudgetState,
-  type TimeoutStage,
-} from './timeout-budget';
-import {
-  buildWriteFileSessionKey as createWriteFileSessionKey,
-  bufferWriteFileToolCallChunk as bufferWriteFileChunk,
-  cleanupWriteFileBufferIfNeeded as cleanupWriteFileBufferSession,
-  enrichWriteFileToolError as buildWriteFileToolErrorPayload,
-  isWriteFileProtocolOutput as isWriteFileProtocolResponse,
-  isWriteFileToolCall as isWriteFileTool,
-  shouldEnrichWriteFileFailure as needEnrichWriteFileFailure,
-  type WriteBufferRuntime,
-} from './write-file-session';
-import {
-  createToolResultMessage as buildToolResultMessage,
-  NoopToolExecutionLedger,
-  executeToolCallWithLedger as executeWithToolLedger,
-  type ToolExecutionLedger,
-  type ToolExecutionLedgerRecord,
-} from './tool-execution-ledger';
-import {
-  emitMetric as pushMetric,
-  emitTrace as pushTrace,
-  endSpan as finishSpan,
-  extractErrorCode as parseErrorCode,
-  logError as writeErrorLog,
-  logInfo as writeInfoLog,
-  logWarn as writeWarnLog,
-  startSpan as beginSpan,
-  type SpanRuntime,
-} from './telemetry';
-import {
-  safeCallback as invokeSafeCallback,
-  safeErrorCallback as invokeSafeErrorCallback,
-} from './callback-safety';
-import { mergeToolCalls as mergeToolCallsWithBuffer } from './tool-call-merge';
-import type { ToolResult } from '../tool/base-tool';
-import {
-  normalizeTimeoutBudgetError as normalizeAbortTimeoutBudgetError,
-  sleepWithAbort,
-  throwIfAborted as assertNotAborted,
-  timeoutBudgetErrorFromSignal as timeoutErrorFromAbortSignal,
-} from './abort-runtime';
-
-function generateId(prefix: string): string {
-  return `${prefix}${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
-}
-
-function hasNonEmptyText(value: unknown): value is string {
-  return typeof value === 'string' && value.length > 0;
-}
-
-type ContinuationMetadata = {
-  responseId?: string;
-  llmRequestConfigHash?: string;
-  llmRequestInputHash?: string;
-  llmRequestInputMessageCount?: number;
-  llmResponseMessageHash?: string;
-  continuationMode?: 'full' | 'incremental';
-  previousResponseIdUsed?: string;
-  continuationBaselineMessageCount?: number;
-  continuationDeltaMessageCount?: number;
-};
-
-type LLMRequestPlan = {
-  llmMessages: LLMRequestMessage[];
-  requestMessages: LLMRequestMessage[];
-  requestConfig: AgentInput['config'];
-  requestConfigHash: string;
-  requestInputHash: string;
-  requestInputMessageCount: number;
-  continuationMode: 'full' | 'incremental';
-  previousResponseIdUsed?: string;
-  continuationBaselineMessageCount?: number;
-  continuationDeltaMessageCount: number;
-};
-
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function normalizeValueForHash(value: unknown): unknown {
-  if (value === undefined) {
-    return null;
-  }
-  if (
-    value === null ||
-    typeof value === 'string' ||
-    typeof value === 'number' ||
-    typeof value === 'boolean'
-  ) {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => normalizeValueForHash(item));
-  }
-  if (typeof value === 'object') {
-    return Object.keys(value as Record<string, unknown>)
-      .sort()
-      .reduce<Record<string, unknown>>((acc, key) => {
-        const normalized = normalizeValueForHash((value as Record<string, unknown>)[key]);
-        if (normalized !== undefined) {
-          acc[key] = normalized;
-        }
-        return acc;
-      }, {});
-  }
-  return String(value);
-}
-
-function hashValueForContinuation(value: unknown): string {
-  return createHash('sha256')
-    .update(JSON.stringify(normalizeValueForHash(value)))
-    .digest('hex');
-}
-
-export interface AgentConfig {
-  maxRetryCount?: number;
-  enableCompaction?: boolean;
-  compactionTriggerRatio?: number;
-  compactionKeepMessagesNum?: number;
-  enableServerSideContinuation?: boolean;
-  backoffConfig?: BackoffConfig;
-  maxConcurrentToolCalls?: number;
-  toolConcurrencyPolicyResolver?: (toolCall: ToolCall) => ToolConcurrencyPolicy;
-  logger?: AgentLogger;
-  /**
-   * Optional external idempotency ledger.
-   * Defaults to Noop to keep the agent stateless across process restarts and scale-out replicas.
-   */
-  toolExecutionLedger?: ToolExecutionLedger;
-  timeoutBudgetMs?: number;
-  llmTimeoutRatio?: number;
-}
-
-export type { AgentLogger } from './logger';
-
-interface InternalAgentConfig {
-  maxRetryCount: number;
-  enableCompaction: boolean;
-  compactionTriggerRatio: number;
-  compactionKeepMessagesNum: number;
-  enableServerSideContinuation: boolean;
-  backoffConfig: BackoffConfig;
-  maxConcurrentToolCalls: number;
-  toolConcurrencyPolicyResolver?: (toolCall: ToolCall) => ToolConcurrencyPolicy;
-  logger: AgentLogger;
-  timeoutBudgetMs?: number;
-  llmTimeoutRatio: number;
-}
-
-const DEFAULT_MAX_RETRY_COUNT = 20;
-const DEFAULT_COMPACTION_TRIGGER_RATIO = 0.8;
-const DEFAULT_COMPACTION_KEEP_MESSAGES = 20;
-const DEFAULT_MAX_CONCURRENT_TOOL_CALLS = 1;
-const DEFAULT_LLM_TIMEOUT_RATIO = 0.7;
-const ABORTED_MESSAGE = 'Operation aborted';
-
-export type { ToolExecutionLedger, ToolExecutionLedgerRecord } from './tool-execution-ledger';
-
-export class StatelessAgent extends EventEmitter {
-  private llmProvider: LLMProvider;
-  private toolExecutor: ToolManager;
-  private config: InternalAgentConfig;
-  private logger: AgentLogger;
-  private toolExecutionLedger: ToolExecutionLedger;
-  constructor(llmProvider: LLMProvider, toolExecutor: ToolManager, config: AgentConfig) {
-    super();
-    this.llmProvider = llmProvider;
-    this.toolExecutor = toolExecutor;
-    this.logger = config.logger ?? {};
-    this.toolExecutionLedger = config.toolExecutionLedger ?? new NoopToolExecutionLedger();
-    const llmTimeoutRatio = Number.isFinite(config.llmTimeoutRatio)
-      ? Number(config.llmTimeoutRatio)
-      : DEFAULT_LLM_TIMEOUT_RATIO;
-    const clampedLlmTimeoutRatio = Math.min(0.95, Math.max(0.05, llmTimeoutRatio));
-    this.config = {
-      maxRetryCount: config.maxRetryCount ?? DEFAULT_MAX_RETRY_COUNT,
-      enableCompaction: config.enableCompaction ?? false,
-      compactionTriggerRatio: config.compactionTriggerRatio ?? DEFAULT_COMPACTION_TRIGGER_RATIO,
-      compactionKeepMessagesNum:
-        config.compactionKeepMessagesNum ?? DEFAULT_COMPACTION_KEEP_MESSAGES,
-      enableServerSideContinuation: config.enableServerSideContinuation ?? false,
-      backoffConfig: config.backoffConfig ?? {},
-      maxConcurrentToolCalls: Math.max(
-        1,
-        Math.floor(config.maxConcurrentToolCalls ?? DEFAULT_MAX_CONCURRENT_TOOL_CALLS)
-      ),
-      toolConcurrencyPolicyResolver: config.toolConcurrencyPolicyResolver,
-      logger: this.logger,
-      timeoutBudgetMs:
-        config.timeoutBudgetMs &&
-        Number.isFinite(config.timeoutBudgetMs) &&
-        config.timeoutBudgetMs > 0
-          ? Math.floor(config.timeoutBudgetMs)
-          : undefined,
-      llmTimeoutRatio: clampedLlmTimeoutRatio,
-    };
-  }
-
-  getContextLimitTokens(contextLimitTokens?: number): number {
-    if (
-      typeof contextLimitTokens === 'number' &&
-      Number.isFinite(contextLimitTokens) &&
-      contextLimitTokens > 0
-    ) {
-      return Math.max(1, Math.floor(contextLimitTokens));
-    }
-    const maxTokens = this.llmProvider.getLLMMaxTokens();
-    const maxOutputTokens = this.llmProvider.getMaxOutputTokens();
-    return Math.max(1, maxTokens - maxOutputTokens);
-  }
-
-  estimateContextUsage(
-    messages: Message[],
-    tools?: Tool[],
-    contextLimitTokens?: number
-  ): Pick<AgentContextUsage, 'contextTokens' | 'contextLimitTokens' | 'contextUsagePercent'> {
-    const llmTools = tools as unknown as LLMTool[] | undefined;
-    const contextTokens = estimateMessagesTokens(messages, llmTools);
-    const resolvedContextLimitTokens = this.getContextLimitTokens(contextLimitTokens);
-    return {
-      contextTokens,
-      contextLimitTokens: resolvedContextLimitTokens,
-      contextUsagePercent: (contextTokens / resolvedContextLimitTokens) * 100,
-    };
-  }
-
-  attachLogger(logger: AgentLogger): void {
-    this.logger = mergeAgentLoggers(this.logger, logger);
-    this.config.logger = this.logger;
-  }
-
-  private convertMessageToLLMMessage(message: Message) {
-    return toLLMMessage(message);
-  }
-
-  private normalizeContinuationConfig(config: AgentInput['config']): Record<string, unknown> {
-    if (!config) {
-      return {};
-    }
-
-    const { abortSignal, previous_response_id, ...rest } = config as AgentInput['config'] & {
-      abortSignal?: AbortSignal;
-      previous_response_id?: string;
-    };
-    void abortSignal;
-    void previous_response_id;
-
-    return normalizeValueForHash(rest) as Record<string, unknown>;
-  }
-
-  private readContinuationMetadata(message: Message): ContinuationMetadata | undefined {
-    if (!isPlainRecord(message.metadata)) {
-      return undefined;
-    }
-
-    const metadata = message.metadata as Record<string, unknown>;
-    const responseId =
-      typeof metadata.responseId === 'string' && metadata.responseId.trim().length > 0
-        ? metadata.responseId
-        : undefined;
-    const llmRequestConfigHash =
-      typeof metadata.llmRequestConfigHash === 'string' ? metadata.llmRequestConfigHash : undefined;
-    const llmRequestInputHash =
-      typeof metadata.llmRequestInputHash === 'string' ? metadata.llmRequestInputHash : undefined;
-    const llmRequestInputMessageCount =
-      typeof metadata.llmRequestInputMessageCount === 'number'
-        ? metadata.llmRequestInputMessageCount
-        : undefined;
-    const llmResponseMessageHash =
-      typeof metadata.llmResponseMessageHash === 'string'
-        ? metadata.llmResponseMessageHash
-        : undefined;
-
-    if (
-      !responseId ||
-      !llmRequestConfigHash ||
-      !llmRequestInputHash ||
-      typeof llmRequestInputMessageCount !== 'number' ||
-      !Number.isInteger(llmRequestInputMessageCount) ||
-      llmRequestInputMessageCount < 0 ||
-      !llmResponseMessageHash
-    ) {
-      return undefined;
-    }
-
-    const safeInputMessageCount = llmRequestInputMessageCount;
-
-    return {
-      responseId,
-      llmRequestConfigHash,
-      llmRequestInputHash,
-      llmRequestInputMessageCount: safeInputMessageCount,
-      llmResponseMessageHash,
-    };
-  }
-
-  private buildLLMRequestPlan(messages: Message[], config: AgentInput['config']): LLMRequestPlan {
-    const llmSourceMessages = messages.filter((msg) => shouldSendMessageToLLM(msg));
-    const llmMessages = llmSourceMessages.map((msg) => this.convertMessageToLLMMessage(msg));
-    const requestConfigHash = hashValueForContinuation(this.normalizeContinuationConfig(config));
-    const requestInputHash = hashValueForContinuation(llmMessages);
-    const requestInputMessageCount = llmMessages.length;
-
-    const explicitPreviousResponseId =
-      typeof config?.previous_response_id === 'string' &&
-      config.previous_response_id.trim().length > 0
-        ? config.previous_response_id
-        : undefined;
-
-    if (explicitPreviousResponseId) {
-      return {
-        llmMessages,
-        requestMessages: llmMessages,
-        requestConfig: config,
-        requestConfigHash,
-        requestInputHash,
-        requestInputMessageCount,
-        continuationMode: 'full',
-        continuationDeltaMessageCount: llmMessages.length,
-      };
-    }
-
-    // Keep server-side continuation opt-in. In the current gateway environment
-    // full replay + prompt_cache_key is more stable than automatic previous_response_id chaining.
-    if (!this.config.enableServerSideContinuation) {
-      return {
-        llmMessages,
-        requestMessages: llmMessages,
-        requestConfig: config,
-        requestConfigHash,
-        requestInputHash,
-        requestInputMessageCount,
-        continuationMode: 'full',
-        continuationDeltaMessageCount: llmMessages.length,
-      };
-    }
-
-    for (let index = llmSourceMessages.length - 1; index >= 0; index -= 1) {
-      const candidate = llmSourceMessages[index];
-      if (candidate.role !== 'assistant') {
-        continue;
-      }
-
-      const metadata = this.readContinuationMetadata(candidate);
-      if (!metadata) {
-        continue;
-      }
-
-      if (metadata.llmRequestConfigHash !== requestConfigHash) {
-        break;
-      }
-
-      const prefixMessages = llmMessages.slice(0, index);
-      const currentAssistantMessage = llmMessages[index];
-      if (!currentAssistantMessage) {
-        break;
-      }
-
-      if (prefixMessages.length !== metadata.llmRequestInputMessageCount) {
-        break;
-      }
-
-      if (hashValueForContinuation(prefixMessages) !== metadata.llmRequestInputHash) {
-        break;
-      }
-
-      if (hashValueForContinuation(currentAssistantMessage) !== metadata.llmResponseMessageHash) {
-        break;
-      }
-
-      // If the delta contains a tool result, the paired assistant tool_call must
-      // be included as well, otherwise the Responses gateway rejects the request shape.
-      const continuationWindow = processToolCallPairs(
-        llmSourceMessages.slice(0, index + 1),
-        llmSourceMessages.slice(index + 1)
-      );
-      const deltaSourceMessages = continuationWindow.active;
-      if (deltaSourceMessages.length === 0) {
-        break;
-      }
-      const deltaMessages = deltaSourceMessages.map((msg) => this.convertMessageToLLMMessage(msg));
-
-      return {
-        llmMessages,
-        requestMessages: deltaMessages,
-        requestConfig: {
-          ...(config || {}),
-          previous_response_id: metadata.responseId,
-        },
-        requestConfigHash,
-        requestInputHash,
-        requestInputMessageCount,
-        continuationMode: 'incremental',
-        previousResponseIdUsed: metadata.responseId,
-        continuationBaselineMessageCount: continuationWindow.pending.length,
-        continuationDeltaMessageCount: deltaMessages.length,
-      };
-    }
-
-    return {
-      llmMessages,
-      requestMessages: llmMessages,
-      requestConfig: config,
-      requestConfigHash,
-      requestInputHash,
-      requestInputMessageCount,
-      continuationMode: 'full',
-      continuationDeltaMessageCount: llmMessages.length,
-    };
-  }
-
-  private needsCompaction(
-    messages: Message[],
-    tools?: Tool[],
-    contextLimitTokens?: number
-  ): boolean {
-    if (!this.config.enableCompaction) {
-      return false;
-    }
-
-    const usableLimit = this.getContextLimitTokens(contextLimitTokens);
-    const threshold = usableLimit * this.config.compactionTriggerRatio;
-
-    const llmTools = tools as unknown as LLMTool[] | undefined;
-    const currentTokens = estimateMessagesTokens(messages, llmTools);
-
-    return currentTokens >= threshold;
-  }
-
-  private async compactMessagesIfNeeded(
-    messages: Message[],
-    tools?: Tool[],
-    contextLimitTokens?: number
-  ): Promise<string[]> {
-    if (!this.needsCompaction(messages, tools, contextLimitTokens)) {
-      return [];
-    }
-
-    try {
-      const result = await compact(messages, {
-        provider: this.llmProvider,
-        keepMessagesNum: this.config.compactionKeepMessagesNum,
-      });
-      messages.splice(0, messages.length, ...result.messages);
-
-      return result.removedMessageIds ?? [];
-    } catch (error) {
-      this.logError('[Agent] Compaction failed:', error);
-      return [];
-    }
-  }
-
-  async *runStream(
-    input: AgentInput,
-    callbacks?: AgentCallbacks
-  ): AsyncGenerator<StreamEvent, void, unknown> {
-    const { messages: inputMessages, maxSteps = 100, abortSignal: inputAbortSignal } = input;
-    const effectiveTools = this.resolveLLMTools(input.tools);
-    const messages = [...inputMessages];
-    if (typeof input.systemPrompt === 'string' && input.systemPrompt.trim().length > 0) {
-      const hasSystemMessage = messages.some((message) => message.role === 'system');
-      if (!hasSystemMessage) {
-        messages.unshift({
-          messageId: generateId('msg_sys_'),
-          type: 'system',
-          role: 'system',
-          content: input.systemPrompt,
-          timestamp: Date.now(),
-        });
-      }
-    }
-    const writeBufferSessions = new Map<string, WriteBufferRuntime>();
-    const timeoutBudget = this.createTimeoutBudgetState(input);
-    const executionScope = this.createExecutionAbortScope(inputAbortSignal, timeoutBudget);
-    const abortSignal = executionScope.signal;
-    const traceId = input.executionId || generateId('trace_');
-    const runSpan = await this.startSpan(callbacks, traceId, 'agent.run', undefined, {
-      executionId: input.executionId,
-      conversationId: input.conversationId,
-      maxSteps,
-      timeoutBudgetMs: timeoutBudget?.totalMs,
-    });
-    this.logInfo('[Agent] run.start', {
-      executionId: input.executionId,
-      traceId,
-      spanId: runSpan.spanId,
-      messageCount: messages.length,
-    });
-
-    let stepIndex = 0;
-    let retryCount = 0;
-    let runOutcome: 'done' | 'error' | 'aborted' | 'timeout' | 'max_retries' | 'max_steps' = 'done';
-    let runErrorCode: string | undefined;
-    let terminalDoneEmitted = false;
-
-    try {
-      while (stepIndex < maxSteps) {
-        if (abortSignal?.aborted) {
-          const timeoutError = this.timeoutBudgetErrorFromSignal(abortSignal);
-          if (timeoutError) {
-            runOutcome = 'timeout';
-            runErrorCode = timeoutError.errorCode;
-            yield* this.yieldErrorEvent(timeoutError);
-          } else {
-            runOutcome = 'aborted';
-            runErrorCode = 'AGENT_ABORTED';
-            yield* this.yieldErrorEvent(new AgentAbortedError(ABORTED_MESSAGE));
-          }
-          break;
-        }
-
-        if (retryCount >= this.config.maxRetryCount) {
-          runOutcome = 'max_retries';
-          runErrorCode = 'AGENT_MAX_RETRIES_REACHED';
-          yield* this.yieldMaxRetriesError();
-          break;
-        }
-
-        stepIndex++;
-
-        try {
-          this.throwIfAborted(abortSignal);
-          const messageCountBeforeCompaction = messages.length;
-          const removedMessageIds = await this.compactMessagesIfNeeded(
-            messages,
-            effectiveTools,
-            input.contextLimitTokens
-          );
-          if (removedMessageIds.length > 0) {
-            const compactionInfo: CompactionInfo = {
-              executionId: input.executionId,
-              stepIndex,
-              removedMessageIds,
-              messageCountBefore: messageCountBeforeCompaction,
-              messageCountAfter: messages.length,
-            };
-            await this.safeCallback(callbacks?.onCompaction, compactionInfo);
-            yield {
-              type: 'compaction',
-              data: compactionInfo,
-            };
-          }
-
-          this.throwIfAborted(abortSignal);
-
-          const contextUsage = this.estimateContextUsage(
-            messages,
-            effectiveTools,
-            input.contextLimitTokens
-          );
-          await this.safeCallback(callbacks?.onContextUsage, {
-            stepIndex,
-            messageCount: messages.length,
-            ...contextUsage,
-          });
-
-          yield* this.emitProgress(input.executionId, stepIndex, 'llm', messages.length);
-          const llmSpan = await this.startSpan(
-            callbacks,
-            traceId,
-            'agent.llm.step',
-            runSpan.spanId,
-            {
-              executionId: input.executionId,
-              stepIndex,
-              messageCount: messages.length,
-            }
-          );
-          const llmScope = this.createStageAbortScope(abortSignal, timeoutBudget, 'llm');
-          let llmResult:
-            | {
-                assistantMessage: Message;
-                toolCalls: ToolCall[];
-              }
-            | undefined;
-          let llmErrorCode: string | undefined;
-          let llmSucceeded = false;
-          try {
-            const llmGen = this.callLLMAndProcessStream(
-              messages,
-              this.mergeLLMConfig(
-                input.config,
-                effectiveTools,
-                llmScope.signal,
-                input.conversationId
-              ),
-              llmScope.signal,
-              input.executionId,
-              stepIndex,
-              writeBufferSessions
-            );
-            for (;;) {
-              const next = await llmGen.next();
-              if (next.done) {
-                llmResult = next.value;
-                break;
-              }
-              yield next.value as StreamEvent;
-            }
-            this.throwIfAborted(llmScope.signal);
-            llmSucceeded = true;
-          } catch (error) {
-            llmErrorCode = this.extractErrorCode(error) || 'AGENT_LLM_STAGE_FAILED';
-            throw error;
-          } finally {
-            llmScope.release();
-            const llmLatencyMs = Date.now() - llmSpan.startedAt;
-            await this.emitMetric(callbacks, {
-              name: 'agent.llm.duration_ms',
-              value: llmLatencyMs,
-              unit: 'ms',
-              timestamp: Date.now(),
-              tags: {
-                executionId: input.executionId,
-                stepIndex,
-                success: llmSucceeded ? 'true' : 'false',
-              },
-            });
-            await this.endSpan(callbacks, llmSpan, {
-              executionId: input.executionId,
-              stepIndex,
-              latencyMs: llmLatencyMs,
-              errorCode: llmErrorCode,
-            });
-            this.logInfo('[Agent] llm.step', {
-              executionId: input.executionId,
-              traceId,
-              spanId: llmSpan.spanId,
-              stepIndex,
-              latencyMs: llmLatencyMs,
-              errorCode: llmErrorCode,
-              messageCount: messages.length,
-            });
-          }
-
-          if (!llmResult) {
-            throw new UnknownError('LLM stream completed without result');
-          }
-          const assistantMessage = llmResult.assistantMessage;
-          const toolCalls = llmResult.toolCalls;
-
-          messages.push(assistantMessage);
-          await this.safeCallback(callbacks?.onMessage, assistantMessage);
-
-          if (toolCalls.length > 0) {
-            yield* this.emitProgress(input.executionId, stepIndex, 'tool', messages.length);
-            const toolStageSpan = await this.startSpan(
-              callbacks,
-              traceId,
-              'agent.tool.stage',
-              runSpan.spanId,
-              {
-                executionId: input.executionId,
-                stepIndex,
-                toolCalls: toolCalls.length,
-              }
-            );
-            const toolScope = this.createStageAbortScope(abortSignal, timeoutBudget, 'tool');
-            let toolResultMessage: Message | undefined;
-            let toolStageErrorCode: string | undefined;
-            let toolStageSucceeded = false;
-            try {
-              const toolGen = this.processToolCalls(
-                toolCalls,
-                messages,
-                stepIndex,
-                callbacks,
-                toolScope.signal,
-                input.executionId,
-                traceId,
-                toolStageSpan.spanId,
-                writeBufferSessions
-              );
-              for (;;) {
-                const next = await toolGen.next();
-                if (next.done) {
-                  toolResultMessage = next.value;
-                  break;
-                }
-                yield next.value as StreamEvent;
-              }
-              toolStageSucceeded = true;
-            } catch (error) {
-              toolStageErrorCode = this.extractErrorCode(error) || 'AGENT_TOOL_STAGE_FAILED';
-              throw error;
-            } finally {
-              toolScope.release();
-              const toolStageLatencyMs = Date.now() - toolStageSpan.startedAt;
-              await this.emitMetric(callbacks, {
-                name: 'agent.tool.stage.duration_ms',
-                value: toolStageLatencyMs,
-                unit: 'ms',
-                timestamp: Date.now(),
-                tags: {
-                  executionId: input.executionId,
-                  stepIndex,
-                  success: toolStageSucceeded ? 'true' : 'false',
-                },
-              });
-              await this.endSpan(callbacks, toolStageSpan, {
-                executionId: input.executionId,
-                stepIndex,
-                latencyMs: toolStageLatencyMs,
-                errorCode: toolStageErrorCode,
-                toolCalls: toolCalls.length,
-              });
-              this.logInfo('[Agent] tool.stage', {
-                executionId: input.executionId,
-                traceId,
-                spanId: toolStageSpan.spanId,
-                stepIndex,
-                latencyMs: toolStageLatencyMs,
-                errorCode: toolStageErrorCode,
-                toolCalls: toolCalls.length,
-              });
-            }
-
-            const lastMessage = toolResultMessage;
-            yield* this.yieldCheckpoint(input.executionId, stepIndex, lastMessage, callbacks);
-            continue;
-          }
-
-          retryCount = 0;
-          runOutcome = 'done';
-          terminalDoneEmitted = true;
-          yield* this.yieldDoneEvent(stepIndex, 'stop');
-          break;
-        } catch (error) {
-          const timeoutError = this.normalizeTimeoutBudgetError(error, abortSignal);
-          if (timeoutError) {
-            runOutcome = 'timeout';
-            runErrorCode = timeoutError.errorCode;
-            yield* this.yieldErrorEvent(timeoutError);
-            break;
-          }
-
-          if (this.isAbortError(error) || inputAbortSignal?.aborted) {
-            runOutcome = 'aborted';
-            runErrorCode = 'AGENT_ABORTED';
-            yield* this.yieldErrorEvent(new AgentAbortedError(ABORTED_MESSAGE));
-            break;
-          }
-
-          const normalizedError = this.normalizeError(error);
-          this.logError('[Agent] run.error', normalizedError, {
-            executionId: input.executionId,
-            traceId,
-            stepIndex,
-            retryCount,
-            errorCode: normalizedError.errorCode,
-            category: normalizedError.category,
-          });
-          runOutcome = 'error';
-          runErrorCode = normalizedError.errorCode;
-          const decision = await this.safeErrorCallback(callbacks?.onError, normalizedError);
-          yield* this.yieldErrorEvent(normalizedError);
-
-          const shouldRetry = decision?.retry ?? normalizedError.retryable;
-          if (!shouldRetry) {
-            break;
-          }
-
-          retryCount++;
-          this.logWarn('[Agent] retry.scheduled', {
-            executionId: input.executionId,
-            traceId,
-            stepIndex,
-            retryCount,
-            errorCode: normalizedError.errorCode,
-          });
-          if (retryCount < this.config.maxRetryCount) {
-            const retryDelay = this.calculateRetryDelay(retryCount, error as Error);
-            try {
-              await this.sleep(retryDelay, abortSignal);
-            } catch (sleepError) {
-              const sleepTimeoutError = this.normalizeTimeoutBudgetError(sleepError, abortSignal);
-              if (sleepTimeoutError) {
-                runOutcome = 'timeout';
-                runErrorCode = sleepTimeoutError.errorCode;
-                yield* this.yieldErrorEvent(sleepTimeoutError);
-                break;
-              }
-              if (this.isAbortError(sleepError) || inputAbortSignal?.aborted) {
-                runOutcome = 'aborted';
-                runErrorCode = 'AGENT_ABORTED';
-                yield* this.yieldErrorEvent(new AgentAbortedError(ABORTED_MESSAGE));
-                break;
-              }
-              throw sleepError;
-            }
-          }
-        }
-      }
-
-      if (!terminalDoneEmitted && runOutcome === 'done' && stepIndex >= maxSteps) {
-        runOutcome = 'max_steps';
-        terminalDoneEmitted = true;
-        yield* this.yieldDoneEvent(stepIndex, 'max_steps');
-      }
-    } finally {
-      const runLatencyMs = Date.now() - runSpan.startedAt;
-      await this.emitMetric(callbacks, {
-        name: 'agent.run.duration_ms',
-        value: runLatencyMs,
-        unit: 'ms',
-        timestamp: Date.now(),
-        tags: {
-          executionId: input.executionId,
-          outcome: runOutcome,
-        },
-      });
-      await this.emitMetric(callbacks, {
-        name: 'agent.retry.count',
-        value: retryCount,
-        unit: 'count',
-        timestamp: Date.now(),
-        tags: {
-          executionId: input.executionId,
-        },
-      });
-      await this.endSpan(callbacks, runSpan, {
-        executionId: input.executionId,
-        stepIndex,
-        latencyMs: runLatencyMs,
-        outcome: runOutcome,
-        errorCode: runErrorCode,
-        retryCount,
-      });
-      this.logInfo('[Agent] run.finish', {
-        executionId: input.executionId,
-        traceId,
-        spanId: runSpan.spanId,
-        stepIndex,
-        latencyMs: runLatencyMs,
-        outcome: runOutcome,
-        errorCode: runErrorCode,
-        retryCount,
-      });
-      executionScope.release();
-    }
-  }
-
-  private async safeCallback<T>(
-    callback: ((arg: T) => void | Promise<void>) | undefined,
-    arg: T
-  ): Promise<void> {
-    await invokeSafeCallback(callback, arg, (error) =>
-      this.logError('[Agent] Callback error:', error)
-    );
-  }
-
-  private async safeErrorCallback(
-    callback: ((error: Error) => ErrorDecision | void | Promise<ErrorDecision | void>) | undefined,
-    error: Error
-  ): Promise<ErrorDecision | undefined> {
-    return invokeSafeErrorCallback(callback, error, (err) =>
-      this.logError('[Agent] Error callback error:', err)
-    );
-  }
-
-  private async mergeToolCalls(
-    existing: ToolCall[],
-    newCalls: ToolCall[],
-    messageId: string,
-    executionId: string | undefined,
-    stepIndex: number,
-    writeBufferSessions: Map<string, WriteBufferRuntime>
-  ): Promise<ToolCall[]> {
-    return mergeToolCallsWithBuffer({
-      existing,
-      incoming: newCalls,
-      messageId,
-      onArgumentsChunk: async (toolCall, argumentsChunk, chunkMessageId) => {
-        const sessionKey = createWriteFileSessionKey({
-          executionId,
-          stepIndex,
-          toolCallId: toolCall.id,
-        });
-        await bufferWriteFileChunk({
-          toolCall,
-          argumentsChunk,
-          messageId: chunkMessageId,
-          sessionKey,
-          sessions: writeBufferSessions,
-          onError: (error) =>
-            this.logError('[Agent] Failed to buffer write_file tool chunk:', error),
-        });
-      },
-    });
-  }
-
-  private async *callLLMAndProcessStream(
-    messages: Message[],
-    config: AgentInput['config'],
-    abortSignal?: AbortSignal,
-    executionId?: string,
-    stepIndex = 0,
-    writeBufferSessions: Map<string, WriteBufferRuntime> = new Map()
-  ): AsyncGenerator<StreamEvent, { assistantMessage: Message; toolCalls: ToolCall[] }, unknown> {
-    const requestPlan = this.buildLLMRequestPlan(messages, config);
-    const stream = this.llmProvider.generateStream(
-      requestPlan.requestMessages,
-      requestPlan.requestConfig
-    );
-
-    const assistantMessage: Message = {
-      messageId: generateId('msg_'),
-      type: 'assistant-text',
-      role: 'assistant',
-      content: '',
-      reasoning_content: '',
-      timestamp: Date.now(),
-    };
-
-    let toolCalls: ToolCall[] = [];
-    let finished = false;
-
-    for await (const chunk of stream) {
-      this.throwIfAborted(abortSignal);
-      const choices = chunk.choices;
-      const delta = choices?.[0]?.delta;
-
-      if (typeof chunk.id === 'string' && chunk.id.trim().length > 0) {
-        assistantMessage.metadata = {
-          ...assistantMessage.metadata,
-          responseId: chunk.id,
-        };
-      }
-
-      if (chunk.usage) {
-        assistantMessage.usage = chunk.usage;
-      }
-
-      if (finished) {
-        continue;
-      }
-
-      if (typeof delta?.content === 'string') {
-        assistantMessage.content = `${assistantMessage.content}${delta.content}`;
-
-        yield {
-          type: 'chunk',
-          data: {
-            messageId: assistantMessage.messageId,
-            content: delta.content,
-            delta: true,
-          },
-        };
-      }
-
-      if (typeof delta?.reasoning_content === 'string') {
-        const currentReasoning = assistantMessage.reasoning_content;
-        assistantMessage.reasoning_content = `${currentReasoning || ''}${delta.reasoning_content}`;
-
-        yield {
-          type: 'reasoning_chunk',
-          data: {
-            messageId: assistantMessage.messageId,
-            reasoningContent: delta.reasoning_content,
-            delta: true,
-          },
-        };
-      }
-
-      if (delta?.tool_calls) {
-        toolCalls = await this.mergeToolCalls(
-          toolCalls,
-          delta.tool_calls,
-          assistantMessage.messageId,
-          executionId,
-          stepIndex,
-          writeBufferSessions
-        );
-
-        yield {
-          type: 'tool_call',
-          data: {
-            messageId: assistantMessage.messageId,
-            toolCalls,
-          },
-        };
-      }
-
-      const finishReason =
-        choices?.[0]?.finish_reason ||
-        (delta as { finish_reason?: string } | undefined)?.finish_reason;
-      if (finishReason) {
-        finished = true;
-      }
-    }
-
-    assistantMessage.tool_calls = toolCalls.length > 0 ? toolCalls : undefined;
-    assistantMessage.type = toolCalls.length > 0 ? 'tool-call' : 'assistant-text';
-    assistantMessage.metadata = {
-      ...assistantMessage.metadata,
-      llmRequestConfigHash: requestPlan.requestConfigHash,
-      llmRequestInputHash: requestPlan.requestInputHash,
-      llmRequestInputMessageCount: requestPlan.requestInputMessageCount,
-      continuationMode: requestPlan.continuationMode,
-      continuationDeltaMessageCount: requestPlan.continuationDeltaMessageCount,
-      ...(requestPlan.previousResponseIdUsed
-        ? {
-            previousResponseIdUsed: requestPlan.previousResponseIdUsed,
-            continuationBaselineMessageCount: requestPlan.continuationBaselineMessageCount,
-          }
-        : {}),
-    };
-    assistantMessage.metadata = {
-      ...assistantMessage.metadata,
-      llmResponseMessageHash: hashValueForContinuation(
-        this.convertMessageToLLMMessage(assistantMessage)
-      ),
-    };
-
-    const hasAssistantText = hasNonEmptyText(assistantMessage.content);
-    const hasReasoningText = hasNonEmptyText(assistantMessage.reasoning_content);
-    if (toolCalls.length === 0 && !hasAssistantText && !hasReasoningText) {
-      throw new AgentUpstreamRetryableError('LLM returned an empty assistant response');
-    }
-
-    return { assistantMessage, toolCalls };
-  }
-
-  private async *executeTool(
-    toolCall: ToolCall,
-    stepIndex: number,
-    callbacks?: AgentCallbacks,
-    abortSignal?: AbortSignal,
-    executionId?: string,
-    traceId?: string,
-    parentSpanId?: string,
-    writeBufferSessions: Map<string, WriteBufferRuntime> = new Map()
-  ): AsyncGenerator<StreamEvent, Message, unknown> {
-    this.throwIfAborted(abortSignal);
-    const effectiveTraceId = traceId || executionId || generateId('trace_');
-    const toolSpan = await this.startSpan(
-      callbacks,
-      effectiveTraceId,
-      'agent.tool.execute',
-      parentSpanId,
-      {
-        executionId,
-        stepIndex,
-        toolCallId: toolCall.id,
-        toolName: toolCall.function.name,
-      }
-    );
-    let toolErrorCode: string | undefined;
-    let cachedHit = false;
-    let toolSucceeded = false;
-    try {
-      const writeFileSessionKey = createWriteFileSessionKey({
-        executionId,
-        stepIndex,
-        toolCallId: toolCall.id,
-      });
-
-      const ledgerResult = await executeWithToolLedger({
-        ledger: this.toolExecutionLedger,
-        executionId,
-        toolCallId: toolCall.id,
-        execute: async () => {
-          const toolExecResult = await this.toolExecutor.execute(toolCall, {
-            onChunk: (chunk) => {
-              this.emit('tool_chunk', {
-                toolCallId: toolCall.id,
-                toolName: toolCall.function.name,
-                arguments: toolCall.function.arguments,
-                chunk: chunk.data,
-                chunkType: chunk.type,
-              });
-            },
-            onConfirm: async (info) => {
-              return new Promise((resolve) => {
-                let settled = false;
-                const abortHandler = () => {
-                  if (!settled) {
-                    settled = true;
-                    resolve({ approved: false, message: ABORTED_MESSAGE });
-                  }
-                };
-
-                const cleanup = () => {
-                  if (!settled) {
-                    settled = true;
-                  }
-                  abortSignal?.removeEventListener('abort', abortHandler);
-                };
-
-                if (abortSignal?.aborted) {
-                  abortHandler();
-                  return;
-                }
-                abortSignal?.addEventListener('abort', abortHandler, { once: true });
-
-                this.emit('tool_confirm', {
-                  ...info,
-                  resolve: (decision: ToolDecision) => {
-                    cleanup();
-                    resolve(decision);
-                  },
-                });
-              });
-            },
-            onPolicyCheck: callbacks?.onToolPolicy
-              ? async (info) => {
-                  const decision = await callbacks.onToolPolicy?.(info);
-                  return decision || { allowed: true };
-                }
-              : undefined,
-            toolCallId: toolCall.id,
-            loopIndex: stepIndex,
-            agent: this,
-            toolAbortSignal: abortSignal,
-          });
-
-          let toolOutput = '';
-          let toolSummary = '';
-          let errorCode: string | undefined;
-
-          if (toolExecResult.success) {
-            toolOutput = toolExecResult.output || '';
-            await cleanupWriteFileBufferSession(toolCall, writeBufferSessions, writeFileSessionKey);
-          } else {
-            if (isWriteFileTool(toolCall)) {
-              if (isWriteFileProtocolResponse(toolExecResult.output)) {
-                toolOutput = toolExecResult.output;
-              } else if (needEnrichWriteFileFailure(toolExecResult.error, toolExecResult.output)) {
-                const errorContent =
-                  toolExecResult.error?.message ||
-                  toolExecResult.output ||
-                  new UnknownError().message;
-                toolOutput = await buildWriteFileToolErrorPayload(
-                  toolCall,
-                  errorContent,
-                  writeBufferSessions,
-                  writeFileSessionKey
-                );
-              } else {
-                toolOutput =
-                  toolExecResult.error?.message ||
-                  toolExecResult.output ||
-                  new UnknownError().message;
-              }
-            } else {
-              toolOutput =
-                toolExecResult.error?.message ||
-                toolExecResult.output ||
-                new UnknownError().message;
-            }
-            errorCode = this.extractErrorCode(toolExecResult.error) || 'TOOL_EXECUTION_FAILED';
-          }
-
-          toolSummary = this.resolveToolResultSummary(toolCall, toolExecResult, toolOutput);
-
-          return {
-            success: toolExecResult.success,
-            output: toolOutput,
-            summary: toolSummary,
-            payload: toolExecResult.payload,
-            metadata: toolExecResult.metadata,
-            errorName: toolExecResult.error?.name,
-            errorMessage: toolExecResult.error?.message,
-            errorCode,
-            recordedAt: Date.now(),
-          };
-        },
-        onError: (error) => {
-          this.logError('[Agent] Failed to execute tool with ledger:', error, {
-            executionId,
-            stepIndex,
-            toolCallId: toolCall.id,
-          });
-        },
-      });
-
-      cachedHit = ledgerResult.fromCache;
-      toolSucceeded = ledgerResult.record.success;
-      toolErrorCode = ledgerResult.record.errorCode;
-
-      const replayResult = this.createToolResultMessageFromLedger(toolCall.id, ledgerResult.record);
-      await this.safeCallback(callbacks?.onMessage, replayResult);
-
-      yield {
-        type: 'tool_result',
-        data: replayResult,
-      };
-
-      return replayResult;
-    } catch (error) {
-      toolErrorCode = this.extractErrorCode(error) || 'TOOL_EXECUTION_FAILED';
-      throw error;
-    } finally {
-      const toolLatencyMs = Date.now() - toolSpan.startedAt;
-      await this.emitMetric(callbacks, {
-        name: 'agent.tool.duration_ms',
-        value: toolLatencyMs,
-        unit: 'ms',
-        timestamp: Date.now(),
-        tags: {
-          executionId: executionId || '',
-          stepIndex,
-          toolCallId: toolCall.id,
-          cached: cachedHit ? 'true' : 'false',
-          success: toolSucceeded ? 'true' : 'false',
-        },
-      });
-      await this.endSpan(callbacks, toolSpan, {
-        executionId,
-        stepIndex,
-        toolCallId: toolCall.id,
-        toolName: toolCall.function.name,
-        latencyMs: toolLatencyMs,
-        cached: cachedHit,
-        errorCode: toolErrorCode,
-      });
-      this.logInfo('[Agent] tool.execute', {
-        executionId,
-        traceId: effectiveTraceId,
-        spanId: toolSpan.spanId,
-        parentSpanId: toolSpan.parentSpanId,
-        stepIndex,
-        toolCallId: toolCall.id,
-        toolName: toolCall.function.name,
-        latencyMs: toolLatencyMs,
-        cached: cachedHit,
-        errorCode: toolErrorCode,
-      });
-    }
-  }
-
-  private async *processToolCalls(
-    toolCalls: ToolCall[],
-    messages: Message[],
-    stepIndex: number,
-    callbacks?: AgentCallbacks,
-    abortSignal?: AbortSignal,
-    executionId?: string,
-    traceId?: string,
-    parentSpanId?: string,
-    writeBufferSessions: Map<string, WriteBufferRuntime> = new Map()
-  ): AsyncGenerator<StreamEvent, Message, unknown> {
-    if (this.config.maxConcurrentToolCalls <= 1 || toolCalls.length <= 1) {
-      for (const toolCall of toolCalls) {
-        this.throwIfAborted(abortSignal);
-        yield* this.emitProgress(executionId, stepIndex, 'tool', messages.length);
-
-        const toolGen = this.executeTool(
-          toolCall,
-          stepIndex,
-          callbacks,
-          abortSignal,
-          executionId,
-          traceId,
-          parentSpanId,
-          writeBufferSessions
-        );
-        let resultMessage: Message | undefined;
-        for (;;) {
-          const next = await toolGen.next();
-          if (next.done) {
-            resultMessage = next.value;
-            break;
-          }
-          yield next.value as StreamEvent;
-        }
-
-        if (resultMessage) {
-          messages.push(resultMessage);
-        }
-      }
-
-      const lastMessage = messages[messages.length - 1];
-      return lastMessage;
-    }
-
-    const plans = toolCalls.map((toolCall) => ({
-      toolCall,
-      policy: this.resolveToolConcurrencyPolicy(toolCall),
-    }));
-
-    for (let i = 0; i < plans.length; i++) {
-      this.throwIfAborted(abortSignal);
-      yield* this.emitProgress(executionId, stepIndex, 'tool', messages.length);
-    }
-
-    const waves = this.buildExecutionWaves(plans);
-    const allResults: Array<{ events: StreamEvent[]; message?: Message }> = [];
-    for (const wave of waves) {
-      this.throwIfAborted(abortSignal);
-      if (wave.type === 'exclusive') {
-        allResults.push(
-          await this.executeToolTask(
-            wave.plans[0].toolCall,
-            stepIndex,
-            callbacks,
-            abortSignal,
-            executionId,
-            traceId,
-            parentSpanId,
-            writeBufferSessions
-          )
-        );
-        continue;
-      }
-
-      const parallelResults = await this.runParallelWave(
-        wave.plans,
-        stepIndex,
-        callbacks,
-        abortSignal,
-        executionId,
-        traceId,
-        parentSpanId,
-        writeBufferSessions
-      );
-      allResults.push(...parallelResults);
-    }
-
-    for (const taskResult of allResults) {
-      for (const event of taskResult.events) {
-        yield event;
-      }
-      if (taskResult.message) {
-        messages.push(taskResult.message);
-      }
-      this.throwIfAborted(abortSignal);
-    }
-
-    const lastMessage = messages[messages.length - 1];
-    return lastMessage;
-  }
-
-  private resolveToolConcurrencyPolicy(toolCall: ToolCall): ToolConcurrencyPolicy {
-    if (this.config.toolConcurrencyPolicyResolver) {
-      return this.config.toolConcurrencyPolicyResolver(toolCall);
-    }
-
-    const manager = this.toolExecutor as ToolManager & {
-      getConcurrencyPolicy?: (call: ToolCall) => ToolConcurrencyPolicy;
-    };
-    if (typeof manager.getConcurrencyPolicy === 'function') {
-      return manager.getConcurrencyPolicy(toolCall);
-    }
-
-    return { mode: 'exclusive' };
-  }
-
-  private buildExecutionWaves(
-    plans: Array<{ toolCall: ToolCall; policy: ToolConcurrencyPolicy }>
-  ): Array<{
-    type: 'exclusive' | 'parallel';
-    plans: Array<{ toolCall: ToolCall; policy: ToolConcurrencyPolicy }>;
-  }> {
-    return buildToolExecutionWaves(plans);
-  }
-
-  private async runParallelWave(
-    plans: Array<{ toolCall: ToolCall; policy: ToolConcurrencyPolicy }>,
-    stepIndex: number,
-    callbacks?: AgentCallbacks,
-    abortSignal?: AbortSignal,
-    executionId?: string,
-    traceId?: string,
-    parentSpanId?: string,
-    writeBufferSessions: Map<string, WriteBufferRuntime> = new Map()
-  ): Promise<Array<{ events: StreamEvent[]; message?: Message }>> {
-    const tasks = plans.map((plan) => ({
-      lockKey: plan.policy.lockKey,
-      run: async () =>
-        this.executeToolTask(
-          plan.toolCall,
-          stepIndex,
-          callbacks,
-          abortSignal,
-          executionId,
-          traceId,
-          parentSpanId,
-          writeBufferSessions
-        ),
-    }));
-    return this.runWithConcurrencyAndLock(tasks, this.config.maxConcurrentToolCalls);
-  }
-
-  private async executeToolTask(
-    toolCall: ToolCall,
-    stepIndex: number,
-    callbacks?: AgentCallbacks,
-    abortSignal?: AbortSignal,
-    executionId?: string,
-    traceId?: string,
-    parentSpanId?: string,
-    writeBufferSessions: Map<string, WriteBufferRuntime> = new Map()
-  ): Promise<{ events: StreamEvent[]; message?: Message }> {
-    const events: StreamEvent[] = [];
-    const toolGen = this.executeTool(
-      toolCall,
-      stepIndex,
-      callbacks,
-      abortSignal,
-      executionId,
-      traceId,
-      parentSpanId,
-      writeBufferSessions
-    );
-    let resultMessage: Message | undefined;
-    for (;;) {
-      const next = await toolGen.next();
-      if (next.done) {
-        resultMessage = next.value;
-        break;
-      }
-      events.push(next.value as StreamEvent);
-    }
-    return {
-      events,
-      message: resultMessage,
-    };
-  }
-
-  private async runWithConcurrencyAndLock<T>(
-    tasks: Array<{ lockKey?: string; run: () => Promise<T> }>,
-    limit: number
-  ): Promise<T[]> {
-    return runTasksWithConcurrencyAndLock(tasks, limit);
-  }
-
-  private async *yieldCheckpoint(
-    executionId: string | undefined,
-    stepIndex: number,
-    lastMessage: Message | undefined,
-    callbacks?: AgentCallbacks
-  ): AsyncGenerator<StreamEvent, void, unknown> {
-    const checkpoint = createCheckpoint(executionId, stepIndex, lastMessage?.messageId);
-    await this.safeCallback(callbacks?.onCheckpoint, checkpoint);
-
-    yield {
-      type: 'checkpoint',
-      data: checkpoint,
-    };
-  }
-
-  private *yieldMaxRetriesError(): Generator<StreamEvent> {
-    yield* this.yieldErrorEvent(new MaxRetriesError());
-  }
-
-  private *emitProgress(
-    executionId: string | undefined,
-    stepIndex: number,
-    currentAction: 'llm' | 'tool',
-    messageCount: number
-  ): Generator<StreamEvent> {
-    yield createProgressEvent(executionId, stepIndex, currentAction, messageCount);
-  }
-
-  private *yieldErrorEvent(error: AgentError): Generator<StreamEvent> {
-    yield createErrorEvent(error);
-  }
-
-  private *yieldDoneEvent(
-    stepIndex: number,
-    finishReason: 'stop' | 'max_steps' = 'stop'
-  ): Generator<StreamEvent> {
-    yield createDoneEvent(stepIndex, finishReason);
-  }
-
-  private mergeLLMConfig(
-    config: AgentInput['config'],
-    tools?: AgentInput['tools'],
-    abortSignal?: AbortSignal,
-    conversationId?: string
-  ): AgentInput['config'] {
-    const merged = mergeLLMRequestConfig(config, tools, abortSignal);
-    if (
-      typeof conversationId !== 'string' ||
-      conversationId.trim().length === 0 ||
-      merged?.prompt_cache_key
-    ) {
-      return merged;
-    }
-
-    // Use the conversation id as the default sticky cache routing key so
-    // repeated full replays can still hit provider-side prefix caching.
-    return {
-      ...(merged || {}),
-      prompt_cache_key: conversationId,
-    };
-  }
-
-  private resolveLLMTools(inputTools?: Tool[]): Tool[] | undefined {
-    if (typeof inputTools !== 'undefined') {
-      return inputTools;
-    }
-
-    const manager = this.toolExecutor as ToolManager & {
-      getTools?: () => Array<{ toToolSchema?: () => unknown }>;
-    };
-    if (typeof manager.getTools !== 'function') {
-      return undefined;
-    }
-
-    const schemas: Tool[] = [];
-    for (const tool of manager.getTools()) {
-      if (typeof tool.toToolSchema !== 'function') {
-        continue;
-      }
-      const schema = tool.toToolSchema();
-      schemas.push({
-        type: schema.type,
-        function: {
-          name: schema.function.name,
-          description: schema.function.description,
-          parameters: (schema.function.parameters as Record<string, unknown> | undefined) || {},
-        },
-      });
-    }
-
-    return schemas.length > 0 ? schemas : undefined;
-  }
-
-  private async emitMetric(
-    callbacks: AgentCallbacks | undefined,
-    metric: Parameters<typeof pushMetric>[1]
-  ): Promise<void> {
-    await pushMetric(callbacks, metric, this.safeCallback.bind(this));
-  }
-
-  private async emitTrace(
-    callbacks: AgentCallbacks | undefined,
-    event: Parameters<typeof pushTrace>[1]
-  ): Promise<void> {
-    await pushTrace(callbacks, event, this.safeCallback.bind(this));
-  }
-
-  private async startSpan(
-    callbacks: AgentCallbacks | undefined,
-    traceId: string,
-    name: string,
-    parentSpanId?: string,
-    attributes?: Record<string, unknown>
-  ): Promise<SpanRuntime> {
-    return beginSpan({
-      callbacks,
-      traceId,
-      name,
-      parentSpanId,
-      attributes,
-      createSpanId: () => generateId('span_'),
-      emitTrace: async (cbs, event) => {
-        await this.emitTrace(cbs, event);
-      },
-    });
-  }
-
-  private async endSpan(
-    callbacks: AgentCallbacks | undefined,
-    span: SpanRuntime,
-    attributes?: Record<string, unknown>
-  ): Promise<void> {
-    await finishSpan({
-      callbacks,
-      span,
-      attributes,
-      emitTrace: async (cbs, event) => {
-        await this.emitTrace(cbs, event);
-      },
-    });
-  }
-
-  private extractErrorCode(error: unknown): string | undefined {
-    return parseErrorCode(error);
-  }
-
-  private createTimeoutBudgetState(input: AgentInput): TimeoutBudgetState | undefined {
-    return createBudgetState({
-      inputTimeoutBudgetMs: input.timeoutBudgetMs,
-      configTimeoutBudgetMs: this.config.timeoutBudgetMs,
-      inputLlmTimeoutRatio: input.llmTimeoutRatio,
-      configLlmTimeoutRatio: this.config.llmTimeoutRatio,
-    });
-  }
-
-  private createExecutionAbortScope(
-    inputAbortSignal: AbortSignal | undefined,
-    timeoutBudget: TimeoutBudgetState | undefined
-  ): AbortScope {
-    return createExecutionBudgetScope(inputAbortSignal, timeoutBudget);
-  }
-
-  private createStageAbortScope(
-    baseSignal: AbortSignal | undefined,
-    timeoutBudget: TimeoutBudgetState | undefined,
-    stage: TimeoutStage
-  ): AbortScope {
-    return createStageBudgetScope(baseSignal, timeoutBudget, stage);
-  }
-
-  private timeoutBudgetErrorFromSignal(
-    signal: AbortSignal | undefined
-  ): TimeoutBudgetExceededError | undefined {
-    return timeoutErrorFromAbortSignal(signal);
-  }
-
-  private normalizeTimeoutBudgetError(
-    error: unknown,
-    signal: AbortSignal | undefined
-  ): TimeoutBudgetExceededError | undefined {
-    return normalizeAbortTimeoutBudgetError(error, signal);
-  }
-
-  private throwIfAborted(signal?: AbortSignal): void {
-    assertNotAborted(signal, ABORTED_MESSAGE);
-  }
-
-  private isAbortError(error: unknown): boolean {
-    return isAbortErrorByMessage(error, ABORTED_MESSAGE);
-  }
-
-  private normalizeError(error: unknown): AgentError {
-    return normalizeAgentError(error, ABORTED_MESSAGE);
-  }
-
-  private calculateRetryDelay(retryCount: number, error: Error): number {
-    return calculateRetryDelayWithBackoff(retryCount, error, this.config.backoffConfig);
-  }
-
-  private async sleep(ms: number, signal?: AbortSignal): Promise<void> {
-    await sleepWithAbort(ms, signal, ABORTED_MESSAGE);
-  }
-
-  private logError(message: string, error: unknown, context?: Record<string, unknown>): void {
-    writeErrorLog(this.logger, message, error, context);
-  }
-
-  private logInfo(message: string, context?: Record<string, unknown>, data?: unknown): void {
-    writeInfoLog(this.logger, message, context, data);
-  }
-
-  private logWarn(message: string, context?: Record<string, unknown>, data?: unknown): void {
-    writeWarnLog(this.logger, message, context, data);
-  }
-
-  private resolveToolResultSummary(
-    toolCall: ToolCall,
-    toolResult: ToolResult,
-    toolOutput: string
-  ): string {
-    if (hasNonEmptyText(toolResult.summary)) {
-      return toolResult.summary;
-    }
-
-    const toolName = toolCall.function.name;
-    const subject = toolName === 'bash' ? 'Command' : toolName;
-
-    if (toolResult.success) {
-      if (hasNonEmptyText(toolOutput)) {
-        return `${subject} completed successfully.`;
-      }
-      return `${subject} completed successfully with no output.`;
-    }
-
-    const errorMessage =
-      toolResult.error?.message || (hasNonEmptyText(toolOutput) ? toolOutput : undefined);
-    if (errorMessage) {
-      return `${subject} failed: ${errorMessage}`;
-    }
-    return `${subject} failed.`;
-  }
-
-  private buildToolResultMetadata(
-    record: ToolExecutionLedgerRecord
-  ): Record<string, unknown> | undefined {
-    const error: Record<string, unknown> = {};
-    if (record.errorName) {
-      error.name = record.errorName;
-    }
-    if (record.errorMessage) {
-      error.message = record.errorMessage;
-    }
-    if (record.errorCode) {
-      error.code = record.errorCode;
-    }
-
-    const toolResult: Record<string, unknown> = {
-      success: record.success,
-      summary: record.summary,
-    };
-    if (hasNonEmptyText(record.output)) {
-      toolResult.output = record.output;
-    }
-    if (record.payload !== undefined) {
-      toolResult.payload = record.payload;
-    }
-    if (record.metadata && Object.keys(record.metadata).length > 0) {
-      toolResult.metadata = record.metadata;
-    }
-    if (Object.keys(error).length > 0) {
-      toolResult.error = error;
-    }
-
-    return {
-      toolResult,
-    };
-  }
-
-  private createToolResultMessageFromLedger(
-    toolCallId: string,
-    record: ToolExecutionLedgerRecord
-  ): Message {
-    return buildToolResultMessage({
-      toolCallId,
-      content: hasNonEmptyText(record.output) ? record.output : record.summary,
-      metadata: this.buildToolResultMetadata(record),
-      createMessageId: () => generateId('msg_'),
-    });
-  }
-}