Module ccr 

Content-addressed recovery (CCR) for the proxy’s lossy rewrites (#482).

When the proxy prunes an old tool_result from conversation history, the lossy stub used to say “re-read the file” — which is stale-unsafe by construction: in an agent session files are edited or deleted between turns, so a re-read returns the current bytes (or fails), not the historical version the conversation actually showed. The model could then silently reason about the wrong content.

CCR fixes this by persisting the verbatim original to the shared, content-addressed tee store ({state}/tee/, reused from the shell path) and embedding a retrieval handle — the absolute path of that file — in the stub. These legacy copies have no source authority and are only available without an active policy. Protected file recovery uses source-bound archives.

Cache-safety (#448)

The handle is the file path, and the path is a pure function of the content hash (crate::core::hasher::hash_short). For a fixed pruned message the handle is therefore byte-identical on every later turn, so the provider prompt-cache prefix is preserved for available copies. Failed or unauthorized persistence returns no handle; a deterministic path is not proof of recovery.

The proxy splices in-band markers back into requests (proxy::ccr); the store, its resolver and its bounded read live here, below every caller.

Enums

TeeResolveError

Why a canonical tee handle could not be resolved.

Constants

EXPAND_CLOSE

Closing delimiter of an in-band retrieval marker.

EXPAND_OPEN

Opening delimiter of an in-band retrieval marker: <lc_expand:HASH> (#493).

LITELLM_HASH_LEN

Length of a LiteLLM gateway retrieval hash (#702): LiteLLM’s headroom guardrail scans compressed text with hash=([a-f0-9]{24}) (BerriAI/litellm#31681), so the marker must carry exactly 24 lowercase hex.

MIN_TEE_BYTES

Originals smaller than this are not worth a tee file + handle; the caller keeps its plain stub. Matches the spirit of the prune length thresholds.

Functions

inband_locator

The in-band marker for handle only when in-band CCR is enabled (#493), else None. Stub sites use this to advertise an echo-able <lc_expand:HASH> solely in in-band mode: a normal (shared-filesystem) deployment keeps its path handle, so the model never sees a marker the proxy would not splice.

inband_marker

The in-band retrieval marker <lc_expand:HASH> for a CCR handle (#493).

litellm_hash

The 24-hex gateway retrieval hash for content (#702): the first 24 chars of the full blake3 hex. A strict extension of the 16-hex tee name (crate::core::hasher::hash_short is the same digest truncated to 16), so hash[..16] resolves the tee file while the extra 8 chars keep the marker collision-resistant on the gateway side. Pure — the marker embedding it stays byte-stable per content (#498).

persist

Persist content verbatim (best-effort, secret-redacted) to the content-addressed tee store and return its retrieval handle (the absolute path). Returns None for protected originless data, invalid/oversized input or persistence failure. Re-persisting identical content keeps the same path; callers must preserve useful fresh output when no recovery handle is available.

persist_conversation

Persist a dropped conversation message under a compact conv_ handle.

persist_html

Persist an HTML page’s verbatim original (#1124) under the html_ prefix and return its {state}/tee/html_{hash}.log handle. The extracted markdown is the compressed form; the full HTML is recoverable via resolve_tee / ctx_expand. Shares the content-address and best-effort write contract of persist.

persist_json

Persist a JSON crusher’s verbatim original (#936) under the json_ prefix and return its {state}/tee/json_{hash}.log handle. Used by the lossy crush stage so a dropped column is always recoverable out-of-band via resolve_tee / ctx_expand, never reconstructed from the (lossy) text. Shares the content-address and best-effort write contract of persist, so the embedded handle stays deterministic (cache-safe).

persist_once

Like persist, but a content-addressed copy that is already on disk is named as it is: no rewrite, no new relevance registration. A copy the TTL cleanup removed is written again (self-healing). Under protection nothing originless is named, existing or not.

persist_tabular

Persist a tabular (CSV/TSV) crusher’s verbatim original (#982) under the tbl_ prefix and return its {state}/tee/tbl_{hash}.log handle. Used by the lossy column-drop stage so a dropped column is always recoverable out-of-band via resolve_tee / ctx_expand, never reconstructed from the (lossy) text. Shares the content-address and best-effort write contract of persist.

persist_tool_definition

Persist the full definition of a tool whose description the proxy shortened (K26) under the tool_ prefix. Returns the basename, like persist_conversation: it resolves through ctx_expand and keeps a machine-specific path out of the provider prompt, so the shortened tool list is the same bytes on every machine and turn.

persist_yaml

Persist a YAML crusher’s verbatim original (#985) under the yaml_ prefix and return its {state}/tee/yaml_{hash}.log handle. Used by the lossy column-drop stage so a dropped column is always recoverable out-of-band via resolve_tee / ctx_expand, never reconstructed from the (lossy) text. Shares the content-address and best-effort write contract of persist.

read_checked_tee

One bounded, no-follow read shared by selectors, HTTP, CLI and in-band recovery. Policy is freshly resolved before I/O and rechecked at publication.

read_tee

Resolve and read a tee handle in one step.

read_tee_detailed

read_tee_file

Read a tee file that resolve_tee returned. One read path for every caller: bounded, no-follow and bound to the checked file, re-checked against the current policy and re-admitted by the context gateway.

resolve_tee

Back-compatible resolver used by ctx_expand.

resolve_tee_checked

Resolve a retrieval ID through the same canonical store path used by ctx_expand, while distinguishing malformed IDs and policy refusals.

retrieve_litellm

Resolve a LiteLLM hash=<24hex> retrieval id (#702) back to the verbatim original in the tee store, for GET /v1/retrieve/{hash}. Shape-locked to LiteLLM’s own regex (24 lowercase hex — uppercase or any other length is rejected, never coerced) so only a string the guardrail could actually have captured resolves; the first 16 chars are the proxy_ tee content-address.

write_tee

Never publish an incomplete, oversized, unfiltered or protected originless copy. Atomic replacement preserves shell’s latest-output handle contract.