Skip to content

Results and traces

RunResult

Bases: BaseModel

The state of a run: its status, output or error, usage, cost and trace.

ok property 

ok: bool

Whether the run completed.

RunStatus

Bases: StrEnum

Where a run is in its lifecycle (DESIGNS No. 18).

RunEvent

Bases: BaseModel

Progress of a run, as yielded by harness.stream(run_id).

status and approval events are kept in the state store's event log; trace and chunk events are only delivered live.

RunTrace 

RunTrace(
    clock: Clock,
    *,
    events: tuple[TraceEvent, ...] = (),
    on_event: Callable[[TraceEvent], None] | None = None,
)

An append-only list of TraceEvent for one run.

on_event is called with each new event, so a harness can stream them live.

hook 

hook(
    hook: HookPoint,
    source: str,
    outcome: Outcome,
    *,
    middleware: int,
) -> TraceEvent

Record that hook fired, from source, and the combined outcome.

outcome 

outcome(
    hook: HookPoint,
    source: str,
    band: Band | None,
    outcome: Outcome,
) -> TraceEvent

Record a middleware's answer to a hook event.

failure 

failure(
    hook: HookPoint,
    source: str,
    band: Band | None,
    outcome: Outcome,
    *,
    error_type: str,
    timed_out: bool,
) -> TraceEvent

Record a middleware that raised or timed out, and the outcome its fail mode chose.

Only the exception's type is recorded: its message may hold raw content (R9).

note 

note(
    source: str,
    reason: str,
    *,
    hook: HookPoint | None = None,
    code: str | None = None,
    outcome: OutcomeKind | None = None,
    details: dict[str, JsonValue] | None = None,
) -> TraceEvent

Record a framework event, such as a budget check or a status change.

for_hook 

for_hook(hook: HookPoint) -> list[TraceEvent]

Events recorded for one hook point, in order.

hooks_fired 

hooks_fired() -> list[HookPoint]

Hook points that appear in the trace, in the order they first appear.

TraceEvent

Bases: BaseModel

One entry in a RunTrace.

TraceKind

Bases: StrEnum

What a trace event records.

HOOK class-attribute instance-attribute 

HOOK = 'hook'

A hook point fired. outcome is the combined result of its middleware.

OUTCOME class-attribute instance-attribute 

OUTCOME = 'outcome'

A middleware answered a hook event.

FAILURE class-attribute instance-attribute 

FAILURE = 'failure'

A middleware raised or timed out; its fail mode decided the outcome.

NOTE class-attribute instance-attribute 

NOTE = 'note'

A framework event: a budget check, a status change, a decision, a shadow guard.