Enum CoderEventKind 

pub enum CoderEventKind {
    StateChanged {
        from: String,
        to: String,
    },
    ContractProposed {
        contract: OutcomeContract,
    },
    EngineSelected {
        engine: String,
        reason: String,
    },
    EngineFallback {
        from: String,
        to: String,
        reason: String,
    },
    ModelFallback {
        from: String,
        to: String,
        reason: String,
    },
    IterationStarted {
        n: u32,
        max: u32,
    },
    InferenceWaiting {
        elapsed_secs: u64,
    },
    OperatorGuidance {
        text: String,
        status: String,
    },
    InferenceRetry {
        model: String,
        attempt: u32,
        reason: String,
        backoff_ms: u64,
    },
    AuthRequired {
        message: String,
        wait_secs: u64,
    },
    BudgetExhausted {
        reason: String,
        elapsed_secs: u64,
        iterations: u32,
    },
    InvocationRetried {
        hypothesis: u32,
        reason: String,
        retries_remaining: u32,
    },
    PlanText {
        text: String,
    },
    ToolCall {
        tool: String,
        params_preview: String,
    },
    ToolResult {
        tool: String,
        ok: bool,
        preview: String,
    },
    CheckStarted {
        name: String,
    },
    CheckCompleted {
        result: CheckResult,
    },
    ContractBaseline {
        results: Vec<CheckResult>,
        gates_nothing: bool,
    },
    ExternalEvent {
        raw: Value,
    },
    FindingProposed {
        finding: NoChangeFinding,
    },
    FindingResolved {
        accepted: bool,
        comment: Option<String>,
    },
    DiffReady {
        stat: String,
        patch: String,
        patch_truncated: bool,
        patch_full_bytes: usize,
        changed_paths: usize,
        contract_overlap: Vec<CheckOverlap>,
        overlap_disclosure: Option<String>,
    },
    UserInputRequested {
        prompt: String,
    },
    UserInputExpired {
        prompt: String,
        waited_secs: u64,
    },
    ContractRevisionRejected {
        request: String,
        reason: String,
    },
    MergeCompleted {
        branch: String,
    },
    Error {
        message: String,
    },
}

What happened. Serialized with "type": "snake_case_name" for WS clients.

Variants

StateChanged

Fields

from: String

to: String

ContractProposed

Fields

contract: OutcomeContract

EngineSelected

Fields

engine: String

reason: String

EngineFallback

Fields

from: String

to: String

reason: String

ModelFallback

The preferred inference lane was skipped and a different model served the call. Distinct from EngineFallback, which is about the coder ENGINE (native vs an external CLI), not the model behind it.

Emitted at most once per PHASE — contract derivation, each contract revision, and the run loop announce independently, and a session that degrades in more than one of them emits more than one. The guard is against narrating every routing decision inside a phase, not against a second phase reporting a degrade the operator has not seen resolved.

Fields

from: String

The lane that was skipped.

to: String

The model that actually served the call.

reason: String

Why, in words an operator can act on.

IterationStarted

Fields

n: u32

max: u32

InferenceWaiting

A native model call is still pending; not evidence of tool execution.

Fields

elapsed_secs: u64

OperatorGuidance

Status: queued, applied (included in the next turn), or not_applied.

Fields

text: String

status: String

InferenceRetry

Sanitized provider retry metadata from the inference engine.

Fields

model: String

attempt: u32

reason: String

backoff_ms: u64

AuthRequired

The run is blocked on sign-in and is waiting for the human, rather than failing. Not terminal: if a credential appears within wait_secs the session resumes from where it stopped, worktree intact.

Distinct from Error on purpose. A client should surface this as an action the user can take (“sign in to continue”), because it is the one failure mode a person standing at the machine can clear in seconds — and previously it read as no inference backend is available, which points at models and accounts instead of at the sign-in it actually needs.

Fields

message: String

The underlying auth error, for diagnosis.

wait_secs: u64

How long the session will wait before giving up.

BudgetExhausted

The session hit its wall-clock ceiling and the next iteration was not admitted. Terminal, and the session ends Failed — it never reaches the merge gate, which requires green checks. The worktree IS retained for postmortem (the budget path forces keep_workspace_on_failure), so the partial work survives on disk at workspace_path.

Fields

reason: String

Human-readable, naming both the elapsed time and the ceiling.

elapsed_secs: u64

iterations: u32

Iterations completed before the ceiling was reached.

InvocationRetried

A worker invocation died mid-run (timeout / I/O) with the contract still red, and the same hypothesis is being re-invoked.

Distinct from IterationStarted on purpose: a retry costs no hypothesis, so folding it in would make that event’s n/max misreport the budget. A chronically flaky CLI is otherwise indistinguishable from a fast clean one in the A/B’s wall-clock.

Fields

hypothesis: u32

The hypothesis being retried (IterationStarted.n).

reason: String

Transport error that ended the invocation.

retries_remaining: u32

Transient retries left for this session.

PlanText

Fields

text: String

ToolCall

Fields

tool: String

params_preview: String

ToolResult

Fields

tool: String

ok: bool

preview: String

CheckStarted

Fields

name: String

CheckCompleted

Fields

result: CheckResult

ContractBaseline

The contract evaluated against the unmodified worktree at session start (car#707). Distinct from CheckStarted/CheckCompleted, which mean “the contract is being evaluated on the work” — replaying those for a baseline would show checks going green before a line was written. gates_nothing is true when every check already passed, i.e. the contract verifies nothing for this task.

Fields

results: Vec<CheckResult>

gates_nothing: bool

ExternalEvent

Fields

raw: Value

FindingProposed

The loop nominated a “no code should change” conclusion. A nomination, not a verdict: the runtime decides what happens next.

Fields

finding: NoChangeFinding

FindingResolved

A nominated finding was accepted or rejected.

Fields

accepted: bool

comment: Option<String>

DiffReady

Fields

stat: String

patch: String

The patch body, tail-capped to the configured budget. Named for what it is; patch_truncated (the bool) says whether it is partial.

patch_truncated: bool

True when patch is a tail. A UI must be able to say “you are approving against a partial diff” without string-matching the …[truncated]… marker (car#706).

patch_full_bytes: usize

Size of the untruncated patch.

changed_paths: usize

How many distinct paths the diff touches. Named paths, not files, because a rename contributes BOTH of its endpoints — one file moved is two paths touched, and for a reviewer asking “what did this session reach into” that is the honest number. stat carries it too, but only as prose a client must parse; scope explosion is what a reviewer most needs stated plainly before deciding whether to read the patch at all.

contract_overlap: Vec<CheckOverlap>

Contract checks whose commands execute a path this diff modified. Disclosure, never denial: editing tests is frequently the task, and the human at the gate is who should judge which case this is.

overlap_disclosure: Option<String>

The rendered disclosure sentence, or None when nothing overlaps.

On the wire so every surface prints the SAME words. Hand-rolling it per renderer had already lost “that is often legitimate” from both the CLI and the host app while the log kept it — dropping the non-accusatory half of a sentence whose entire design posture is disclosure rather than accusation, and leaving the only tested copy the one no human reads. contract_overlap stays alongside it for machine consumers that want the structure.

UserInputRequested

Fields

prompt: String

UserInputExpired

The mid-session question’s answer window closed server-side without an answer. The loop carried on without one; the prompt is DEAD.

Its own event because a client has no other way to learn: the gate simply stops being pending, which is a state a board can only discover by asking again. Without this, a board kept rendering the question as live — and counting it under “needs you” — until the operator happened to refresh. It is also what drives the coder.session_changed fanout that drops needs_you back to null.

Fields

prompt: String

The question that went unanswered, so a client can match it to the prompt it is showing.

waited_secs: u64

How long the daemon waited.

ContractRevisionRejected

A coder.revise_contract request could NOT be honored: the redraft did not validate, or the request was not expressible as checks. The session stays at the gate with the PREVIOUS contract intact.

Its own event rather than a generic Error because the operator needs to know the contract they are still looking at is the old one — a revision that silently passes as applied is the failure mode this exists to make impossible.

Fields

request: String

The operator’s plain-English request, verbatim.

reason: String

Why it could not be honored (the derivation/validation failure).

MergeCompleted

Fields

branch: String

Error

Fields

message: String

Trait Implementations

impl Clone for CoderEventKind

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 CoderEventKind

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for CoderEventKind

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for CoderEventKind

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

where __S: Serializer,

Serialize this value into the given Serde serializer.