Sessions & replays
Every run is a durable, inspectable session. Resume to continue, replay to re-run step by step, export to share.
Sessions are stored as plain JSON under ~/.harnext/sessions (configurable via HARNEXT_HOME). A session captures the full message history, every tool call and result, token usage, and the metadata you attached.
Resuming a run
Pass a session id (or a Session object) to the session option, and the new run continues with the entire prior context intact.
first = agent.run("Scaffold a FastAPI app")
sid = first.session_id
# Later, in a different process:
agent2 = Harnext(provider="anthropic", session=sid)
agent2.run("Add a Dockerfile for it")The Session API
from harnext import Session
# Discover and load
sessions = Session.list(limit=20) # list[SessionInfo]
s = Session.load("sess_8f4ac1b")
# Inspect
s.id
s.created_at
s.messages # full transcript
s.steps # every tool call + result
s.usage # aggregate token usage
s.metadata
# Share / archive
s.export("run.json")
s.delete()Replays
A replay re-executes a recorded session step by step. By default it replays from the stored transcript (no model calls, no token cost) — ideal for audits, demos, and debugging. Pass live=True to re-run the same prompts against the model again.
s = Session.load("sess_8f4ac1b")
for step in s.replay(): # deterministic re-run from the record
print(step.tool, step.status)
# Re-run against the model from a chosen step
s.replay(live=True, from_step=3)Fork a session
Branch from any point to explore an alternative without touching the original run.
branch = s.fork(at_step=5)
agent = Harnext(provider="anthropic", session=branch)
agent.run("Try a different approach: use SQLModel instead")HARNEXT_HOME to relocate the store (e.g. a per-project .harnext directory in CI). Transcripts redact known credential patterns; treat exported files as sensitive regardless.