Session

Session

The lifecycle skill: resume a saved game with a recap, save at a pause, and inspect the roll-log. The save_game document the engine persists is the single source of truth; everything here reads or writes around it. When resume finishes, hand off to play for the turn loop.

Read the referee's constitution before anything else. In particular, Article VII.4 governs what the roll-log may reveal to the player mid-scene.

Resume a saved game

1. Enumerate saves. Read the game directory with the gametool CLI via Bash (a filesystem read, off the play surface):

   uv run --project ${CLAUDE_PLUGIN_ROOT}/server python -m osrlib_referee_mcp.gametool saves
   

   It returns {saves: [{adventure_id, save_id, schema_version, engine_version, mtime}, …]}, newest first. If there's exactly one, use it; otherwise AskUserQuestion which save_id to continue.

2. Load it. session_load(save_id) re-activates the session — the adventure spec is embedded in the save, so no adventure_id is needed.

3. Recap from the cold observe. Call observe(); right after a load it comes back "cold" with a bounded tail of recent events. Narrate "here's where you left off" from that tail and the current mode/area/party. If a journal file exists for this save (see below), Read it for a richer narrative recap — it is prose context, never reloaded as state.

4. Hand off to play to continue the turn loop.

Save

session_save() persists the active session to its current slot and returns the save_id. Report it back. A session keeps multiple named saves per adventure through distinct save_id stems (set at session_new); session_save writes to whichever slot is active.

The optional journal

You may write a human-readable journal alongside the save — a session log and current-situation note — as a convenience for the player and for recaps, never canonical. Write it as a .md sibling of the save in the game directory:

<game-root>/adventures/<adventure_id>/<save_id>.journal.md

(<game-root> is ~/osr-games by default or wherever OSRLIB_REFEREE_GAME_ROOT points; gametool saves gives the adventure_id/save_id.) It is derived and disposable: the save_game document is the one source of truth, and the journal is never read back to reconstruct game state — only as recap prose.

Audit — the roll-log

The engine records every roll, and session_audit surfaces the real trajectory — dice rolls, attack and save resolutions, XP awards.

session_audit(kinds?, visibility?, limit?)

• kinds narrows to specific event_types (e.g. ["dice_rolled", "attack_rolled", "saving_throw_rolled", "xp_awarded"]); limit bounds the tail.
• visibility draws the information-discipline boundary (constitution Article VII.4 / Article II). Mid-scene, request visibility="player" — it returns the player-visibility events (a character's own attacks and saves, XP awards, already-revealed outcomes) and withholds the referee-only rolls (a morale check, a reaction roll, an unrevealed monster's stats, your own RollDice adjudications). The filter is mechanical — it keys on each event's own visibility, so a monster's attack or save roll against a PC is player-visible too (a revealed in-fiction outcome, not a leak); apply your own judgment before surfacing anything that would spoil a beat still hidden in the fiction. At a scene boundary, in town, or at session end, the full referee trajectory is fair game — omit visibility (or pass "referee") and show the complete roll history. That post-hoc transparency is precisely the eval-ability this project was built for.

Present the audit as a readable log — what was rolled, what it needed (only when revealing is allowed), and the outcome — never as a raw event dump. Use character_sheet(character_id) when the player wants a member's full derived numbers alongside the log.

Tool reference