Struct ExecuteOptions 

pub struct ExecuteOptions {
    pub vars: HashMap<String, Value>,
    pub timeout: Option<Duration>,
    pub cancel_token: Option<CancellationToken>,
    pub cwd: Option<PathBuf>,
    pub traceparent: Option<String>,
    pub tracestate: Option<String>,
    pub baggage: BTreeMap<String, String>,
    pub stdin: Option<Vec<u8>>,
    pub interrupt: Option<Arc<dyn Fn() -> bool + Send + Sync>>,
    pub errexit: Option<bool>,
}

Per-call options for Kernel::execute_with_options.

Construct with ExecuteOptions::new() and the chainable with_* builders, or via Default.

Cancellation vs. timeout — embedder note

If a cancel_token is supplied, it is raced against the kernel’s internal token. The kernel does NOT cancel the embedder’s token on its own timeouts — it cancels its internal token and returns exit code 124. So your_token.is_cancelled() after the call returns reflects only whether you (or someone sharing your token) cancelled, not whether the kernel timed out. Distinguish via the returned ExecResult.code: 124 = kernel timeout, 130 = cancellation (Ctrl-C / Kernel::cancel).

Fields

vars: HashMap<String, Value>

Variables exported into this call’s environment (per-call overlay).

timeout: Option<Duration>

Per-call timeout. Overrides KernelConfig::request_timeout.

None means no timeout (or whatever the kernel-config default is). Some(Duration::ZERO) returns exit 124 immediately without spawning anything — useful for tests and dry-run paths. Any other Some(d) lets the kernel run for at most d before cancelling (which kills external children with the configured grace) and returning 124.

cancel_token: Option<CancellationToken>

Optional externally-owned cancellation token, raced against the kernel’s internal token. Either firing cancels the request and kills any running external children. The kernel does not store this token in its own state — it’s a per-call read-only input, so embedders are free to drop or reuse the original token after the call returns. CancellationToken is internally Arc-shared, so clone() it into the builder if you want to keep your original handle.

cwd: Option<PathBuf>

Per-call working directory override.

When Some(path), the kernel runs this call as if cd path happened first, then restores the prior cwd on return. Useful for embedders that run scripts in workspace contexts (notebook cells, per-tool dirs) without polluting the long-lived kernel’s cwd.

traceparent: Option<String>

W3C traceparent of the embedder’s active span, e.g. "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01". When set, the kernel’s execution span parents onto it, so kaish’s spans appear as children of the embedder’s trace rather than as orphan roots.

tracestate: Option<String>

W3C tracestate (vendor-specific list) that rides alongside traceparent. Per the W3C spec, tracestate is meaningless without a traceparent, so the kernel ignores it unless traceparent is also set.

baggage: BTreeMap<String, String>

W3C baggage — cross-cutting identifiers (owner, connection, tenant, …) the embedder wants stamped onto the trace. Propagated to every child span. Independent of traceparent: baggage with no trace context starts a fresh root that still carries the identifiers.

stdin: Option<Vec<u8>>

Standard input for this call, seeded to the first top-level command that reads stdin. A command that consumes less than the whole buffer (read, a pipeline stage that never reads stdin) leaves the remainder for the next statement in the same call — it is not drained wholesale to the first reader.

Lets a non-interactive frontend feed piped input, e.g. printf '…' | kaish -c 'sort'. Without it a bare top-level builtin reading stdin has no input source and silently produces nothing. Bytes-typed (GH #176) to match ExecContext::set_stdin: a byte-aware builtin (wc -c, cat, cmp, checksum, …) sees binary content exactly, while a text-only builtin (grep, sed, …) still refuses it loudly at the point it asks for text (read_stdin_to_text), not here. Embedders that already hold a complete buffer use this; one that wants to avoid pre-draining an open process stdin should prefer Kernel::execute_with_pipe_stdin instead.

interrupt: Option<Arc<dyn Fn() -> bool + Send + Sync>>

Polled interrupt check, for embedders whose thread cannot fire cancel_token while execution runs — the motivating case is single-threaded wasm, where the browser’s main thread flips a SharedArrayBuffer flag and this closure reads it. The kernel polls at its cancellation checkpoints (each loop iteration, among others) and, on true, fires its internal cancel — the same exit-130 path as Kernel::cancel(). Keep the closure cheap: it runs on the hot path. None (the default) polls nothing.

errexit: Option<bool>

Per-call override for errexit (set -e): abort on a statement’s first nonzero exit instead of continuing to the next one.

Precedence: Some(enabled) wins over KernelConfig::errexit_enabled for this call only, and is restored to whatever the kernel already had (the config default, or a prior call’s set -e/set +e) when the call returns. None (the default) leaves errexit exactly as the kernel already has it — no override, no restore. Either way, a set -e / set +e the script itself runs still applies for the rest of that call: this and the config default only pick the starting value of the one piece of state (Scope::error_exit) that set -e also mutates, so set -o always reports the true, single answer.

Use this to run one call (e.g. a security/gating hook) with errexit on while the kernel’s other calls keep the shell-standard default off.

Implementations

impl ExecuteOptions

pub fn new() -> Self

pub fn with_vars(self, vars: HashMap<String, Value>) -> Self

Replace the entire vars overlay with the given map.

pub fn with_var(self, name: impl Into<String>, value: Value) -> Self

Add a single variable to the overlay (extending; last write wins).

pub fn with_interrupt(self, check: Arc<dyn Fn() -> bool + Send + Sync>) -> Self

Install a polled interrupt check (see the interrupt field).

pub fn with_timeout(self, timeout: Duration) -> Self

pub fn with_cancel_token(self, token: CancellationToken) -> Self

pub fn with_cwd(self, cwd: PathBuf) -> Self

Run this call as if cd path had happened first; the prior cwd is restored on return.

pub fn with_traceparent(self, traceparent: impl Into<String>) -> Self

Set the W3C traceparent the kernel’s execution span should parent onto.

pub fn with_tracestate(self, tracestate: impl Into<String>) -> Self

Set the W3C tracestate that rides alongside traceparent. Ignored by the kernel unless a traceparent is also present.

pub fn with_baggage(self, baggage: BTreeMap<String, String>) -> Self

Replace the entire baggage map with the given identifiers.

pub fn with_baggage_entry( self, key: impl Into<String>, value: impl Into<String>, ) -> Self

Add a single baggage identifier (extending; last write wins).

pub fn with_stdin(self, stdin: impl Into<Vec<u8>>) -> Self

Set the standard input fed to this call, starting with the first stdin-reading command; whatever a command doesn’t consume carries forward to the next one in the same call.

Accepts anything Into<Vec<u8>> — a &str/String (the common text case) or a raw Vec<u8> (binary, GH #176) both work.

pub fn with_errexit(self, enabled: bool) -> Self

Force errexit on or off for this call only, overriding KernelConfig::errexit_enabled. See the errexit field doc for exact precedence and restore behavior.

Trait Implementations

impl Clone for ExecuteOptions

fn clone(&self) -> ExecuteOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for ExecuteOptions

fn default() -> ExecuteOptions

Returns the “default value” for a type.