Trait Beholder

Source

pub trait Beholder: Send {
    // Required methods
    fn name(&self) -> &'static str;
    fn version(&self) -> &'static str;
    fn mode(&self) -> BeholderMode;
    fn parse_chunk(&mut self, chunk: &OutputChunk) -> Vec<Event>;

    // Provided methods
    fn on_done(&mut self, _run_id: &TaskRunId, _offset_ms: u32) -> Vec<Event> { ... }
    fn unknown_format_reason(&self) -> Option<&str> { ... }
}

Expand description

Per-run stateful chunk processor.

The instance is private to a single TaskRun. parse_chunk is called for every captured chunk in arrival order and may produce zero or more structured events. Implementations must be incremental — buffering everything to EOF defeats the lossless-during-execution property.

For tools that dump a single JSON document at exit (e.g. ESLint, Biome), implement parse_chunk as a simple buffer accumulator and do all parsing in on_done, which the driver calls once the PTY reader exits.

Required Methods§

Source

fn parse_chunk(&mut self, chunk: &OutputChunk) -> Vec<Event>

Extract structured events from one output chunk.

Provided Methods§

Source

fn on_done(&mut self, _run_id: &TaskRunId, _offset_ms: u32) -> Vec<Event>

Called once after the last chunk has been delivered (PTY EOF).

Use this for tools that write a single JSON document at exit rather than streaming line-by-line. The driver passes the run id and a final timestamp so the returned events can be fully populated.

Default: returns no events (correct for streaming beholders).

Source

fn unknown_format_reason(&self) -> Option<&str>

Returns a reason string if the beholder detected that the tool’s output format is unrecognized (schema drift). When Some, the driver detaches this beholder and updates beholder_status to unknown_format:name.

Default: None — format OK or not yet probed.