RuntimeEvent

Category: Core

Source: runtime_event.dart

Narrow runtime-layer events emitted by [CommandExecutor] implementations when a [RuntimeEventSink] is supplied.

These are deliberately smaller than the full SessionEvent variants in session_event.dart — executors don't know about turn ids or per-session sequence numbers. The harness consumes [RuntimeEvent]s and translates them into the broader RuntimeCommand*Events with turn context attached.

Pattern-match with switch:

switch (event) {
RuntimeCommandStarted(:final command) => print('▶ $command'),
RuntimeCommandCompleted(:final exitCode) => print('✓ exit=$exitCode'),
RuntimeCommandFailed(:final message) => print('✗ $message'),
RuntimeCommandCancelled(:final reason) => print('⨯ cancelled: $reason'),
}

Classes

sealed RuntimeEvent

Narrow runtime-layer events emitted by [CommandExecutor] implementations when a [RuntimeEventSink] is supplied.

These are deliberately smaller than the full SessionEvent variants in session_event.dart — executors don't know about turn ids or per-session sequence numbers. The harness consumes [RuntimeEvent]s and translates them into the broader RuntimeCommand*Events with turn context attached.

Pattern-match with switch:

switch (event) {
RuntimeCommandStarted(:final command) => print('▶ $command'),
RuntimeCommandCompleted(:final exitCode) => print('✓ exit=$exitCode'),
RuntimeCommandFailed(:final message) => print('✗ $message'),
RuntimeCommandCancelled(:final reason) => print('⨯ cancelled: $reason'),
}

Constructor

const RuntimeEvent({
    required this.commandId,
    required this.runtimeId,
    required this.at,
  })

Properties

Property	Type	Description
commandId	String	Per-execution identifier. Stable across [RuntimeCommandStarted] → [RuntimeCommandCompleted] / [RuntimeCommandFailed] / [RuntimeCommandCancelled] for the same command.
runtimeId	String	Adapter id: 'host', 'docker', 'daytona', 'sprites', 'modal'.
at	DateTime	Wall-clock time the event was produced.

RuntimeCommandStarted

A command has been dispatched and is starting.

Constructor

const RuntimeCommandStarted({
    required super.commandId,
    required super.runtimeId,
    required super.at,
    required this.command,
    required this.runtimeCwd,
    this.sandboxId,
  })

Properties

Property	Type	Description
command	String	The command line as dispatched. Treat as a display string — emitters may truncate.
runtimeCwd	String	The directory inside the runtime where the command will execute (/workspace for cloud/Docker; host cwd otherwise).
sandboxId	String?	Cloud-side per-session sandbox id (e.g. Daytona sandboxId, sprite name, Modal sandbox id). null for host.

RuntimeCommandCompleted

A command finished normally with [exitCode]. Non-zero exit codes are not errors — they're the program's own failure signal. Use [RuntimeCommandFailed] for transport-level errors.

Constructor

const RuntimeCommandCompleted({
    required super.commandId,
    required super.runtimeId,
    required super.at,
    required this.exitCode,
    required this.duration,
    this.stdoutBytes,
    this.stderrBytes,
  })

Properties

Property	Type	Description
exitCode	int
duration	Duration
stdoutBytes	int?
stderrBytes	int?

RuntimeCommandFailed

A command failed at the transport / runtime layer (the runtime couldn't run it at all, lost connection, etc.). Distinct from a non-zero exit code, which is [RuntimeCommandCompleted].

Constructor

const RuntimeCommandFailed({
    required super.commandId,
    required super.runtimeId,
    required super.at,
    required this.errorType,
    required this.message,
  })

Properties

Property	Type	Description
errorType	String
message	String

RuntimeCommandCancelled

A command was cancelled by the harness (timeout, /cancel, shutdown) before it finished.

Constructor

const RuntimeCommandCancelled({
    required super.commandId,
    required super.runtimeId,
    required super.at,
    required this.reason,
  })

Properties

Property	Type	Description
reason	String