⚙️ Query Engine & LLM API

Quando uma mensagem e enviada ao Claude Code, ela passa por quatro camadas distintas antes de chegar ao terminal do usuario:

QueryEngine e uma classe stateful instanciada uma vez por conversa. Ela mantem historico de mensagens mutavel, uso total de tokens, denials de permissao e o abort controller.

export class QueryEngine {
  private mutableMessages: Message[]
  private abortController: AbortController
  private totalUsage: NonNullableUsage
  private permissionDenials: SDKPermissionDenial[]

  // Turn-scoped: cleared at start of each submitMessage() call
  private discoveredSkillNames = new Set<string>()

  async *submitMessage(
    prompt: string | ContentBlockParam[],
    options?: { uuid?: string; isMeta?: boolean },
  ): AsyncGenerator<SDKMessage> {
    // 1. Build system prompt (fetchSystemPromptParts)
    // 2. processUserInput -- handles slash commands
    // 3. recordTranscript -- persists BEFORE the API call
    // 4. yield* query({ messages, ... })
    // 5. yield final result SDKMessage
  }
}

queryLoop() em query.ts e um while(true) carregando um objeto State tipado entre iteracoes:

type State = {
  messages: Message[]
  toolUseContext: ToolUseContext
  autoCompactTracking: AutoCompactTrackingState | undefined
  maxOutputTokensRecoveryCount: number
  hasAttemptedReactiveCompact: boolean
  maxOutputTokensOverride: number | undefined
  pendingToolUseSummary: Promise<ToolUseSummaryMessage | null> | undefined
  stopHookActive: boolean | undefined
  turnCount: number
  transition: Continue | undefined   // WHY we looped again
}

Continue Transitions -- Sete Razoes para Continuar o Loop

queryModel em claude.ts e um async function* que chama o endpoint de mensagens beta da Anthropic e re-yields cada evento de stream como um AssistantMessage ou StreamEvent interno.

for await (const message of deps.callModel({
  messages: prependUserContext(messagesForQuery, userContext),
  systemPrompt: fullSystemPrompt,
  thinkingConfig: toolUseContext.options.thinkingConfig,
  tools: toolUseContext.options.tools,
  signal: toolUseContext.abortController.signal,
  options: { model: currentModel, fallbackModel, ... },
})) {
  if (message.type === 'assistant') {
    assistantMessages.push(message)
    const toolBlocks = message.message.content
      .filter(b => b.type === 'tool_use')
    if (toolBlocks.length > 0) needsFollowUp = true
  }
  yield yieldMessage // surfaces to SDK caller / REPL
}

Streaming Tool Execution

Quando config.gates.streamingToolExecution esta habilitado, um StreamingToolExecutor inicia ferramentas enquanto o stream ainda esta aberto. Tools com inputs disponiveis comecam a executar em paralelo com o modelo ainda gerando texto, reduzindo latencia em turns com multiplas tools.

Toda API call passa por withRetry() em services/api/withRetry.ts. A funcao e um async function* com ate DEFAULT_MAX_RETRIES = 10 tentativas, yielding um SystemAPIErrorMessage antes de cada sleep para que usuarios vejam status updates em tempo real.

export function getRetryDelay(
  attempt: number,
  retryAfterHeader?: string | null,
  maxDelayMs = 32000,
): number {
  if (retryAfterHeader) {
    const seconds = parseInt(retryAfterHeader, 10)
    if (!isNaN(seconds)) return seconds * 1000
  }
  const baseDelay = Math.min(
    BASE_DELAY_MS * Math.pow(2, attempt - 1),
    maxDelayMs,
  )
  const jitter = Math.random() * 0.25 * baseDelay
  return baseDelay + jitter
}

Regras de Decisao de Retry

• 529 (overloaded): Apenas sources foreground fazem retry (usuario esta esperando). Sources background abortam imediatamente para evitar amplificar cascatas de capacidade.
• Opus fallback: Apos 3 erros 529 consecutivos em modelo Opus nao-custom, lanca FallbackTriggeredError que queryLoop captura e muda para fallbackModel.
• OAuth 401: Forca token refresh via handleOAuth401Error() antes da proxima tentativa.
• Context overflow 400: Parseia contagens de tokens da mensagem de erro e calcula novo maxTokensOverride.
• Persistent mode (UNATTENDED_RETRY): Retenta indefinidamente com cap de 30 minutos, yielding heartbeat messages a cada 30s.
• ECONNRESET/EPIPE: Socket keep-alive stale detectado; disableKeepAlive() chamado antes do retry.

Antes de cada API call, queryLoop executa um pipeline de estrategias de reducao de contexto em ordem fixa de prioridade:

// task_budget carryover across compaction (query.ts ~508)
if (params.taskBudget) {
  const preCompactContext =
    finalContextTokensFromLastResponse(messagesForQuery)
  taskBudgetRemaining = Math.max(
    0,
    (taskBudgetRemaining ?? params.taskBudget.total) - preCompactContext,
  )
}

Apos o modelo terminar (sem tool calls, sem recovery), o engine chama handleStopHooks() que executa tres categorias em ordem:

Fire-and-Forget Background Tasks

Ignorados em bare mode (-p). Disparados sem await em modo interativo:

if (!isBareMode()) {
  void executePromptSuggestion(stopHookContext)
  if (feature('EXTRACT_MEMORIES') && isExtractModeActive()) {
    void extractMemoriesModule!.executeExtractMemories(...)
  }
  if (!toolUseContext.agentId) {
    void executeAutoDream(...)
  }
}

query/tokenBudget.ts implementa auto-continue para o SDK path. Quando um budget por turno e configurado, o engine verifica apos cada stop limpo se o modelo "usou" budget suficiente.

const COMPLETION_THRESHOLD = 0.9   // 90% usado = feito
const DIMINISHING_THRESHOLD = 500  // <500 novos tokens = sem progresso

export function checkTokenBudget(
  tracker: BudgetTracker,
  agentId: string | undefined,
  budget: number | null,
  globalTurnTokens: number,
): TokenBudgetDecision {
  if (agentId || budget === null || budget <= 0) {
    return { action: 'stop', completionEvent: null }
  }
  const pct = Math.round((globalTurnTokens / budget) * 100)
  const isDiminishing =
    tracker.continuationCount >= 3 &&
    deltaSinceLastCheck < DIMINISHING_THRESHOLD &&
    tracker.lastDeltaTokens < DIMINISHING_THRESHOLD
  if (!isDiminishing && turnTokens < budget * COMPLETION_THRESHOLD) {
    return { action: 'continue', nudgeMessage: ... }
  }
  return { action: 'stop', ... }
}