Replay & reproducibility¶
Every pipeline tool call against a session is logged, so a run can be reproduced later as a plain Python script — no agent, no MCP server, no re-derivation of what happened.
How it works¶
Each *_from_session tool (and the other pipeline-mutating tools —
ingest_to_session, plotting, covariance, SACC assembly, inference,
register_session) appends one JSON line to
{session_dir}/tool_call_log.jsonl as it runs: tool name, the arguments it
was called with, and a UTC timestamp. Logging is best-effort and non-fatal —
an I/O error there never fails the actual pipeline call.
generate_replay_script(session_dir, output_name=None) reads that log and
emits a self-contained script that imports straight from
cosmotron_mcp.tools and calls the same functions in the same order,
reproducing the run without going through opencode/Claude Code or the MCP
server at all:
The script is written to {session_dir}/scripts/replay_YYYY-MM-DD.py
(or output_name, if given) and registered as a "script" artefact. Run it
from the repo root:
Call it at the end of a successful run — it's how a session's exact sequence
of ingest_to_session → compute_*_from_session → plotting → covariance →
SACC calls gets captured for later reruns, diffing against a changed
catalogue, or handing to someone without opencode access.
Fallback: sessions without a log¶
A session that predates tool_call_log.jsonl, or one where logging failed
for a step, has no usable log. generate_replay_script then falls back to a
best-effort reconstruction from results/artefact_registry.json — walking
registered artefacts in creation order and recovering each one's
generated_by tool name and bin_index. This path is lossier (only whatever
the registry captured, not the exact call arguments), and the generated
script is header-flagged accordingly:
The return value's source field ("tool_call_log" vs
"artefact_registry") tells you which path was taken.
Why this matters¶
This is the concrete mechanism behind
Determinism & no fabrication: if every tool is pure given
its inputs, and every call is logged, a session isn't just an artefact
folder — it's a reproducible computation. That's also what makes a review
verdict or a covariance result auditable after the fact, not just at the
moment @reviewer looked at it.
Full signature: cosmotron_mcp.replay.