Recording and replay¶
HANI2 records everything that happens in every negotiation, in a file you can replay later exactly as the participant saw it, and evaluate with the evaluation metrics. Recording is on by default.
What is recorded¶
One recording per negotiation. It starts when a scenario is loaded and ends when the next one is loaded or the session closes, so the questionnaire after a negotiation belongs to it.
| What | Details |
|---|---|
| The screen | Every state and tool view the server sent to the browser, in order, with a sequence number. Replaying them rebuilds what was on screen (see the known limits). |
| The browser | Pointer moves and clicks (with the element clicked), keys, text typed in fields, scrolling, window focus, tab visibility, the viewport size, device and theme, which server message was on screen when, and the participant's local UI state (open drawers, menus, tabs, the assistant panel, enlarged tools, dialogs). |
| Every action | Every message the browser sent (button clicks, offer edits, chat, tool inputs, layout changes, questionnaire answers), and every action on the participant's seat with who took it: the human, the assistant or the autopilot. |
| The negotiation | The scenario with each party's utility for every outcome and the reserved values, the opponent, the settings, the full offer trace and the result. |
| The assistant | Every chat message, every offer it filled in, every function it called (arguments, result, time). |
| Language models | Every call by the assistant, the opponent or HANI2 itself: model, prompt (stored once — later calls store only new messages), response, tool calls, latency, tokens and cost. |
| Events | Everything also written to the event log (tool opened, tab changed, offer made, …). |
Recordings are stored per participant in <results>/<user>/recordings/:
<id>.hrec— the recording: gzip-compressed JSON lines (a few hundred kB for a long negotiation);<id>.json— a short summary used for listing;<id>.eval.json— cached language-model judgements (see evaluation).
While a negotiation runs the file is <id>.hrec.jsonl (plain, flushed after every line), so a
session that is abandoned or a server that crashes still leaves a readable recording.
Recordings contain everything
A recording holds both parties' preferences and everything participants typed. Only admins can list, open or download recordings in the app.
Turning it off¶
or in env.json:
The replay tool¶
Open Replay from the admin console, go to /replay, or run:
hani2 replay open # every recording in the results folder
hani2 replay open path/to/folder file.hrec # also show these
Library¶
A table of recordings with search and filters (user, opponent, status, scenario). Select
recordings to evaluate them (pick metrics by kind, optionally with the language-model judge)
or compare them grouped by opponent, assistant, user, scenario or experiment. Every table can
be exported as CSV. You can also upload .hrec files from elsewhere.
Player¶
Opens one recording. The negotiation is shown at the participant's own window size (scaled to fit) with their pointer, clicks and key presses drawn on top.
- Play, pause, speed (0.5× to 8×), skip idle periods, jump to the previous or next action.
- A timeline with markers for human actions, partner offers, assistant messages and suggestions, language-model calls, clicks and the questionnaire.
- Events: everything in order, readable ("Human offered …", "Assistant: …", "LLM call (support, 1.2 s, 845 tokens)", "Clicked Accept"); click one to jump there.
- Metrics: the evaluation of this recording.
- Fidelity: checks the replay against the participant's browser. Every few seconds the browser recorded a fingerprint of what it was showing; the player rebuilds the same moment and compares. It also reports server messages the browser never confirmed. Use it to confirm a recording really captured everything.
- Info: the session, scenario, opponent, assistant, result and file.
Known limits of the replay¶
The replay rebuilds everything the server sent and everything the browser reported. A few things that never left the participant's browser are approximated:
- a slider being dragged before the value was sent is not shown moving;
- a notification closed early is shown for its full duration;
- the collapsed / page / sort state of a tool card or table without a component
id; - a fingerprint taken while a dragged divider waits for the server's echo may briefly not match (the next one does);
- a recording made without browser telemetry (e.g. a headless run) has no pointer, clicks or local UI state.
From the command line¶
hani2 replay list [PATHS…] # recordings, with result and length
hani2 replay show FILE.hrec [--events] # what a recording holds
hani2 replay export FILE.hrec -o out.json # as plain JSON
hani2 replay metrics # the evaluation metrics
hani2 replay evaluate [PATHS…] [-m outcome,optimality] [--llm] [-o table.csv]
hani2 replay compare [PATHS…] --by opponent [-o groups.csv]
PATHS are recording files or folders (searched recursively); the default is the results folder.
From Python¶
from hani2.recording import Recording
rec = Recording.load("results/alice/recordings/20261117-101500-Trade-1a2b3c.hrec")
rec.summary # the result
rec.offers() # every offer, by whom
rec.of("chat") # assistant chat
rec.of("llm") # language-model calls
rec.telemetry() # (time, type, data) from the browser
rec.state_at(42.0) # what was on screen 42 s into the recording
The file format¶
Each line is a JSON object. The first is the header
({"k": "header", "format": "hani2-recording", "version": 1, "id", "t0", "session", …}); every
other line has t (seconds since t0) and k (its kind):
k |
Contents |
|---|---|
out |
A message sent to the browser: m (its type) and seq. state and tool messages are stored as a full copy (full) or as changes since the previous one (delta); others as msg. |
in |
A message from the browser (msg). |
tel |
A batch of browser telemetry: sent (browser clock, ms) and ev, a list of [browser ms, type, …]. Types: vp viewport, mm pointer move, pd/pu pointer down/up, click, key, input, scroll, focus, blur, vis, recv (a server message was applied), ui (local UI state), toast, chk (fingerprint). |
ev |
An event-log entry (type, component, action, value, …). |
act |
An action on the participant's seat: actor (human, agent, autopilot), type (offer, accept, end, text), offer, values, text, utility. |
draft |
The counter-offer was edited (by: human or agent). |
chat |
An assistant chat message. |
llm |
A language-model call: role, model, latency, usage, cost, prefix (messages shared with the previous call of that role) and the new messages, response. |
fn |
A function the assistant called: name, args, result, latency. |
scenario |
Issues, outcomes, utilities (one list per party), reserved, human_index, serialized utility functions. |
start, trace, result, questionnaire, end |
The negotiation's start (opponent, settings, assistant), its full trace, its result, the questionnaire and its answers, and the end of the recording. |
Deltas map a key to {"s": value} (set), {"a": [items]} (append to a list), {"d": 1}
(delete) or {"o": delta} (changes inside a nested object). hani2.recording.format.patch
applies them.