Context windows

ContextWindow

The turns around an anchor event, persisted as refs plus previews.

Usage

ContextWindow(
    anchor,
    before,
    trigger,
    after,
    fidelity,
    preview_chars,
    preview_schema=None
)

Attributes

anchor: EventRef: The event the window centers on.
before: tuple[TurnRef, …]: Turns preceding the anchor’s turn, oldest first.
trigger: TurnRef | None: The anchor’s own turn, or None when the window carries no trigger preview.
after: tuple[TurnRef, …]: Turns following the anchor’s turn, oldest first.
fidelity: Fidelity: 'full' while the transcript backs the window; 'summary' once only the previews remain.
preview_chars: int: The preview budget the window was captured at.
preview_schema: str | None: The typed-preview version (cc-transcript.preview/1) when the turn refs carry typed previews, or None for a legacy window.

Example

>>> window = capture_window(raw, anchor)
>>> hydrated = window.hydrate()
>>> text = hydrated.render(budget=Budget()) if hydrated else window.render_preview(budget=Budget())

Methods

Name	Description
from_json()	Deserialize a window persisted by to_json().
hydrate()	Resolve every ref back to real turns for full-fidelity rendering.
render_preview()	Render the persisted previews, never touching the transcript.
to_json()	Serialize to the `cc-transcript.context/2` wire schema, byte-stably.

from_json()

Deserialize a window persisted by to_json().

Usage

Source

from_json(data)

Raises

SchemaError: When data does not carry the literal cc-transcript.context/2 schema.

hydrate()

Resolve every ref back to real turns for full-fidelity rendering.

Usage

Source

hydrate()

Returns

HydratedWindow | None

None when the transcript has expired or any ref was compacted

away — callers fall back to render_preview(), never

hydrate-or-fail.

render_preview()

Render the persisted previews, never touching the transcript.

Usage

Source

render_preview(*, budget)

Summary-fidelity windows always lead with the [summary fidelity — transcript unavailable] label.

to_json()

Serialize to the cc-transcript.context/2 wire schema, byte-stably.

Usage

Source

to_json()

Typed previews (cc-transcript.preview/1) ride alongside the rendered string previews when present; a legacy window omits both, so it stays readable by every reader.

HydratedWindow

A context window resolved back to its real turns.

Usage

Source

HydratedWindow(window, turns)

Attributes

window: ContextWindow: The capture this hydration came from.
turns: tuple[Turn, …]: The resolved turns, in window order — before, trigger, after.

Methods

Name	Description
render()	Render the resolved turns at full fidelity; truncation happens only here.

render()

Render the resolved turns at full fidelity; truncation happens only here.

Usage

Source

render(*, budget)

TurnRef

A reference to one turn: resolvable refs plus a capture-time preview.

Usage

Source

TurnRef(role, refs, preview, tool_digests, previews=None)

Attributes

role: Role: Whether a user prompt opened the turn or it is assistant-only preamble.
refs: tuple[EventRef, …]: References to the turn’s events.
preview: str: The turn rendered at capture time, at the preview budget.
tool_digests: tuple[ToolDigest, …]: Content digests of the turn’s tool calls, in order.
previews: tuple[Preview, …] | None: The turn’s typed previews (cc-transcript.preview/1), or None for a legacy window persisted before typed previews existed.

capture_window()

Capture the turns around anchor as a live, full-fidelity window.

Usage

Source

capture_window(raw, anchor, *, before=6, after=2, preview_chars=200)

Parses raw in the native core, lifts it into turns under native Claude Code semantics, and builds a TurnRef per turn with a preview rendered at the explicit, persisted preview budget.

Parameters

raw: bytes: The session’s transcript bytes, exactly as they hit disk.
anchor: EventRef: The event the window centers on; its session, event, and tool-use ids locate the anchor within raw.
before: int = 6: How many turns before the anchor’s turn to capture.
after: int = 2: How many turns after the anchor’s turn to capture.
preview_chars: int = 200: The per-chunk preview budget, persisted on the window.

Raises

ValueError: When anchor does not resolve within raw.

SchemaError

Persisted context data does not carry a known schema version.

Usage

Source

SchemaError()