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>,
}

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.

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_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).

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.