Home

15. Deep Read: services/api/claude.ts

This File Is the Main Request Engine

If client.ts chooses how to connect, claude.ts decides how to talk. This file owns the main query path: system prompt shaping, tool schema conversion, beta headers, caching, effort and thinking config, streaming, retry strategy, usage tracking, prompt fingerprinting, and response normalization.

Why It Feels Large

The file has to bridge many concerns that all affect one model request:

  • Message normalization and tool-result pairing
  • Model selection and provider-specific capability checks
  • Prompt cache strategy and cache-break detection
  • Streaming request orchestration
  • Cost and usage accounting
  • Retry, fallback, and refusal handling

Main Lesson

Serious model clients are not “call API, print answer.” They are request engines that coordinate context management, tool schema exposure, retry behavior, observability, and product feature flags around every single turn.

Source Navigation

Recommended Source Files

  • source/services/api/claude.ts
  • source/services/api/client.ts
  • source/services/api/logging.ts
  • source/services/tokenEstimation.ts
  • source/services/api/sessionIngress.ts

Next Files to Read

  • source/services/api/promptCacheBreakDetection.ts
  • source/services/api/dumpPrompts.ts
  • source/services/compact/apiMicrocompact.ts

Related Chapters