CommandExecutor

Category: Shell Execution

Source: command_executor.dart

Classes

CaptureResult

The captured output of a completed shell command.

Constructor

CaptureResult({
    required this.exitCode,
    required this.stdout,
    required this.stderr,
    this.runtimeId = 'host',
    this.sessionId,
  })

Properties

Property	Type	Description
exitCode	int
stdout	String
stderr	String
runtimeId	String	Identifier of the runtime that ran this command (e.g. 'host', 'docker', 'daytona'). Used by the SessionEvent layer to label runtime command events. Defaults to 'host' so existing call sites that don't yet thread this through still work.
sessionId	String?	Session this command was associated with, if known. Optional in V1; populated by the harness in later work so runtime events can be correlated with a session.
process	Process
stdout	Stream<List<int>> get
stderr	Stream<List<int>> get
exitCode	Future<int> get
n	final
stdout	Stream<List<int>> get
stderr	Stream<List<int>> get
exitCode	Future<int> get

Methods

Future<void> kill({bool force = false})

Future<CaptureResult> runCapture(String command, {Duration? timeout})

Runs [command] and returns the captured stdout, stderr, and exit code.

When [timeout] is provided and exceeded, the process is killed and the returned [CaptureResult.exitCode] will be -1.

Future<RunningCommandHandle> startStreaming(String command)

Starts [command] and returns a handle for streaming its output.

Prefer this over [runCapture] for long-running or interactive processes where you want to consume stdout/stderr incrementally. Implementations return their own [RunningCommandHandle] subtype (e.g. [RunningCommand] for host/Docker, an HTTP-backed handle for cloud runtimes).

RunningCommand

A handle to a running shell process.

Implements [RunningCommandHandle] so harness consumers (e.g. ShellJobManager) can manage background jobs uniformly across runtimes. Subclassed by DockerRunningCommand to add container cleanup on kill.

Constructor

RunningCommand(this.process)

Properties

Property	Type	Description
process	Process
stdout	Stream<List<int>> get
stderr	Stream<List<int>> get
exitCode	Future<int> get
stdout	Stream<List<int>> get
stderr	Stream<List<int>> get
exitCode	Future<int> get

Methods

Future<void> kill({bool force = false})

abstract CommandExecutor

Abstraction for running shell commands either locally or inside a container.

See [HostExecutor] for local execution and [DockerExecutor] for sandboxed Docker execution. Use [ExecutorFactory.create] to pick the right one based on the current [DockerConfig].

Implementations may accept an optional [RuntimeEventSink] to emit [RuntimeCommandStarted] / [RuntimeCommandCompleted] / [RuntimeCommandFailed] / [RuntimeCommandCancelled] events around each command. Emission is guarded so a null sink is free.

Methods

Future<CaptureResult> runCapture(String command, {Duration? timeout})

Runs [command] and returns the captured stdout, stderr, and exit code.

When [timeout] is provided and exceeded, the process is killed and the returned [CaptureResult.exitCode] will be -1.

Future<RunningCommandHandle> startStreaming(String command)

Starts [command] and returns a handle for streaming its output.

Prefer this over [runCapture] for long-running or interactive processes where you want to consume stdout/stderr incrementally. Implementations return their own [RunningCommandHandle] subtype (e.g. [RunningCommand] for host/Docker, an HTTP-backed handle for cloud runtimes).

Functions

String generateRuntimeCommandId()

Generates a short opaque command id used to correlate runtime events emitted around a single executor invocation. Format is cmd-<rand> — not stable across processes, not a secret.