Enum WorkflowEvent 

pub enum WorkflowEvent {
    Start {
        total_tasks: usize,
    },
    End {
        output: Value,
        duration: Duration,
        totals: WorkflowTotals,
    },
    TaskStart {
        task: String,
        on_error: Option<String>,
    },
    TaskEnd {
        task: String,
        output: Value,
        duration: Duration,
        usage: Option<TokenUsage>,
        variant: TaskEndVariant,
    },
    AgentChunk {
        task: String,
        agent: Option<String>,
        task_id: String,
        chunk: String,
    },
    ToolCallStart {
        task: String,
        tool: String,
        server: String,
        input: Value,
    },
    ToolCallEnd {
        task: String,
        tool: String,
        output: Value,
        duration: Duration,
    },
    Checkpoint {
        name: String,
        token: String,
        prompt: String,
        schema: Value,
        timeout_secs: Option<u64>,
        trigger: SuspendTrigger,
    },
    ToolApproval {
        token: String,
        tool_ref: String,
        args: Value,
        execution_id: Option<String>,
        node_id: Option<u64>,
    },
    Breakpoint {
        token: String,
        node_id: u64,
        env: HashMap<String, Value>,
    },
    Error {
        message: String,
        kind: ErrorKind,
        code: Option<String>,
    },
    ValidationFailure {
        task_name: String,
        attempt: u32,
        model_response: String,
        missing_fields: Vec<String>,
        extra_fields: Vec<String>,
        type_errors: Vec<String>,
        stop_reason: Option<String>,
    },
    RuntimeStart {
        task_name: String,
        runtime_name: String,
        language: String,
    },
    RuntimeStdout {
        task_name: String,
        chunk: String,
    },
    RuntimeStderr {
        task_name: String,
        chunk: String,
    },
    RuntimeEnd {
        task_name: String,
        exit_code: i32,
        duration_ms: u64,
    },
    RuntimeError {
        task_name: String,
        kind: String,
        message: String,
    },
    Other {
        type_name: String,
        payload: Value,
    },
}

A normalized, client-friendly engine event.

High-traffic variants (Start, End, TaskStart, TaskEnd, AgentChunk, ToolCallStart, ToolCallEnd, the three suspensions and Error) are typed with real fields. Everything else is collapsed into Other, which preserves the wire type name and the raw JSON payload so consumers can still inspect it.

Variants

Start

Fields

total_tasks: usize

End

Fields

output: Value

duration: Duration

totals: WorkflowTotals

Aggregate token + cost rollup across every TaskEnd in the workflow scope (issue #1173). Always present in the typed projection — when the upstream EngineEvent::WorkflowEnd carries the default WorkflowTotals (legacy bare-value wire shape, or a workflow that ran no TaskEnds), every field is zero. Consumers can pull total tokens off this without re-walking the per-task stream.

TaskStart

Fields

task: String

on_error: Option<String>

TaskEnd

Fields

task: String

output: Value

duration: Duration

usage: Option<TokenUsage>

variant: TaskEndVariant

How the task finished. Success for the ordinary path; Unable when the agent emitted a canonical {"unable": ...} envelope and the flow’s on unable <target> trailer (or default fail) took over. Unknown is the forward-compat catch-all for variants a newer akribes-core might add — see TaskEndVariant.

AgentChunk

Fields

task: String

agent: Option<String>

task_id: String

chunk: String

ToolCallStart

Fields

task: String

tool: String

server: String

input: Value

ToolCallEnd

Fields

task: String

tool: String

output: Value

duration: Duration

Checkpoint

Fields

name: String

token: String

prompt: String

schema: Value

timeout_secs: Option<u64>

trigger: SuspendTrigger

Why the engine suspended. DagPosition for a plain checkpoint cp(...) call site; ValidationExhausted / AgentUnable when a task-level gate routed here; Unknown for discriminants added in a newer akribes-core the SDK doesn’t yet know about (forward-compat; see crate::suspend).

ToolApproval

Fields

token: String

tool_ref: String

args: Value

execution_id: Option<String>

node_id: Option<u64>

Breakpoint

Fields

token: String

node_id: u64

env: HashMap<String, Value>

Error

Fields

message: String

kind: ErrorKind

code: Option<String>

Stable diagnostic code (e.g. "AKRIBES-E-SCRIPT-DEPTH"). Mirrored from akribes_types::event::EngineEvent::Error.code. None on legacy errors without a registered code (#429).

ValidationFailure

A structured-output task’s response failed validation. Mirrors akribes_types::event::EngineEvent::ValidationFailure. Emitted in addition to the existing Log line so consumers without this variant still render the human-readable summary, but tooling that knows about the variant can render the model’s actual response, the schema-validator’s structured error breakdown, and the provider’s stop_reason (so e.g. a max_tokens truncation isn’t misdiagnosed as “schema overflow” — see issue #320).

Fields

task_name: String

attempt: u32

1-indexed attempt number.

model_response: String

Raw text / JSON the validator saw, exactly as the model emitted.

missing_fields: Vec<String>

JSON-pointer paths to required fields the schema validator flagged as absent.

extra_fields: Vec<String>

Paths to fields rejected by additionalProperties: false.

type_errors: Vec<String>

Human-readable type / value mismatches (e.g. "expected string, got null at /name").

stop_reason: Option<String>

Provider’s stop_reason when known. None for streaming paths that don’t surface usage.

RuntimeStart

A runtime block began dispatching to the sandbox executor. Mirrors EngineEvent::RuntimeStart. task_name matches the wrapping task’s name so reducers that group by task continue to work; runtime_name is the source-declared block name.

Fields

task_name: String

runtime_name: String

language: String

"python" | "bash" | "node" | "rust" | "java". Free-form string on the wire so a future language doesn’t require an SDK release.

RuntimeStdout

One chunk of stdout from a running runtime block. Many may fire per invocation; consumers should accumulate.

Fields

task_name: String

chunk: String

RuntimeStderr

One chunk of stderr from a running runtime block.

Fields

task_name: String

chunk: String

RuntimeEnd

A runtime block completed (the executor returned an ExecResult). A non-zero exit_code is still a RuntimeEnd — infrastructure failures (timeout / OOM / unreachable sandbox) emit Self::RuntimeError instead.

Fields

task_name: String

exit_code: i32

duration_ms: u64

RuntimeError

A runtime block failed to complete. kind is a stable wire string mirroring the engine’s RuntimeError enum (NotConfigured / Timeout / SandboxUnavailable / OomKilled / Internal); use crate::runtime::RuntimeErrorKind::from_wire to pattern-match without re-parsing the string.

Fields

task_name: String

kind: String

message: String

Other

Catch-all for variants that don’t need dedicated fields in the SDK: StateUpdate, Log, NodeStart, NodeEnd, Resumed, BreakpointResumed, McpServerDegraded, McpServerRecovered, TaskPrompt, VerificationStart, VerificationResult.

Preserves the original wire type name and JSON payload for consumers who want to reach in and pick them apart.

Fields

type_name: String

payload: Value

Implementations

impl WorkflowEvent

pub fn category(&self) -> EventCategory

Coarse routing category for this event.

impl WorkflowEvent

pub fn from_envelope_json(value: Value) -> Result<Self, EnvelopeDecodeError>

Decode a raw {type, payload} JSON envelope into a typed WorkflowEvent.

Tries the Runtime* decoder first (5 canonical types from crates/akribes-core/src/event.rs). If the envelope’s "type" is not one of those, it falls back to deserialising the JSON as EngineEvent and routing through the existing From<EngineEvent> projection.

Returns EnvelopeDecodeError::Engine if both paths fail. The runtime decoder only errors when the "type" was a runtime tag but the payload shape was wrong — that surfaces as EnvelopeDecodeError::Runtime and is not retried via the engine path (a payload-shape mismatch on a known runtime tag is the only way the runtime arm could be lossy, so we surface it explicitly).

Trait Implementations

impl Clone for WorkflowEvent

fn clone(&self) -> WorkflowEvent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for WorkflowEvent

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

Formats the value using the given formatter.

impl From<EngineEvent> for WorkflowEvent

fn from(evt: EngineEvent) -> Self

Converts to this type from the input type.

impl From<RuntimeEvent> for WorkflowEvent

fn from(evt: RuntimeEvent) -> Self

Converts to this type from the input type.