modelerrors: make overflow errors more specific

[trungutt]

Motivation

Context-overflow errors from LLM providers come in three distinct shapes, but modelerrors collapses them into one. The conflation has user-visible consequences:

• A provider rejecting a single oversized request (HTTP 413, e.g. paste over the wire-body cap) is reported as "context window exceeded — try /compact" — but /compact cannot help, because the offending turn still has to be sent on every subsequent call. Sessions get stuck failing in the same way until the user starts over.
• An image too large for the provider is reported as a generic context error, hiding the actual cause.
• Token-count overflow and wire-size overflow share one retry path even though they need different recovery.

Without distinguishing them at the classifier, every downstream consumer (runtime retry logic, error-code routing, UI hints) has to guess.

Change

Introduce OverflowKind with three values, classified by a small two-tier function:

Kind	Meaning	Recovery shape
tokens	Conversation exceeds the model's context window	Compaction helps
wire	Request body exceeds the provider's wire-level limit	Compaction cannot
media	Image, PDF, or attachment too large	Strip media

Classifier:

1. Structured signals (high confidence): HTTP 413, body.error.type == "request_too_large", body.error.code == "context_length_exceeded".
2. Provider-prose substrings as a fallback, covering the observed error wording across Anthropic, OpenAI, Bedrock, Gemini, Mistral, Groq, Vertex, OpenRouter, Ollama, Kimi, MiniMax, z.ai, and others. Best-effort — provider wording is not contractual, so this list is expected to drift and is easy to extend (one line per provider phrase).

FormatError now returns three distinct, provider-agnostic messages (no vendor names — the wire cap is a deployment detail of the provider, not something the user can act on by name). Two new ErrorCode constants (request_too_large, media_too_large) reach external consumers via the existing ErrorEvent.Code channel so they can render the right hint per kind.

What is preserved

• IsContextOverflowError matches the same set of errors as before.
• Retry classification in ClassifyModelError is unchanged (overflow stays non-retryable).
• Auto-compaction still fires on overflow (this PR labels; it does not yet change control flow).
• NewContextOverflowError now auto-fills Kind from the underlying error, so existing wrap sites in pkg/runtime/fallback.go get the correct kind without code changes.

[docker-agent]

Assessment: 🟢 APPROVE

The overflow classification logic is well-structured and correct. The two-tier classifier (structured signals → prose fallback), the OverflowKindOf unwrapping semantics, FormatError switch, and classifyErrorCode routing all look sound. Backward compatibility is preserved: IsContextOverflowError still matches the same error set, and unclassifiable wraps default to OverflowKindTokens. Test coverage is thorough across 26 classifier cases, wrap semantics, and all three FormatError paths.

[docker-agent]

Assessment: 🟢 APPROVE

The classifier's two-tier approach (structured signals first, substring patterns as fallback) is sound. Tier 1 structured checks correctly map HTTP 413 → OverflowKindWire and context_length_exceeded → OverflowKindTokens. The OverflowKindOf helper correctly handles legacy zero-Kind wraps by falling back to classification on the underlying error. NewContextOverflowError auto-fills Kind correctly via classifyOverflow. The classifyErrorCode switch in loop_steps.go correctly routes all three kinds to distinct ErrorCode constants.

Intentional design noted: The PR description explicitly states "Auto-compaction still fires on overflow (this PR labels; it does not yet change control flow)" — the handleStreamError check is intentionally unchanged; control-flow differentiation for Wire/Media is deferred to a follow-up.

No bugs found in the changed code.