Skip to main content

Session recording

Status: built, default off. Tested against fakes (unit tests and an in-process handler test); not run on Linux or at scale.

What it is​

GET /v1/sessions/{id}/recording returns a signed bundle that replays what a session did, in time order: the journal rows, the event log and the approvals. POST /v1/recordings/verify checks a bundle's digest and signature and says which key signed it.

Why it is safe to hand out​

The bundle is built only from host records, then masked before it is signed:

SourceKeptLeft out
Journal rowaction, phase, time, hashes, the OTLP allowlist of scalar fields (ids, host, method, decision)free-text error/tail, bodies, previews, the subject; the row counts what it dropped
Eventkind, sequence, time, data length and SHA-256the data
Approvalkind, status, created and decided timesthe prompt and the planned action

Replay shows what happened and when, not the content. A reader who also holds the content can match it to the SHA-256.

Signing​

Ed25519 over the SHA-256 of the masked bundle, with the key from ZYVOR_AGENT_RECORDING_KEY (64 hex characters). With no key the endpoint answers 404, because an unsigned recording would prove nothing. The host holds the key; the agent never sees it. A bundle carries its signer's public key, so verification proves the bundle is intact and who signed it, not that the signer is one you trust.

A journal row's own hash is kept as a pointer into the journal. It was computed over the unmasked row, so it cannot be recomputed from the bundle; compare it against the journal itself.

Retention​

Recordings are built on request, not stored. They can only be as old as the records they read, so the existing ZYVOR_AGENT_EVENT_RETENTION_DAYS bounds the event part. Each export is journaled as merion.recording.export with a step count only.

Not done​

  • A richer replay view. The Merion session page has a Replay card (load, check the signature, scrub, download); it shows steps as lines, not a video.
  • Prompt and response capture. Replay alone shows what happened, not why; model calls are not in the bundle.
  • A browser or screen video. This records host-side actions, not pixels.
  • Key rotation and a trusted-signer list; today the caller decides whom to trust.