Implement #4: Context and Conversation Management

[yagop]

Closes #4

Chapter 4 teaches the stateful layer over the stateless Messages API: conversation history, the system prompt, token counting + rolling-window trimming, history summarization, prompt caching, and persisted per-user Telegram sessions. Authored by the write-chapter ultracode Workflow (1 doc agent + 6 implement/review pipeline pairs), then verified end-to-end.

Definition of done

• Chapter at chapters/04-context.md, <=120 lines, <=4 main-line H2s plus an optional closer
• Every sample runnable with bun run, imported via <<< @/examples/04-context/file.ts, <=35 lines, comment:code <=0.30
• One-home rule held: no prose sentence restates an inline code comment
• Friendliness floor held: reader addressed as "you"; intro + the History/Per-user sections open warm
• Samples use only real @anthropic-ai/sdk surface; ASCII punctuation only
• Optional material lives in asides (a :::warning, a :::tip, and one comparison table); the main line reads complete without them
• Linked from README.md and the .vitepress/config.ts sidebar; bun x vitepress build passes
• Caching sample actually shows a non-zero cache_read_input_tokens

Verification (run live against an Anthropic-compatible gateway)

Chapter budget:

wc -l chapters/04-context.md   -> 68   (<=120)
grep -c '^## '                 -> 4    (<=4 main-line H2s)

Sample budgets (all <=35 lines, comment:code <=0.30):

multi-turn.ts         30 lines  ratio 0.158
system-prompt.ts      28 lines  ratio 0.158
token-counter.ts      31 lines  ratio 0.200
summarize-history.ts  35 lines  ratio 0.100
prompt-cache.ts       21 lines  ratio 0.231
telegram-sessions.ts  35 lines  ratio 0.032

bunx tsc --noEmit clean; bun x vitepress@2.0.0-alpha.17 build passes (chapter 4 renders, all six snippet imports resolve). Each sample was run, not just typechecked:

• multi-turn.ts - history survives across 3 turns; turn 3 recalls "teal" from turn 1; ends history holds 6 messages across 3 turns.
• system-prompt.ts - the pirate persona ("...Arr!") holds across both turns, string system then block-array system.
• token-counter.ts - counting against GLM-4.6; with a small demo threshold the rolling window trims in pairs and holds at window=3 msgs instead of growing.
• summarize-history.ts - history is 78 tokens; threshold 30 -> compacted 4 turns into 2, replaced by one injected user/assistant summary pair.
• prompt-cache.ts - two identical requests: request 1 created=0 read=0, request 2 created=0 read=6272. The non-zero cache_read_input_tokens=6272 on the second request is the cache hit. (Note: the gateway used for this run does not surface cache_creation_input_tokens, so it reads as 0 here via a ?? 0 guard; on Anthropic direct, request 1 reports the creation count. The DoD field, cache_read_input_tokens, is non-zero as required.)
• telegram-sessions.ts - long-running poller (cannot run to completion). Boot-smoked: deserializes a seeded sessions.json into its per-chat.id Map at startup and long-polls getUpdates cleanly; type-checked and snippet resolves in the build. The transient sessions.json artifact was removed so examples/04-context/ ships exactly the six .ts files.

Review flags

None - the Workflow returned all six samples as fully compliant (no flagged files).