Module history_sink 

Durable MinIO/S3 sink for pure chat history.

Why a second sink?

Phase A of the history/context refactor makes [Session::messages] a pure, append-only record of what happened. The local JSON file at ~/.local/share/codetether/sessions/{id}.json is the authoritative resume cache, but it also gets rewritten on every save() — so a crash between saves or a laptop loss evicts the record entirely.

The history sink streams the pure transcript to a MinIO-compatible S3 bucket as an append-only JSONL object, one line per message. This serves three purposes that the Liu et al. (arXiv:2512.22087), Meta-Harness (arXiv:2603.28052), and ClawVM (arXiv:2604.10352) references all emphasise:

1. Durable archive for session_recall across machines and crashes.
2. Filesystem-as-history substrate — the virtual context_browse files served in Phase B are backed by these objects.
3. Pointer-residency backing store — when a ResidencyLevel::Pointer page is selected, its handle points here.

The sink is env-gated and non-fatal. When the endpoint isn’t configured or the upload fails, the session continues; a single tracing::warn! records the error and the local file remains authoritative for resume.

Configuration

Reads five environment variables at session load / first save:

Variable	Required?	Purpose
CODETETHER_HISTORY_S3_ENDPOINT	Yes	MinIO/S3 endpoint URL
CODETETHER_HISTORY_S3_BUCKET	Yes	Bucket name
CODETETHER_HISTORY_S3_PREFIX	No	Key prefix (default history/)
CODETETHER_HISTORY_S3_ACCESS_KEY	Yes	S3 access key
CODETETHER_HISTORY_S3_SECRET_KEY	Yes	S3 secret key

When any required variable is unset, HistorySinkConfig::from_env returns Ok(None) and the sink is silently disabled.

Examples

use codetether_agent::session::history_sink::HistorySinkConfig;

match HistorySinkConfig::from_env() {
    Ok(Some(config)) => {
        assert!(!config.endpoint.is_empty());
    }
    Ok(None) => {
        // Env vars not set; sink disabled.
    }
    Err(e) => eprintln!("history sink misconfigured: {e}"),
}

Structs

HistorySinkConfig

Durable history-sink configuration.

PointerHandle

Stable locator for a single ResidencyLevel::Pointer page’s backing bytes.

Functions

encode_jsonl_delta

Encode messages[start..] as JSONL — one line per message.

resolve_pointer

Fetch the bytes referenced by a PointerHandle from the MinIO sink.

upload_full_history

Overwrite the session’s history.jsonl object with the full JSONL rendering of messages.