Struct RunMeta 

pub struct RunMeta {

    pub run_id: String,
    pub agent_name: String,
    pub agent_path: String,
    pub task: String,
    pub model: Option<String>,
    pub pid: u32,
    pub status: RunStatus,
    pub current_stage: String,
    pub stage_index: usize,
    pub num_stages: usize,
    pub iteration: usize,
    pub prompt_tokens: usize,
    pub completion_tokens: usize,
    pub cached_tokens: usize,
    pub cache_write_tokens: usize,
    pub tool_calls: usize,
    pub workdir: String,
    pub started_at: i64,
    pub updated_at: i64,
    pub last_progress_at: Option<i64>,
    pub error: Option<String>,
    pub title: Option<String>,
    pub metadata: HashMap<String, String>,
    pub callback_url: Option<String>,
    pub callback_secret: Option<String>,
    pub parent_run_id: Option<String>,
    pub children: Vec<String>,
    pub depth: usize,
    pub max_child_depth: usize,
    pub flags: RunFlags,
    pub yolo: bool,
    pub read_paths: Option<ReadPathGrantCounts>,
    pub final_output: Option<FinalOutputDescriptor>,
    pub waiting_on: Option<WaitReason>,
    pub output_request: Option<OutputSpec>,
}

Metadata for a single background agent run.

Fields

run_id: String

Identifies the run everywhere, and names its directory under ~/.leviath/runs/. Assigned at spawn and never reused.

agent_name: String

The blueprint’s [agent] name, not the file it was loaded from. Two runs of the same agent from different paths share this.

agent_path: String

Absolute path to the agent manifest directory

task: String

The task text the run was started with, verbatim.

model: Option<String>

The provider/model actually resolved for the entry stage, or None before resolution. Later stages may use a different one; this is not rewritten to follow them.

pid: u32

Always 0. There is no worker process per run: the daemon hosts every run as an entity in one shared world, so no run has a pid of its own.

Kept because it is written into every meta.json there has ever been, and served from GET /api/agents. Do not key liveness on it. pid == 0 is true of a run that is working, a run that has finished, and a run nothing is driving, so a sweeper that reverts on it reverts everything. Ask the daemon (lev ps) whether it is still hosting the run, and read status and last_progress_at off disk for what became of it.

status: RunStatus

Where the run stands. The durable counterpart to the ECS world’s live AgentStatus, and the one that survives a daemon restart.

current_stage: String

Name of the stage the run is in, matching a key under [stages].

stage_index: usize

Zero-based position of current_stage in the blueprint’s stage list. Not a progress measure: stages can loop and revisit.

num_stages: usize

How many stages the blueprint declares, so a reader can render stage_index as “3 of 7” without loading the manifest.

iteration: usize

Inference turns taken in the current stage, reset on entering a new one. Compared against the stage’s max_iterations.

prompt_tokens: usize

Cumulative input tokens billed across every inference this run has made, including retries.

completion_tokens: usize

Cumulative output tokens billed across every inference this run has made.

cached_tokens: usize

Cumulative tokens read from provider cache.

cache_write_tokens: usize

Cumulative tokens written to provider cache.

tool_calls: usize

Total number of tool calls made across all iterations.

workdir: String

Absolute path to the working directory for tool execution

started_at: i64

Unix timestamp (seconds)

updated_at: i64

Unix timestamp (seconds)

last_progress_at: Option<i64>

Unix seconds when this run last actually moved: a new iteration, a new stage, or a change of status. None before the first snapshot lands, and on runs written by a daemon older than this field.

Distinct from updated_at, which also advances on the 30-second persistence heartbeat and so stays fresh on a run that is wedged. A fresh updated_at is evidence the daemon is alive, and no evidence at all about the run. Anything that ages a run must read this instead. Note that a daemon restart resets it: a reloaded run really is re-driven from its saved context, so it really has just moved.

error: Option<String>

What went wrong, set alongside RunStatus::Error. None on every other status.

title: Option<String>

Short human-readable title generated from the task prompt (None until generated).

metadata: HashMap<String, String>

Custom key-value pairs from the spawn request (API metadata).

callback_url: Option<String>

Webhook URL to POST on agent completion/error.

callback_secret: Option<String>

Optional shared secret used to HMAC-SHA256 sign the webhook body (X-Leviath-Signature header) so the receiver can verify authenticity.

Persisted, because the daemon must still be able to sign a webhook for a run it reloaded after a restart. Never serve it - strip it with RunMeta::redacted before any of this struct leaves the process. See that method for what went wrong.

parent_run_id: Option<String>

Links sub-agent runs to their parent run.

children: Vec<String>

Run-ids of this agent’s direct sub-agents (sub-agent-tool spawns and fan-out workers). Persisted so the daemon can rebuild the exact parent→children tree on restart rather than reload children as orphans.

depth: usize

This agent’s depth in the sub-agent tree (0 for a top-level run). Persisted so a reloaded child enforces its remaining spawn-depth budget.

max_child_depth: usize

The sub-agent depth cap this agent imposes on its own children (0 when it has none). Restores SubAgentChildren::max_child_depth.

flags: RunFlags

Why this run may have produced nothing useful - see RunFlags.

yolo: bool

Whether the run was launched unattended (--yolo), so a daemon restart resumes it the way it was started.

This used to be dropped on reload, on the reasoning that forgetting a launch override can only prompt more, never less. In practice it meant a restart silently converted an unattended run into one parked on a prompt nobody was watching for - the operator’s own consent, given at launch, discarded by an implementation detail they never saw. Runs written before this field existed default to attended, so nothing is escalated retroactively.

read_paths: Option<ReadPathGrantCounts>

How much of the blueprint’s [read_paths] the config granted, as resolved at spawn. None for a blueprint that declared none, and for runs written before this field existed.

final_output: Option<FinalOutputDescriptor>

What the agent handed back, if it submitted anything: everything about the answer except the bytes.

This is the run’s answer, as distinct from error (why it failed) and from the stage logs (what it did along the way). The content itself is in a sidecar file beside this one, because this file is parsed for every run on every listing and must stay small no matter how long an answer is.

waiting_on: Option<WaitReason>

Why this run is parked, when it is. None on every other status, and on a run written before this field existed. Same vocabulary the live listing reports, so lev ps and a client reading this file describe a run the same way.

Additive on purpose: default means a meta.json from an older build still loads, and skip_serializing_if means a run that is not parked writes exactly the file it wrote before, so an older build reading a newer run sees nothing new either.

output_request: Option<OutputSpec>

The output shape this run was launched asking for, when the caller overrode the blueprint’s.

Persisted for the same reason yolo is: a daemon restart rebuilds the run’s spawn arguments from this file, and dropping the request would silently revert the run to the blueprint’s shape partway through. The caller asked once and should not have to ask again.

Implementations

impl RunMeta

pub fn redacted(&self) -> RunMeta

This run’s metadata with the webhook signing secret removed, for anything that leaves the process.

GET /api/agents, /api/agents/{id} and /api/agents/{id}/children all serialized RunMeta whole, so any holder of the API token could read every run’s callback_secret - the key that authenticates Leviath’s webhooks to their receivers. Mirrors the RedactedConfig pattern the /api/config handler already uses correctly.

Returns an owned copy rather than mutating in place so a caller cannot accidentally redact the record the daemon still needs for signing.

pub fn new( run_id: String, agent_name: String, agent_path: String, task: String, model: Option<String>, workdir: String, num_stages: usize, ) -> RunMeta

A newly accepted run: RunStatus::Starting, both timestamps now, every counter at zero and every optional field unset.

Only the seven values a caller genuinely knows at spawn are parameters. Everything else is filled in by the daemon as the run proceeds, so taking them here would invite a caller to invent a stage or a token count.

pub fn touch(&mut self)

Stamp updated_at with the current time.

Deliberately does not touch last_progress_at: the 30-second persistence heartbeat calls this, and a run that is wedged must not look like one that just moved. See RunMeta::last_progress_at.

Trait Implementations

impl Clone for RunMeta

fn clone(&self) -> RunMeta

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RunMeta

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RunMeta

fn deserialize<__D>( __deserializer: __D, ) -> Result<RunMeta, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for RunMeta

fn eq(&self, other: &RunMeta) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for RunMeta

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for RunMeta