Implement #8: Production and Deployment

[yagop]

Closes #8

Chapter 8 hardens the agent for production: the SDK error hierarchy, retries/timeouts, rate-limit-aware concurrency, observability + cost, and deployment (a webhook server + Dockerfile). Authored single-pass; the cutoff-sensitive error/retry surface was verified against the installed SDK.

Definition of done

• Chapter at chapters/08-production.md, <=120 lines, <=4 main-line H2s plus a closer
• Every sample runnable, imported via <<< @/examples/08-production/file.ts
• One-home rule held (the maxRetries: 0 gotcha lives in a :::warning, not a code comment); reader addressed as "you"; intro + sections open warm
• Samples use only real @anthropic-ai/sdk surface; ASCII punctuation only
• Optional material (layered cache breakpoints) lives in a Going-deeper :::details aside
• Linked from README.md and the .vitepress/config.ts sidebar; bun x vitepress build passes
• Error/retry behavior verified against the current SDK - see below
• Sample line budget: samples are 27-33 lines (mostly within <=35; the skill cap is <=100)

Cutoff-sensitive corrections (issue text was outdated; verified against the installed SDK .d.ts)

• APITimeoutError -> APIConnectionTimeoutError (the real exported class, extends APIConnectionError).
• client.messages.withRawResponse.create(...) -> .create(...).withResponse() (returns { data, response, request_id }) / .asResponse().
• x-ratelimit-remaining-requests -> anthropic-ratelimit-requests-remaining (Anthropic's header name).
• On APIError the request id is error.requestID (camelCase), while .withResponse() returns request_id (snake_case).

Verification (run live)

Chapter: wc -l -> 61; grep -c '^## ' -> 4. tsc --noEmit clean; vitepress build passes (all six snippets resolve, including the Dockerfile).

• error-handling.ts -> ok request_id=n/a: Hi there, friend, then the malformed (empty-messages) call hits the bad request (400) branch.
• retry-backoff.ts -> succeeds with { maxRetries: 0 }; the retry-after backoff path is in place.
• cost-tracker.ts -> input=25 output=41 cache_read=0, estimated cost: $0.00069.
• concurrency-limiter.ts -> 5 prompts drained by 2 workers concurrently.
• webhook-server.ts -> smoke-tested: a secret-validated POST processed a message (chat 1: pong) and returned ok; a POST without the secret got 403.
• Dockerfile -> well-formed multi-stage build (USER bun, env-only secrets); not docker build-tested - Docker isn't available in this environment.

Notes / gateway flags

• The gateway used for the live run returns request_id: null and omits anthropic-ratelimit-* headers (real Anthropic provides both), so the request-id logs print n/a and the limiter's remaining-count stays Infinity. The sample code reads the real fields and is correct against Anthropic.

Review flags

None.

🤖 Generated with Claude Code