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

FinalOutput

The final output an agent has submitted, held on the agent entity until the persistence lane copies it into meta.json.

RunMetaSources

The agent components meta.json is built from.

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.

RunPosition

Where the run has got to, and when.

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.

is_empty_output

Whether a run in status carrying flags stopped with nothing to show for itself.

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).