savant-code 0.0.19 → 0.0.21

package/sdk/src/run.ts

@@ -1,1222 +0,0 @@
-import path from 'path'
-
-import { callMainPrompt } from '@savant-code/agent-runtime/main-prompt'
-import {
-  buildUserMessageContent,
-  withSystemTags,
-} from '@savant-code/agent-runtime/util/messages'
-import { MAX_AGENT_STEPS_DEFAULT } from '@savant-code/common/constants/agents'
-import {
-  COMPOSIO_META_TOOL_NAMES,
-  isComposioMetaToolName,
-} from '@savant-code/common/constants/composio'
-import { toOptionalFile } from '@savant-code/common/constants/paths'
-import {
-  getMCPClient,
-  listMCPTools,
-  callMCPTool,
-} from '@savant-code/common/mcp/client'
-import { toolNames } from '@savant-code/common/tools/constants'
-import { clientToolCallSchema } from '@savant-code/common/tools/list'
-import { applyPatchOperationSchema } from '@savant-code/common/tools/params/tool/apply-patch'
-import {
-  jsonObjectSchema,
-  type JSONValue,
-} from '@savant-code/common/types/json'
-import { AgentOutputSchema } from '@savant-code/common/types/session-state'
-import {
-  FETCH_IDLE_TIMEOUT_USER_MESSAGE,
-  TRANSIENT_NETWORK_ERROR_USER_MESSAGE,
-  extractApiErrorDetails,
-  isFetchIdleTimeoutError,
-  isTransientNetworkError,
-} from '@savant-code/common/util/error'
-import {
-  getOptionalNumber,
-  getOptionalString,
-  getString,
-} from '@savant-code/common/util/param-helpers'
-import { toJSONValue } from '@savant-code/common/util/type-narrowing'
-import { cloneDeep } from 'lodash'
-
-import { executeComposioToolViaServer } from './composio'
-import { getErrorStatusCode } from './error-utils'
-import { getAgentRuntimeImpl } from './impl/agent-runtime'
-import { getUserInfoFromApiKey } from './impl/database'
-import { initialSessionState, applyOverridesToSessionState } from './run-state'
-import { applyPatchTool } from './tools/apply-patch'
-import {
-  changeFile,
-  FileChangeSchema,
-  type OnFileWrittenCallback,
-} from './tools/change-file'
-import { codeSearch } from './tools/code-search'
-import { glob } from './tools/glob'
-import { listDirectory } from './tools/list-directory'
-import { getProjectPathLookupKeys } from './tools/path-utils'
-import { getFiles } from './tools/read-files'
-import { readUrl } from './tools/read-url'
-import { runTerminalCommand } from './tools/run-terminal-command'
-
-import type { CustomToolDefinition } from './custom-tool'
-import type { RunState } from './run-state'
-import type { FileFilter } from './tools/read-files'
-import type { ServerAction } from '@savant-code/common/actions'
-import type { AgentDefinition } from '@savant-code/common/templates/initial-agents-dir/types/agent-definition'
-import type { ToolName } from '@savant-code/common/tools/constants'
-import type { PublishedClientToolName } from '@savant-code/common/tools/list'
-import type { Logger } from '@savant-code/common/types/contracts/logger'
-import type { TraceWriter } from '@savant-code/common/types/contracts/trace'
-import type { SavantCodeFileSystem } from '@savant-code/common/types/filesystem'
-import type {
-  ImagePart,
-  TextPart,
-  ToolResultOutput,
-} from '@savant-code/common/types/messages/content-part'
-import type { ToolMessage } from '@savant-code/common/types/messages/savant-code-message'
-import type { PrintModeEvent } from '@savant-code/common/types/print-mode'
-import type { SessionState } from '@savant-code/common/types/session-state'
-import type { Source } from '@savant-code/common/types/source'
-import type { SavantCodeSpawn } from '@savant-code/common/types/spawn'
-
-/**
- * Wraps content for user messages, ensuring text is wrapped in <user_message> tags.
- * Uses buildUserMessageContent from agent-runtime for consistency.
- */
-const wrapContentForUserMessage = (
-  content?: (TextPart | ImagePart)[],
-): (TextPart | ImagePart)[] | undefined => {
-  if (!content || content.length === 0) {
-    return content
-  }
-  // Delegate to the shared utility which handles wrapping correctly
-  return buildUserMessageContent(undefined, undefined, content)
-}
-
-type OverrideToolHandlers = {
-  [K in PublishedClientToolName]?: (
-    input: Record<string, JSONValue>,
-  ) => Promise<ToolResultOutput[]>
-} & {
-  // Include read_files separately, since it has a different signature.
-  read_files?: (input: {
-    filePaths: string[]
-  }) => Promise<Record<string, string | null>>
-}
-
-function isRunPauseError<T>(
-  error: T,
-): error is T & { savantCode$1?: boolean; name?: string } {
-  if (!error || typeof error !== 'object') return false
-  const err = error as { savantCode$1?: unknown; name?: unknown }
-  return err.savantCode$1 === true || err.name === 'SavantCodeRunPausedError'
-}
-
-export type SavantCodeClientOptions = {
-  apiKey?: string
-
-  cwd?: string
-  /** Optional directory path to load skills from. Skills found here will be available to the `skill` tool. */
-  skillsDir?: string
-  projectFiles?: Record<string, string>
-  knowledgeFiles?: Record<string, string>
-  agentDefinitions?: AgentDefinition[]
-  maxAgentSteps?: number
-  env?: Record<string, string>
-
-  handleEvent?: (event: PrintModeEvent) => void | Promise<void>
-  handleStreamChunk?: (
-    chunk:
-      | string
-      | {
-          type: 'subagent_chunk'
-          agentId: string
-          agentType: string
-          chunk: string
-        }
-      | {
-          type: 'reasoning_chunk'
-          agentId: string
-          ancestorRunIds: string[]
-          chunk: string
-        },
-  ) => void | Promise<void>
-
-  /** Optional filter to classify files before reading (runs before gitignore check) */
-  fileFilter?: FileFilter
-
-  overrideTools?: OverrideToolHandlers
-  customToolDefinitions?: CustomToolDefinition[]
-
-  fsSource?: Source<SavantCodeFileSystem>
-  spawnSource?: Source<SavantCodeSpawn>
-  logger?: Logger
-  /** Optional debug trace of agent message histories. Called with the full
-   *  history at each agent step boundary; implementations should append each
-   *  message once (see TraceWriter). */
-  traceWriter?: TraceWriter
-}
-
-export type ImageContent = {
-  type: 'image'
-  image: string // base64 encoded
-  mediaType: string
-}
-
-export type TextContent = {
-  type: 'text'
-  text: string
-}
-
-export type MessageContent = TextContent | ImageContent
-
-export type RunOptions = {
-  agent: string | AgentDefinition
-  prompt: string
-  /** Content array for multimodal messages (text + images) */
-  content?: MessageContent[]
-  params?: Record<string, JSONValue>
-  previousRun?: RunState
-  extraToolResults?: ToolMessage[]
-  signal?: AbortSignal
-  /** Optional steering hook. Drained at each agent step boundary during the run;
-   * any returned texts are appended to the conversation as user prompts (and keep
-   * the turn going) before the next LLM call. Lets a host inject messages into a
-   * running agent without aborting — i.e. "steer" it, as opposed to queuing a new
-   * prompt for after the turn finishes. */
-  drainSteeringMessages?: () => string[]
-  /** Extra key/values merged into each LLM request's `savant_code_metadata`.
-   *  Used by hosts (e.g. the CLI) to forward client-scoped identifiers like
-   *  `savant_free_instance_id` that server-side gates read from the request body. */
-  extraSavantCodeMetadata?: Record<string, string>
-  /** Optional checkpoint hook. Called once when the run starts and then
-   *  periodically while it is in flight, with a RunState snapshot that
-   *  preserves all progress so far (the user's prompt plus any completed
-   *  agent steps, ending with an interruption note). Hosts can persist these
-   *  snapshots so that a killed process (closed terminal, crash) does not
-   *  lose the in-flight turn. The final resolved RunState supersedes any
-   *  snapshot; no snapshots are emitted after the run settles. */
-  onStateSnapshot?: (runState: RunState) => void
-  /** Optional file write hook. Called after a file is successfully written
-   *  (created or modified). Useful for tracking file changes, syncing to
-   *  databases, or triggering side effects. */
-  onFileWritten?: OnFileWrittenCallback
-  /** Dev override flag — bypasses all FSM tool gating and agent tool restrictions. */
-  devMode?: boolean
-  /** Optional sandbox permission mode. */
-  permissionMode?:
-    | 'safe'
-    | 'prompt'
-    | 'unsafe' /** Optional pre-formatted model metadata block injected into the agent
-   *   system prompt via the {SAVANT_CODE_MODEL_INFO} placeholder. */
-  modelInfoText?: string
-  /** FID-2026-0803-004: directory for persistent per-turn file checkpoints
-   *   (rewind). When set, the runtime captures pre-write snapshots of every
-   *   write_file/str_replace/apply_patch in each turn. Hosts own the turn
-   *   lifecycle via the checkpoint store (openTurn before run, closeTurn
-   *   after) and pass the same directory here. */
-  checkpointDir?: string
-  /** FID-2026-0803-004: turn identity used to group this run's checkpoint
-   *   captures. Defaults to the run's clientSessionId; hosts (e.g. the CLI)
-   *   pass their own id so they can open/close the matching turn. */
-  checkpointTurnId?: string
-}
-
-/** How often onStateSnapshot fires while a run is in flight. */
-const STATE_SNAPSHOT_INTERVAL_MS = 5_000
-
-export const STATE_SNAPSHOT_INTERRUPTION_MESSAGE =
-  'The session ended before this response completed. Partial progress has been preserved.'
-
-/**
- * Copy a SessionState for a checkpoint / cancellation snapshot: the caller
- * appends an interruption message and must not disturb the live session.
- *
- * lodash cloneDeep of the whole session is expensive — ~230ms on an ~8 MB
- * session — and this runs on the CLI's render/input thread every ~5s at each
- * in-flight snapshot, a major source of long-session freezes.
- *
- * Only mainAgentState needs an independent copy: the mutations that would
- * otherwise bleed into an already-captured snapshot all live there —
- * messageHistory (.push), agentContext subgoals (update_subgoal). We copy it
- * with a JSON round-trip, which is ~50x faster than cloneDeep (~4ms). The
- * snapshot is only ever consumed as JSON — persisted to disk, and re-serialized
- * when fed back as previousRunState — so a JSON round-trip is byte-for-byte
- * parity with the prior cloneDeep→JSON.stringify path. It also can't choke on
- * the URL / Buffer / Uint8Array instances the message schema permits in
- * image/file content (structuredClone throws on URL and rewrites
- * Buffer→Uint8Array; both change the persisted bytes or fall back).
- *
- * fileContext is large, effectively read-only during a run, and already
- * persisted as-is, so we share it by reference rather than copy it.
- *
- * Falls back to cloneDeep only if JSON.stringify throws (circular refs /
- * BigInt — which AgentState isn't expected to contain, as it uses IDs rather
- * than object back-refs) so a snapshot — or the final error state, which shares
- * this path — can never fail to build.
- */
-export function cloneSessionState(
-  state: SessionState,
-  logger?: Logger,
-): SessionState {
-  let mainAgentState: SessionState['mainAgentState']
-  try {
-    mainAgentState = JSON.parse(JSON.stringify(state.mainAgentState))
-  } catch (error) {
-    logger?.debug?.(
-      { error: error instanceof Error ? error.message : String(error) },
-      'JSON clone of mainAgentState failed; falling back to cloneDeep',
-    )
-    mainAgentState = cloneDeep(state.mainAgentState)
-  }
-  return { fileContext: state.fileContext, mainAgentState }
-}
-
-const createAbortError = (signal?: AbortSignal) => {
-  if (signal?.reason instanceof Error) {
-    return signal.reason
-  }
-  const error = new Error('Aborted')
-  error.name = 'AbortError'
-  return error
-}
-
-type RunExecutionOptions = RunOptions &
-  SavantCodeClientOptions & {
-    apiKey: string
-    fingerprintId: string
-  }
-type RunReturnType = RunState
-
-export async function run(options: RunExecutionOptions): Promise<RunState> {
-  const { signal } = options
-
-  if (signal?.aborted) {
-    const abortError = createAbortError(signal)
-    return {
-      // FID-2026-0802-008 D2: omit sessionState when there is no previous
-      // run — callers must not assume a session exists on pre-abort.
-      ...(options.previousRun?.sessionState
-        ? { sessionState: options.previousRun.sessionState }
-        : {}),
-      traceSessionId:
-        options.previousRun?.traceSessionId ?? crypto.randomUUID(),
-      output: {
-        type: 'error',
-        message: abortError.message,
-      },
-    }
-  }
-
-  return runOnce(options)
-}
-
-async function runOnce({
-  apiKey,
-  fingerprintId,
-
-  cwd,
-  skillsDir,
-  projectFiles,
-  knowledgeFiles,
-  agentDefinitions,
-  maxAgentSteps = MAX_AGENT_STEPS_DEFAULT,
-  env,
-
-  handleEvent,
-  handleStreamChunk,
-
-  fileFilter,
-  overrideTools,
-  customToolDefinitions,
-
-  fsSource = () => require('fs').promises,
-  spawnSource,
-  logger,
-  traceWriter,
-
-  agent,
-  prompt,
-  content,
-  params,
-  previousRun,
-  extraToolResults,
-  signal,
-  drainSteeringMessages,
-  extraSavantCodeMetadata,
-  onStateSnapshot,
-  onFileWritten,
-  devMode,
-  permissionMode,
-  modelInfoText,
-  checkpointDir,
-  checkpointTurnId,
-}: RunExecutionOptions): Promise<RunState> {
-  const fsSourceValue = typeof fsSource === 'function' ? fsSource() : fsSource
-  const fs = await fsSourceValue
-  let spawn: SavantCodeSpawn
-  if (spawnSource) {
-    const spawnSourceValue = await spawnSource
-    spawn = spawnSourceValue as SavantCodeSpawn
-  } else {
-    spawn = require('child_process').spawn as SavantCodeSpawn
-  }
-  const preparedContent = wrapContentForUserMessage(content)
-  let activeCustomToolDefinitions = customToolDefinitions ?? []
-
-  // Init session state
-  let agentId
-  if (typeof agent !== 'string') {
-    const clonedDefs = agentDefinitions ? cloneDeep(agentDefinitions) : []
-    agentDefinitions = [...clonedDefs, agent]
-    agentId = agent.id
-  } else {
-    agentId = agent
-  }
-  const traceSessionId = previousRun?.traceSessionId ?? crypto.randomUUID()
-
-  // FID-2026-0802-008 E2: setup failures resolve an error RunState instead of
-  // rejecting — the runtime error path already resolves output.error, so run()
-  // has a single error contract.
-  const errorRunStateFrom = (error: unknown) => {
-    const message = error instanceof Error ? error.message : String(error)
-    const statusCode = getErrorStatusCode(error)
-    return {
-      // sessionState deliberately omitted (RunState.sessionState is optional),
-      // matching the D2 pre-abort convention.
-      traceSessionId,
-      output: {
-        type: 'error' as const,
-        message,
-        ...(statusCode !== undefined && { statusCode }),
-      },
-    }
-  }
-
-  let sessionState: SessionState
-  try {
-    if (previousRun?.sessionState) {
-      // applyOverridesToSessionState handles deep cloning and applying any provided overrides
-      sessionState = await applyOverridesToSessionState(
-        cwd,
-        previousRun.sessionState,
-        {
-          knowledgeFiles,
-          agentDefinitions,
-          customToolDefinitions,
-          projectFiles,
-          maxAgentSteps,
-        },
-      )
-    } else {
-      // No previous run, so create a fresh session state
-      sessionState = await initialSessionState({
-        cwd,
-        skillsDir,
-        knowledgeFiles,
-        agentDefinitions,
-        customToolDefinitions,
-        projectFiles,
-        maxAgentSteps,
-        devMode,
-        fs,
-        spawn,
-        logger,
-      })
-    }
-  } catch (error) {
-    return errorRunStateFrom(error)
-  }
-
-  // Ensure devMode reflects the current CLI state (may have changed since last run)
-  if (devMode !== undefined) {
-    sessionState.fileContext.devMode = devMode
-  }
-  if (permissionMode !== undefined) {
-    sessionState.fileContext.permissionMode = permissionMode
-  }
-
-  for (const toolName of COMPOSIO_META_TOOL_NAMES) {
-    delete sessionState.fileContext.customToolDefinitions[toolName]
-  }
-
-  let resolvePromise: (
-    value: RunReturnType | PromiseLike<RunReturnType>,
-  ) => void = () => {}
-  let _reject: (error: Error) => void = () => {}
-  const promise = new Promise<RunReturnType>((res, rej) => {
-    resolvePromise = res
-    _reject = rej
-  })
-
-  // Snapshot support: stop emitting the moment the run settles so a late
-  // snapshot can never overwrite the final state persisted by the host.
-  let settled = false
-  let snapshotTimer: ReturnType<typeof setInterval> | null = null
-  const resolve = (value: RunReturnType) => {
-    settled = true
-    if (snapshotTimer !== null) {
-      clearInterval(snapshotTimer)
-      snapshotTimer = null
-    }
-    resolvePromise(value)
-  }
-
-  // FID-2026-0802-008 E1: event/stream handlers are dispatched fire-and-forget
-  // from sendAction, so a throwing handler (the default client handleEvent
-  // throws to force error visibility) would otherwise become an unhandled
-  // promise rejection — a process-crash risk. Route handler errors into the
-  // run promise instead; once the run has settled, rejections are dropped.
-  const rejectRunWithHandlerError = (error: unknown) => {
-    if (settled) return
-    _reject(error instanceof Error ? error : new Error(String(error)))
-  }
-  const safeDispatch = async (fn: () => void | Promise<void>) => {
-    try {
-      await fn()
-    } catch (error) {
-      logger?.debug?.(
-        {
-          error: error instanceof Error ? error.message : String(error),
-        },
-        'Event/stream handler threw; rejecting run',
-      )
-      rejectRunWithHandlerError(error)
-    }
-  }
-
-  async function onError(error: { message: string }) {
-    if (handleEvent) {
-      await safeDispatch(() =>
-        handleEvent({ type: 'error', message: error.message }),
-      )
-    }
-  }
-
-  // The agent runtime mutates sessionState.mainAgentState as it progresses,
-  // replacing messageHistory with a new array once it adds the user prompt.
-  // Comparing array identity detects progress more robustly than length:
-  // context pruning could shrink history below its starting length without
-  // meaning the runtime never ran.
-  let initialMessageHistory = sessionState.mainAgentState.messageHistory
-
-  /** Calculates the current session state if cancelled.
-   *
-   * This is used when callMainPrompt throws an error. If the agent runtime made
-   * any progress (replaced the shared messageHistory), those messages are
-   * preserved. Otherwise the user's message is added so it isn't lost.
-   */
-  function getCancelledSessionState(message: string): SessionState {
-    const runtimeMadeProgress =
-      sessionState.mainAgentState.messageHistory !== initialMessageHistory
-
-    const state = cloneSessionState(sessionState, logger)
-
-    // Only add the user's message if the runtime didn't get a chance to add it.
-    if (!runtimeMadeProgress && (prompt || preparedContent)) {
-      state.mainAgentState.messageHistory.push({
-        role: 'user' as const,
-        content: buildUserMessageContent(prompt, params, preparedContent),
-        tags: ['USER_PROMPT'] as string[],
-      })
-    }
-
-    // Add error context message
-    state.mainAgentState.messageHistory.push({
-      role: 'user' as const,
-      content: [{ type: 'text' as const, text: withSystemTags(message) }],
-    })
-    return state
-  }
-  function getCancelledRunState(message?: string): RunState {
-    message = message ?? 'Run cancelled by user.'
-    return {
-      sessionState: getCancelledSessionState(message),
-      traceSessionId,
-      output: {
-        type: 'error',
-        message,
-      },
-    }
-  }
-
-  const onResponseChunk = async (
-    action: ServerAction<'response-chunk'>,
-  ): Promise<void> => {
-    if (signal?.aborted) {
-      return
-    }
-    const { chunk } = action
-
-    if (typeof chunk !== 'string') {
-      if (chunk.type === 'reasoning_delta') {
-        await safeDispatch(() =>
-          handleStreamChunk?.({
-            type: 'reasoning_chunk',
-            chunk: chunk.text,
-            // The agent's stable id (matches subagent_start/subagent_chunk), so
-            // subagent reasoning attributes to the right agent. (Previously this
-            // forwarded runId, which no consumer's agent map is keyed by.)
-            agentId: chunk.agentId,
-            ancestorRunIds: chunk.ancestorRunIds,
-          }),
-        )
-      } else {
-        await safeDispatch(() => handleEvent?.(chunk))
-      }
-      return
-    }
-
-    if (handleStreamChunk) {
-      await safeDispatch(() => handleStreamChunk(chunk))
-    }
-  }
-  const onSubagentResponseChunk = async (
-    action: ServerAction<'subagent-response-chunk'>,
-  ) => {
-    if (signal?.aborted) {
-      return
-    }
-    const { agentId, agentType, chunk } = action
-
-    if (handleStreamChunk && chunk) {
-      await safeDispatch(() =>
-        handleStreamChunk({
-          type: 'subagent_chunk',
-          agentId,
-          agentType,
-          chunk,
-        }),
-      )
-    }
-  }
-
-  const agentRuntimeImpl = getAgentRuntimeImpl({
-    logger,
-    traceWriter,
-    apiKey,
-    handleStepsLogChunk: () => {
-      // Does nothing for now
-    },
-    requestToolCall: async ({ userInputId, toolName, input, mcpConfig }) => {
-      return handleToolCall({
-        action: {
-          type: 'tool-call-request',
-          requestId: crypto.randomUUID(),
-          userInputId,
-          toolName,
-          input,
-          timeout: undefined,
-          mcpConfig,
-        },
-        overrides: overrideTools ?? {},
-        customToolDefinitions: activeCustomToolDefinitions
-          ? Object.fromEntries(
-              activeCustomToolDefinitions.map((def) => [def.toolName, def]),
-            )
-          : {},
-        cwd,
-        fs,
-        env,
-        apiKey,
-        signal,
-        onFileWritten,
-      })
-    },
-    checkpointDir,
-    checkpointTurnId,
-    requestMcpToolData: async ({ mcpConfig, toolNames }) => {
-      const mcpClientId = await getMCPClient(mcpConfig)
-      const listToolsResult = await listMCPTools(mcpClientId)
-      const tools = listToolsResult.tools
-      const filteredTools = !toolNames
-        ? tools
-        : tools.filter((tool) => toolNames.includes(tool.name))
-
-      return filteredTools.map((tool) => ({
-        name: tool.name,
-        description:
-          typeof tool.description === 'string' ? tool.description : undefined,
-        inputSchema: toJSONValue(tool.inputSchema),
-      }))
-    },
-    requestFiles: ({ filePaths }) =>
-      readFiles({
-        filePaths,
-        override: overrideTools?.read_files,
-        fileFilter,
-        cwd,
-        fs,
-      }),
-    requestOptionalFile: async ({ filePath }) => {
-      const files = await readFiles({
-        filePaths: [filePath],
-        override: overrideTools?.read_files,
-        fileFilter,
-        cwd,
-        fs,
-      })
-      const lookupKeys = cwd
-        ? getProjectPathLookupKeys(cwd, filePath)
-        : [filePath]
-      const fileKey = lookupKeys.find((key) => key in files)
-      return toOptionalFile(fileKey === undefined ? null : files[fileKey]!)
-    },
-    sendAction: ({ action }) => {
-      if (action.type === 'action-error') {
-        onError({ message: action.message })
-        return
-      }
-      if (action.type === 'response-chunk') {
-        onResponseChunk(action)
-        return
-      }
-      if (action.type === 'subagent-response-chunk') {
-        onSubagentResponseChunk(action)
-        return
-      }
-      if (action.type === 'prompt-response') {
-        handlePromptResponse({
-          action,
-          resolve,
-          onError,
-          initialSessionState: sessionState,
-          traceSessionId,
-        })
-        return
-      }
-      if (action.type === 'prompt-error') {
-        handlePromptResponse({
-          action,
-          resolve,
-          onError,
-          initialSessionState: sessionState,
-          traceSessionId,
-        })
-        return
-      }
-    },
-    sendSubagentChunk: ({
-      userInputId,
-      agentId,
-      agentType,
-      chunk,
-      prompt,
-      forwardToPrompt = true,
-    }) => {
-      onSubagentResponseChunk({
-        type: 'subagent-response-chunk',
-        userInputId,
-        agentId,
-        agentType,
-        chunk,
-        prompt,
-        forwardToPrompt,
-      })
-    },
-  })
-
-  // FID-2026-0802-008 D3: crypto-grade id (was Math.random()).
-  const promptId = crypto.randomUUID()
-
-  // Send input
-  // FID-2026-0802-008 E2: auth failures (401/5xx from getUserInfoFromApiKey)
-  // resolve an error RunState rather than rejecting the run() promise.
-  let userId: string
-  try {
-    const userInfo = await getUserInfoFromApiKey({
-      ...agentRuntimeImpl,
-      apiKey,
-      fields: ['id'],
-    })
-    if (!userInfo) {
-      return getCancelledRunState('Invalid API key or user not found')
-    }
-    userId = userInfo.id
-  } catch (error) {
-    return errorRunStateFrom(error)
-  }
-
-  if (signal?.aborted) {
-    // Align with the pre-abort message in run() (FID-2026-0802-008 E2).
-    return getCancelledRunState(createAbortError(signal).message)
-  }
-
-  if (onStateSnapshot) {
-    // The runtime replaces mainAgentState.messageHistory with a new array at
-    // each step boundary, so reference identity is a cheap "has anything
-    // durable changed" check. Skipping unchanged ticks avoids deep-cloning a
-    // potentially multi-MB sessionState every interval while the run is just
-    // waiting on a slow LLM call.
-    let lastSnapshotHistory:
-      SessionState['mainAgentState']['messageHistory'] | null = null
-    const emitStateSnapshot = () => {
-      if (settled || signal?.aborted) {
-        return
-      }
-      const history = sessionState.mainAgentState.messageHistory
-      if (history === lastSnapshotHistory) {
-        return
-      }
-      lastSnapshotHistory = history
-      try {
-        onStateSnapshot(
-          getCancelledRunState(STATE_SNAPSHOT_INTERRUPTION_MESSAGE),
-        )
-      } catch (error) {
-        logger?.debug?.(
-          { error: error instanceof Error ? error.message : String(error) },
-          'onStateSnapshot handler threw',
-        )
-      }
-    }
-    // Emit immediately so the user's prompt is checkpointed as soon as the
-    // run starts, then keep checkpointing progress while it is in flight.
-    emitStateSnapshot()
-    snapshotTimer = setInterval(emitStateSnapshot, STATE_SNAPSHOT_INTERVAL_MS)
-    // Don't let the checkpoint timer keep the host process alive.
-    const nodeTimer = snapshotTimer as unknown as { unref?: () => void }
-    if (typeof nodeTimer.unref === 'function') {
-      nodeTimer.unref()
-    }
-  }
-
-  callMainPrompt({
-    ...agentRuntimeImpl,
-    promptId,
-    action: {
-      type: 'prompt',
-      promptId,
-      prompt,
-      promptParams: params,
-      content: preparedContent,
-      fingerprintId: fingerprintId,
-      sessionState,
-      toolResults: extraToolResults ?? [],
-      agentId,
-    },
-    drainSteeringMessages,
-    repoUrl: undefined,
-    repoId: undefined,
-    clientSessionId: promptId,
-    userId,
-    modelInfoText,
-    extraSavantCodeMetadata: {
-      ...(extraSavantCodeMetadata ?? {}),
-      trace_session_id: traceSessionId,
-    },
-    signal: signal ?? new AbortController().signal,
-  }).catch((error) => {
-    let errorMessage = isFetchIdleTimeoutError(error)
-      ? FETCH_IDLE_TIMEOUT_USER_MESSAGE
-      : isTransientNetworkError(error)
-        ? TRANSIENT_NETWORK_ERROR_USER_MESSAGE
-        : error instanceof Error
-          ? error.message
-          : String(error ?? '')
-    const apiErrorDetails = extractApiErrorDetails(error)
-    const statusCode = apiErrorDetails.statusCode ?? getErrorStatusCode(error)
-    const {
-      countryBlockReason,
-      countryCode,
-      errorCode,
-      ipPrivacySignals,
-      message: parsedMessage,
-    } = apiErrorDetails
-    if (parsedMessage) {
-      errorMessage = parsedMessage
-    }
-
-    resolve({
-      sessionState: getCancelledSessionState(errorMessage),
-      traceSessionId,
-      output: {
-        type: 'error',
-        message: errorMessage,
-        ...(statusCode !== undefined && { statusCode }),
-        ...(errorCode !== undefined && { error: errorCode }),
-        ...(countryCode !== undefined && { countryCode }),
-        ...(countryBlockReason !== undefined && { countryBlockReason }),
-        ...(ipPrivacySignals !== undefined && { ipPrivacySignals }),
-      },
-    })
-  })
-
-  return promise
-}
-
-function requireCwd(cwd: string | undefined, toolName: string): string {
-  if (!cwd) {
-    throw new Error(
-      `cwd is required for the ${toolName} tool. Please provide cwd in SavantCodeClientOptions or override the ${toolName} tool.`,
-    )
-  }
-  return cwd
-}
-
-async function readFiles({
-  filePaths,
-  override,
-  fileFilter,
-  cwd,
-  fs,
-}: {
-  filePaths: string[]
-  override?: NonNullable<
-    Required<SavantCodeClientOptions>['overrideTools']['read_files']
-  >
-  fileFilter?: FileFilter
-  cwd?: string
-  fs: SavantCodeFileSystem
-}) {
-  if (override) {
-    return await override({ filePaths })
-  }
-  return getFiles({
-    filePaths,
-    cwd: requireCwd(cwd, 'read_files'),
-    fs,
-    fileFilter,
-  })
-}
-
-async function handleToolCall({
-  action,
-  overrides,
-  customToolDefinitions,
-  cwd,
-  fs,
-  env,
-  apiKey,
-  signal,
-  onFileWritten,
-}: {
-  action: ServerAction<'tool-call-request'>
-  overrides: NonNullable<SavantCodeClientOptions['overrideTools']>
-  customToolDefinitions: Record<string, CustomToolDefinition>
-  cwd?: string
-  fs: SavantCodeFileSystem
-  env?: Record<string, string>
-  apiKey: string
-  signal?: AbortSignal
-  onFileWritten?: OnFileWrittenCallback
-}): Promise<{ output: ToolResultOutput[] }> {
-  const toolName = action.toolName
-  const input = action.input
-
-  if (signal?.aborted) {
-    return {
-      output: [
-        {
-          type: 'json',
-          value: {
-            message: 'Tool call cancelled: the run was aborted by the user.',
-          },
-        },
-      ],
-    }
-  }
-
-  // Handle MCP tool calls when mcpConfig is present
-  if (action.mcpConfig) {
-    try {
-      const mcpClientId = await getMCPClient(action.mcpConfig)
-      const result = await callMCPTool(
-        mcpClientId,
-        {
-          name: toolName,
-          arguments: input,
-        },
-        undefined,
-        signal ? { signal } : undefined,
-      )
-      return { output: result }
-    } catch (error) {
-      return {
-        output: [
-          {
-            type: 'json',
-            value: {
-              errorMessage:
-                error instanceof Error ? error.message : String(error),
-            },
-          },
-        ],
-      }
-    }
-  }
-
-  let result: ToolResultOutput[]
-  if (toolNames.includes(toolName as ToolName)) {
-    clientToolCallSchema.parse(action)
-  } else {
-    const customToolHandler = customToolDefinitions[toolName]
-
-    if (!customToolHandler) {
-      throw new Error(
-        `Custom tool handler not found for user input ID ${action.userInputId}`,
-      )
-    }
-    return {
-      output: await customToolHandler.execute(input),
-    }
-  }
-
-  try {
-    let override = overrides[toolName as PublishedClientToolName]
-    if (
-      !override &&
-      (toolName === 'str_replace' || toolName === 'apply_patch')
-    ) {
-      // Reuse the write_file override for file editing tools.
-      override = overrides['write_file']
-    }
-    if (override) {
-      result = await override(input)
-    } else if (toolName === 'end_turn') {
-      result = [{ type: 'json', value: { message: 'Turn ended.' } }]
-    } else if (toolName === 'write_file' || toolName === 'str_replace') {
-      FileChangeSchema.parse(input)
-      result = await changeFile({
-        parameters: input,
-        cwd: requireCwd(cwd, toolName),
-        fs,
-        onFileWritten,
-      })
-    } else if (toolName === 'apply_patch') {
-      applyPatchOperationSchema.parse(input.operation)
-      result = await applyPatchTool({
-        parameters: input,
-        cwd: requireCwd(cwd, toolName),
-        fs,
-        onFileWritten,
-      })
-    } else if (toolName === 'run_terminal_command') {
-      const resolvedCwd = requireCwd(cwd, 'run_terminal_command')
-      result = await runTerminalCommand({
-        command: getString(input, 'command'),
-        process_type: 'SYNC',
-        cwd: path.resolve(resolvedCwd, getOptionalString(input, 'cwd') ?? '.'),
-        timeout_seconds: getOptionalNumber(input, 'timeout_seconds') ?? 30,
-        env,
-        signal,
-      })
-    } else if (toolName === 'read_url') {
-      result = await readUrl({
-        url: getString(input, 'url'),
-        max_chars: getOptionalNumber(input, 'max_chars'),
-        signal,
-      })
-    } else if (toolName === 'code_search') {
-      result = await codeSearch({
-        projectPath: requireCwd(cwd, 'code_search'),
-        pattern: getString(input, 'pattern'),
-        flags: getOptionalString(input, 'flags'),
-        cwd: getOptionalString(input, 'cwd'),
-        maxResults: getOptionalNumber(input, 'maxResults'),
-        globalMaxResults: getOptionalNumber(input, 'globalMaxResults'),
-        maxOutputStringLength: getOptionalNumber(
-          input,
-          'maxOutputStringLength',
-        ),
-        timeoutSeconds: getOptionalNumber(input, 'timeoutSeconds'),
-        signal,
-      })
-    } else if (toolName === 'list_directory') {
-      result = await listDirectory({
-        directoryPath: getString(input, 'path'),
-        projectPath: requireCwd(cwd, 'list_directory'),
-        fs,
-      })
-    } else if (toolName === 'glob') {
-      result = await glob({
-        pattern: getString(input, 'pattern'),
-        projectPath: requireCwd(cwd, 'glob'),
-        cwd: getOptionalString(input, 'cwd'),
-        fs,
-      })
-    } else if (toolName === 'run_file_change_hooks') {
-      // No-op: SDK doesn't run file change hooks
-      result = [
-        {
-          type: 'json',
-          value: {
-            message: 'File change hooks are not supported in SDK mode',
-          },
-        },
-      ]
-    } else if (isComposioMetaToolName(toolName)) {
-      jsonObjectSchema.parse(input)
-      result = await executeComposioToolViaServer({
-        apiKey,
-        toolName,
-        input,
-      })
-    } else {
-      throw new Error(
-        `Tool not implemented in SDK. Please provide an override or modify your agent to not use this tool: ${toolName}`,
-      )
-    }
-  } catch (error) {
-    if (isRunPauseError(error)) {
-      throw error
-    }
-
-    result = [
-      {
-        type: 'json',
-        value: {
-          errorMessage:
-            error &&
-            typeof error === 'object' &&
-            'message' in error &&
-            typeof error.message === 'string'
-              ? error.message
-              : typeof error === 'string'
-                ? error
-                : 'Unknown error',
-        },
-      },
-    ]
-  }
-  return {
-    output: result,
-  }
-}
-
-/**
- * Extracts an HTTP status code from an error message string.
- * Parses common error patterns to identify the underlying status code.
- * Returns the status code if found, undefined otherwise.
- */
-export const extractStatusCodeFromMessage = (
-  errorMessage: string,
-): number | undefined => {
-  const lowerMessage = errorMessage.toLowerCase()
-
-  // AI SDK's built-in retry error (e.g., "Failed after 4 attempts. Last error: Service Unavailable")
-  // The AI SDK already retried 4 times, but we still want our SDK wrapper to retry 3 more times
-  if (
-    lowerMessage.includes('failed after') &&
-    lowerMessage.includes('attempts')
-  ) {
-    // Extract the underlying error type from the message
-    if (lowerMessage.includes('service unavailable')) {
-      return 503
-    }
-    if (lowerMessage.includes('timeout')) {
-      return 408
-    }
-    if (lowerMessage.includes('connection refused')) {
-      return 503
-    }
-    // Default to 500 for other AI SDK retry failures
-    return 500
-  }
-
-  if (
-    errorMessage.includes('503') ||
-    lowerMessage.includes('service unavailable')
-  ) {
-    return 503
-  }
-  if (errorMessage.includes('504')) {
-    return 504
-  }
-  if (errorMessage.includes('502')) {
-    return 502
-  }
-  if (lowerMessage.includes('timeout') || errorMessage.includes('408')) {
-    return 408
-  }
-  if (
-    lowerMessage.includes('econnrefused') ||
-    lowerMessage.includes('connection refused')
-  ) {
-    return 503
-  }
-  if (lowerMessage.includes('dns') || lowerMessage.includes('enotfound')) {
-    return 503
-  }
-  if (lowerMessage.includes('server error') || errorMessage.includes('500')) {
-    return 500
-  }
-  if (errorMessage.includes('429') || lowerMessage.includes('rate limit')) {
-    return 429
-  }
-  if (
-    lowerMessage.includes('network error') ||
-    lowerMessage.includes('fetch failed')
-  ) {
-    return 503
-  }
-
-  return undefined
-}
-
-async function handlePromptResponse({
-  action,
-  resolve,
-  onError,
-  initialSessionState,
-  traceSessionId,
-}: {
-  action: ServerAction<'prompt-response'> | ServerAction<'prompt-error'>
-  resolve: (value: RunReturnType) => void
-  onError: (error: { message: string }) => void
-  initialSessionState: SessionState
-  traceSessionId: string
-}) {
-  if (action.type === 'prompt-error') {
-    onError({ message: action.message })
-
-    const statusCode = extractStatusCodeFromMessage(action.message)
-    resolve({
-      sessionState: initialSessionState,
-      traceSessionId,
-      output: {
-        type: 'error',
-        message: action.message,
-        ...(statusCode !== undefined && { statusCode }),
-      },
-    })
-  } else if (action.type === 'prompt-response') {
-    // Stop enforcing session state schema! It's a black box we will pass back to the server.
-    // Only check the output schema.
-    const parsedOutput = AgentOutputSchema.safeParse(action.output)
-    if (!parsedOutput.success) {
-      const message = [
-        'Received invalid prompt response from server:',
-        JSON.stringify(parsedOutput.error.issues),
-        'If this issues persists, please contact support@savant-code.com',
-      ].join('\n')
-      onError({ message })
-      resolve({
-        sessionState: initialSessionState,
-        traceSessionId,
-        output: {
-          type: 'error',
-          message,
-        },
-      })
-      return
-    }
-    const { sessionState, output } = action
-
-    const state: RunState = {
-      sessionState,
-      traceSessionId,
-      output: output ?? {
-        type: 'error',
-        message: 'No output from agent',
-      },
-    }
-    resolve(state)
-  } else {
-    // FID-2026-0802-008 D4: keep the type-level exhaustiveness guard — if the
-    // action union ever grows, this branch fails to compile instead of
-    // silently leaving the run promise unsettled.
-    action satisfies never
-    throw new Error('Internal error: prompt response type not handled')
-  }
-}