Struct ExecResult 

#[non_exhaustive]
pub struct ExecResult {
    pub code: i64,
    pub data_is_value: bool,
    pub err: String,
    pub data: Option<Value>,
    pub did_spill: bool,
    pub original_code: Option<i64>,
    pub content_type: Option<String>,
    pub baggage: BTreeMap<String, String>,
    /* private fields */
}

The result of executing a command or pipeline.

$? in script syntax is the POSIX exit code (an integer). To read the previous command’s structured .data (or its captured stdout) from inside a script, use the kaish-last builtin and pipe / capture its output. Inside Rust callers, read .data, .text_out(), etc. directly.

Notes on the fields:

• code — exit code (0 = success)
• err — error message if failed
• out — raw stdout as string
• data — structured data; only set by builtins/tools that opt in (e.g. seq, jq, cut, find, glob, split). External commands never populate this — pipe their stdout through jq to get it.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

code: i64

Exit code. 0 means success.

data_is_value: bool

Whether Self::data is this result’s VALUE rather than a structured view of the text it printed. Stamped by the dispatcher from the tool’s crate::tool::ToolSchema::typed_substitution; a command substitution binds data only when this is set, while --json and the pipeline’s structured sideband read data regardless.

err: String

Raw standard error as a string.

Line contract: empty, or ends with exactly one \n — every diagnostic kaish mints ends its own line (#363), so renderers print err verbatim. Two deliberate exceptions carry unterminated text: a read -p prompt and stdout folded into stderr by 1>&2 — both stay byte-faithful, as bash does. External-command stderr is pass-through data too; the contract covers kaish’s own messages.

data: Option<Value>

Structured data — only populated when a builtin/tool sets it explicitly. Stdout is never sniffed; this stays None for external commands.

did_spill: bool

True if output was capped and lost data. Either the output limiter spilled the overflow to disk (the out message carries the path), truncated it in memory (Memory spill mode — head+tail only, no recoverable file), or an external command’s stdout overflowed its fixed-size capture ring with output limiting off (GH #191) — the capture buffer evicted its head with no spill file at all. All cases remap the exit code to 3.

original_code: Option<i64>

The command’s original exit code before spill logic overwrote it with 2 or 3. Present only when did_spill is true and code was changed.

content_type: Option<String>

MIME content type hint (e.g., “text/markdown”, “image/svg+xml”). When set, downstream consumers can use this instead of sniffing content.

baggage: BTreeMap<String, String>

Opaque key-value context propagated from tools through execution. Intermediaries (kaish) carry but don’t interpret. Consumers read known keys. Follows W3C Baggage semantics — useful for OTel trace propagation, application-level hints, etc.

Implementations

impl ExecResult

pub fn terminate_diagnostic(message: impl Into<String>) -> String

End a kaish diagnostic on its own line: empty stays empty; anything else ends with exactly one \n.

stderr is line-oriented. A diagnostic kaish mints must terminate its own line, or whatever renders next fuses onto it (#363). The constructors call this; apply it to any message assigned to err directly.

pub fn success(out: impl Into<String>) -> ExecResult

Create a successful result with output.

pub fn with_output(output: OutputData) -> ExecResult

Create a successful result with structured output data.

The OutputData is the source of truth. Text is materialized lazily via text_out() when needed (pipes, redirects, command substitution).

pub fn success_bytes(bytes: Vec<u8>) -> ExecResult

Create a successful result whose stdout is raw bytes (binary payload).

pub fn success_text_or_bytes(bytes: Vec<u8>) -> ExecResult

Create a successful result from bytes, applying the coercion rule at the producer: valid UTF-8 becomes a text result, anything else a binary Bytes result. This is the single place pass-through/decoder builtins (cat, head -c, base64 -d, xxd -r, tee, …) decide text-vs-binary, so text workflows stay text and only real binary flows as bytes.

pub fn success_data(data: Value) -> ExecResult

Create a successful result with structured data.

pub fn success_with_data(out: impl Into<String>, data: Value) -> ExecResult

Create a successful result with both text output and structured data.

Use this when a command should have:

• Text output for pipes and traditional shell usage
• Structured data for iteration and programmatic access

The data field takes precedence for command substitution in contexts like for i in $(cmd) where the structured data can be iterated.

pub fn failure(code: i64, err: impl Into<String>) -> ExecResult

Create a failed result with an error message.

The message is normalized to the stderr line contract: it ends with exactly one newline (unless empty), so renderers print it verbatim.

pub fn from_output( code: i64, stdout: impl Into<String>, stderr: impl Into<String>, ) -> ExecResult

Create a result from raw output streams.

data is left empty — kaish does not sniff stdout for JSON. To get structured iteration from an external command, pipe through jq: for i in $(curl ... | jq .); do ....

pub fn with_output_and_text( output: OutputData, text: impl Into<String>, ) -> ExecResult

Create a successful result with structured output and explicit pipe text.

Use this when a builtin needs custom text formatting that differs from the canonical OutputData::to_canonical_string() representation.

pub fn from_parts( code: i64, out: String, err: String, data: Option<Value>, ) -> ExecResult

Create a result from parts — for kernel struct literal sites.

pub fn with_code(self, code: i64) -> ExecResult

Builder: set the exit code, returning self for chaining.

pub fn text_out(&self) -> Cow<'_, str>

Get text output, materializing from OutputData on demand.

Returns the text payload if non-empty, otherwise falls back to OutputData::to_canonical_string(). This is the canonical way to get text for pipes, command substitution, and file redirects.

Binary payloads decode lossily here (U+FFFD for invalid UTF-8). Several builtins already produce a Bytes payload (cat/head/tail/ base64 -d/xxd -r/dd/tee/external commands), so this lossy path IS reachable — callers that need to catch binary rather than silently mangle it should use Self::try_text_out instead, which loud-errors with BinaryNotText on invalid UTF-8. See docs/binary-data.md.

pub fn try_text_out(&self) -> Result<Cow<'_, str>, BinaryNotText>

Get text output, or a BinaryNotText error if the payload is binary and not valid UTF-8. This is the boundary guard for text sinks (echo, interpolation, $() capture) — adopted as those paths grow byte awareness (Phase 2). Valid-UTF-8 bytes coerce; everything else is loud.

pub fn out_bytes(&self) -> Option<&[u8]>

Raw bytes if this result carries a binary payload, else None.

pub fn is_bytes(&self) -> bool

True if the stdout payload is raw bytes rather than text.

pub fn output(&self) -> Option<&OutputData>

Get a reference to structured output data.

pub fn has_output(&self) -> bool

True if structured output data is present.

pub fn set_out(&mut self, s: String)

Replace .out with text.

pub fn set_out_bytes(&mut self, b: Vec<u8>)

Replace .out with raw bytes (binary payload).

pub fn push_out(&mut self, s: &str)

Append text to .out. A binary payload is appended to as raw UTF-8 bytes.

pub fn clear_out(&mut self)

Clear .out back to empty text.

pub fn clear_stdout(&mut self)

Drop every representation of stdout: the text .out, the structured .output, and the data-plane .data sideband. Used when a stdout redirect (> file, >> file, &> file, 1>&2) has consumed the command’s output — the bytes went to the file (or stderr), so nothing flows onward to a pipe, a $(...) capture, or the .data sideband. Clearing all three together keeps them from drifting: a redirect that cleared .out/.output but left .data would leak structured data past its own redirect (x=$(fromjson … > file) capturing the value instead of "").

stdout, so a redirect can’t drop it — rm precious > log still gates.

pub fn set_output(&mut self, o: Option<OutputData>)

Replace .output.

pub fn take_output(&mut self) -> Option<OutputData>

Take .output, leaving None.

pub fn materialize(&mut self)

Materialize: if .out is empty and .output is present, populate .out from canonical string and clear .output.

pub fn take_output_for_stream(&mut self) -> Option<OutputData>

Take .output only if .out is empty (no custom text), so caller can stream directly without materializing.

pub fn ok(&self) -> bool

True if the command succeeded (exit code 0).

pub fn with_content_type(self, ct: impl Into<String>) -> ExecResult

Set content type hint, returning self for chaining.

Trait Implementations

impl Clone for ExecResult

fn clone(&self) -> ExecResult

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ExecResult

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

Formats the value using the given formatter.

impl Default for ExecResult

fn default() -> ExecResult

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ExecResult

fn deserialize<__D>( __deserializer: __D, ) -> Result<ExecResult, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<ExecResult> for ToolResult

fn from(exec: ExecResult) -> ToolResult

Converts to this type from the input type.

impl From<ExecResult> for ControlFlow

fn from(result: ExecResult) -> Self

Converts to this type from the input type.

impl From<ToolResult> for ExecResult

fn from(result: ToolResult) -> ExecResult

The symmetric peer of From<ExecResult> for ToolResult above — every field that direction preserves, this direction must preserve too, or a backend-registered tool’s structured data/content_type/baggage silently vanishes crossing back into the kernel (the embedder seam: x=$(embedder_tool) and for r in $(embedder_tool) need .data to see typed results, not just stdout text).

data uses json_to_value_no_envelope rather than the internal round-trip conversion: a backend tool’s JSON is external input, so an object shaped like the byte envelope must stay a plain record, never silently auto-decode to Value::Bytes.

impl PartialEq for ExecResult

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for ExecResult

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ExecResult