Struct RunRecord 

pub struct RunRecord {

    pub run: RunId,
    pub itinerary: ItineraryId,
    pub agent: AgentName,
    pub pipeline: Option<PipelineName>,
    pub model: Option<String>,
    pub outcome: Outcome,
    pub started_at: Timestamp,
    pub finished_at: Option<Timestamp>,
    pub usd: f64,
    pub source: CostSource,
    pub usage: TokenUsage,
    pub detail: Option<String>,
    pub blocked_on: Option<String>,
    pub pid: Option<u32>,
}

One supervised CLI execution, as recorded in history.

Serialised one per line as JSON. Field names are the wire format: renaming one silently orphans every record already on disk, so treat them as an API.

Fields

run: RunId

The run.

itinerary: ItineraryId

The chain it belonged to.

agent: AgentName

Which agent was run.

pipeline: Option<PipelineName>

The pipeline that started the chain, when one did.

model: Option<String>

Which model, when the runner said.

outcome: Outcome

How it ended.

started_at: Timestamp

When it started.

finished_at: Option<Timestamp>

When it ended, or None while it is still going.

usd: f64

Cost in US dollars.

source: CostSource

Where usd came from.

usage: TokenUsage

Tokens consumed, as far as they are known.

detail: Option<String>

Why it ended, for the outcomes where that is not obvious.

blocked_on: Option<String>

What the run could not get past, when it asked for help.

Present whether or not the run succeeded, because the two are independent: an agent can finish its task and still have been unable to check something. Without this a blocked run looks exactly like a clean one on a list, which is the failure mode a lights-out factory can least afford — the detail lives with the help request, and this is the one line that makes the run worth opening.

pid: Option<u32>

The operating system process id, while the run is live.

Recorded so that a Tower coming back from a restart can check whether the process is still there rather than assume. A child routinely outlives the parent that spawned it on Windows, and recovering beside a process that never stopped duplicates its work — see crate::handover::ChildState.

A recycled process id can make a dead run look alive, which fails towards refusing to recover. That is the safe direction: stalled work is visible, duplicated work is not.

Implementations

impl RunRecord

pub fn started( run: RunId, itinerary: ItineraryId, agent: AgentName, started_at: Timestamp, ) -> Self

Records a run that has just started.

pub fn from_pipeline(self, pipeline: PipelineName) -> Self

Attributes the run to the pipeline that started its chain.

pub fn using_model(self, model: impl Into<String>) -> Self

Notes which model the runner used.

pub fn finished(self, outcome: Outcome, at: Timestamp) -> Self

Closes the run out with an outcome and a finishing time.

pub fn costing(self, usd: f64, source: CostSource, usage: TokenUsage) -> Self

Attaches what the run cost.

pub fn because(self, detail: impl Into<String>) -> Self

Explains an outcome that is not self-evident.

pub fn blocked_on(self, summary: impl Into<String>) -> Self

Notes that the run asked for help, and what about.

pub fn needed_help(&self) -> bool

Returns true when the run reported something in its way.

pub fn with_pid(self, pid: u32) -> Self

Notes the process id, so a later Tower can check whether it is still running.

pub fn duration_secs(&self) -> Option<i64>

How long the run took, in whole seconds, or None while it is still going.

Returns None rather than a negative number if the clock went backwards between the two readings, which NTP correction can do: a negative duration on a dashboard is worse than an absent one, because somebody will average it.

pub fn filed_at(&self) -> Timestamp

The instant this record should be filed under.

Runs are filed by when they finished, matching the cost ledger, so that a total for a period covers the runs whose money landed in it. A long run started before a window and finished inside it belongs to the window it was paid for.

Trait Implementations

impl Clone for RunRecord

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RunRecord

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RunRecord

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for RunRecord

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for RunRecord

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for RunRecord