Module persistence 

Agent-state persistence: turning a live ECS agent into the on-disk snapshot the dashboard/API read (meta.json + context.json under the run directory).

This module holds the pure serialization core - components that carry an agent’s run identity and running token totals, plus functions that build the RunMeta/ContextSnapshot value types from an agent’s live components. It does no I/O; the async write lane and the snapshot-dispatch system layer on top of these.

Structs

RunMetadata

Static per-agent run metadata (the parts of RunMeta that don’t change as the agent runs). Set once when the agent is spawned; the dynamic fields are filled from the live components at snapshot time.

RunOutcomeFlags

Run-scoped productivity flags, mirrored into meta.json so an empty run can be recognized (and explained) from disk. Unlike StageProgress, this is never reset on a stage transition - it describes the whole run.

TokenTotals

Running token + tool-call totals accumulated across an agent’s inferences, for the snapshot. Updated by the inference-collect system.

Functions

build_context_snapshot

Build the full context snapshot (context.json) from a window. Pure over the window - no engine/entity. (Ported from the CLI’s build_context_snapshot.)

build_run_meta

Build the run metadata (meta.json) from an agent’s live components, stamping updated_at with now_secs. stage_index is the agent’s current stage position within its blueprint.

run_status_from

Map an agent’s ECS status to the on-disk RunStatus.

stage_status_from

Map an agent’s ECS status to the on-disk per-stage StageRunStatus for the stage it is currently in. Cancelled has no stage-level equivalent, so it surfaces as Error (the stage stopped without completing).