feat: citation content

[cpsievert]

Overview

When a model answers using web search or fetch tools, chatlas now surfaces which
sources back the answer and which words each source grounds, normalized across
OpenAI, Anthropic, and Google. Grounded answers carry their citations through to
turns uniformly — both progressively during streaming and on the final turn.

Motivation

Citation information used to be dropped: OpenAI's citation annotations were discarded,
Anthropic's citation deltas never reached normalized content, and Google's grounding
metadata was ignored entirely. Each provider exposed this differently (or not at all),
so there was no portable way to build a UI that shows sources. This branch gives
chatlas one citation model so a downstream consumer (e.g. shinychat) can render
footnote markers and source lists without touching raw provider payloads.

The model is deliberately shaped to be general-ready: web search is the first
consumer, but the same ContentCitation extends to file / document / RAG citations
(uploaded files, file_search, etc.) by adding new Source subclasses — no redesign
of ContentCitation required when that work lands.

Public API

• ContentCitation — a first-class content type representing a source that grounds
  part of the assistant's answer:
  • source — the evidence it points to, a typed Source (see below), or None when
    a citation grounds answer text with no resolvable source.
  • grounded_text — the answer-side span the citation grounds (the words a footnote
    marker attaches to / the highlightable span).
  • cited_text — the source-side evidence quote, when the provider supplies one
    (populated for ChatAnthropic() web search today).
  • extra — remaining provider-specific payload.
• Source — the identity of a piece of evidence. It is a small hierarchy dispatched
  on type; today the one concrete member is WebSource (type="web", url,
  optional title). File / document / RAG variants slot in later as additional
  subclasses.
• ContentCitation, Source, and WebSource are all exported from chatlas.types.

Behavior

• ContentCitation items sit in a turn's contents list immediately after the text
  they ground, in stream order — position and grounded_text together place a citation
  precisely.
• Under streaming (content="all"), citations arrive interleaved with text
  (OpenAI/Anthropic) or at stream end (Google). The final turn carries the same items in
  the same order, so streaming and replay have one shape.
• grounded_text is normalized to one meaning across providers — the resolved answer
  span, carried as a string (not offsets), sidestepping Google's byte- vs. OpenAI/
  Anthropic's character-offset mismatch.
• Web fetch results also carry a status field.

Breaking change

• ContentToolResponseSearch.urls (list[str]) is replaced by .sources
  (list[WebSource], each carrying url/title). Migrate x.urls →
  [s.url for s in x.sources]. (This content type is unreleased, so the blast radius is
  effectively nil.)

Notes for reviewers

• Per-provider wiring lives in each _provider_*.py's stream_content() and
  _as_turn(). All three filter ContentCitation out of turn serialization (it's
  client-side metadata, not sent back to APIs).
• Source is a pydantic base class rather than a discriminated union (only one variant
  today). A create_source(data) factory + @field_validator(mode="before") hooks +
  SerializeAsAny on the source-typed fields round-trip the concrete subclass through
  model_dump()/model_validate(). This upgrades cleanly to a real discriminated union
  once a second variant exists.
• The Google path is greenfield — grounding and url-context metadata were previously
  unsurfaced.

Test plan

• uv run pyright — 0 errors (full package)
• ruff check + ruff format --check — clean
• Content model unit tests: Source/WebSource, nested-source ContentCitation,
  cited_text, round-trip rebuilds WebSource (not a bare Source), exports
• Per-provider web search/fetch tests assert ContentCitation (with source.url)
  in both streaming and final turns; Anthropic additionally asserts cited_text;
  all replay VCR cassettes offline
• Reviewer: confirm full make check in CI