RuntimeFactory

Category: Runtime

Source: runtime_factory.dart

Enums

RuntimeDiffUnavailableReason

Value	Description
executorDead

Classes

abstract RuntimeSession

Per-session runtime — owns the [CommandExecutor] and [Workspace] that tools route through, plus the lifecycle hook glue calls on session shutdown.

Built-in implementations:

• host / docker — returned by [RuntimeFactory.create] directly; exposed as anonymous instances via [_BuiltinRuntimeSession].
• Cloud adapters (daytona, sprites, modal) implement this interface on their *Runtime class so callers can read sandbox metadata uniformly.

[sandboxId] and [bootstrapSha] are best-effort diagnostics for cloud runtimes; built-in runtimes return empty / null.

Properties

Property	Type	Description
id	String get	Adapter id: 'host', 'docker', 'daytona', 'sprites', 'modal', … Stable across sessions, used for capability lookup and /runtime display.
sandboxId	String get	Per-runtime sandbox identifier (Daytona sandbox id, sprite name, Modal sandbox object id). Empty string for host/docker runtimes that have no per-session sandbox.
bootstrapSha	String? get	Commit SHA the workspace was bootstrapped from inside the sandbox. null for host/docker (no bootstrap) and for cloud sandboxes that were resumed from an existing /workspace/.git.
resumed	bool get	True when the runtime resumed an existing sandbox instead of creating a fresh one. Always false for host/docker.
executor	CommandExecutor get	The executor that [BashTool] and friends route through.
workspace	Workspace get	The workspace that [ReadFileTool] / [WriteFileTool] / etc. route through.
patch	String
meta	RuntimeDiffMeta
meta	RuntimeDiffMeta
reason	RuntimeDiffUnavailableReason
hint	String?
id	String get	Adapter id: 'host', 'docker', 'daytona', 'sprites', 'modal', … Stable across sessions, used for capability lookup and /runtime display.
sandboxId	String get	Per-runtime sandbox identifier (Daytona sandbox id, sprite name, Modal sandbox object id). Empty string for host/docker runtimes that have no per-session sandbox.
bootstrapSha	String? get	Commit SHA the workspace was bootstrapped from inside the sandbox. null for host/docker (no bootstrap) and for cloud sandboxes that were resumed from an existing /workspace/.git.
resumed	bool get	True when the runtime resumed an existing sandbox instead of creating a fresh one. Always false for host/docker.
executor	CommandExecutor get	The executor that [BashTool] and friends route through.
workspace	Workspace get	The workspace that [ReadFileTool] / [WriteFileTool] / etc. route through.

Methods

Future<void> close()

Releases runtime resources on session shutdown. Host/docker runtimes return immediately; cloud runtimes stop the sandbox (or leave it to auto-sleep when delete_on_close: false).

Future<RuntimeDiffOutcome> diffSinceBootstrap()

Returns the outcome of attempting to diff the runtime workspace against [bootstrapSha]. The default implementation reports [RuntimeDiffOutcomeUnavailable] (host/docker, no diff capture). Cloud runtimes override this to return [RuntimeDiffOutcomeSuccess], [RuntimeDiffOutcomeEmpty], or [RuntimeDiffOutcomeUnavailable] with a typed reason and a hint.

Returning unavailable is explicitly not the same as "no changes". Surfaces must turn unavailable into a visible warning so the user knows the session didn't silently lose their work.

const RuntimeDiffOutcome()

const RuntimeDiffOutcomeSuccess({required this.patch, required this.meta})

const RuntimeDiffOutcomeEmpty({required this.meta})

const RuntimeDiffOutcomeUnavailable({required this.reason, this.hint})

sealed RuntimeDiffOutcome

Surface-facing mirror of DiffOutcome from glue_runtimes/common/diff.dart. Lives here so glue_strategies consumers can pattern-match without importing the runtime adapter package.

Constructor

const RuntimeDiffOutcome()

RuntimeDiffOutcomeSuccess

Constructor

const RuntimeDiffOutcomeSuccess({required this.patch, required this.meta})

Properties

Property	Type	Description
patch	String
meta	RuntimeDiffMeta

RuntimeDiffOutcomeEmpty

Constructor

const RuntimeDiffOutcomeEmpty({required this.meta})

Properties

Property	Type	Description
meta	RuntimeDiffMeta

RuntimeDiffOutcomeUnavailable

Constructor

const RuntimeDiffOutcomeUnavailable({required this.reason, this.hint})

Properties

Property	Type	Description
reason	RuntimeDiffUnavailableReason
hint	String?

RuntimeDiffMeta

Constructor

const RuntimeDiffMeta({
    required this.runtimeId,
    required this.sandboxId,
    required this.bootstrapSha,
    required this.remoteUrl,
    required this.runtimeCwd,
    required this.format,
    required this.capturedAt,
    required this.sizeBytes,
  })

Properties

Property	Type	Description
runtimeId	String
sandboxId	String?
bootstrapSha	String?
remoteUrl	String?
runtimeCwd	String
format	String
capturedAt	DateTime
sizeBytes	int

RuntimeFactory

Builds a [RuntimeSession] for runtime: <name> from config.

Two runtimes are built in: host and docker. Cloud adapters (daytona, sprites, modal) register themselves via [register] from a surface (cli/bin/glue.dart) at startup — this keeps glue_strategies free of any dependency on cloud-specific packages.

Methods

static void register(String name, RuntimeAdapter adapter)

Registers a cloud adapter under [name]. The surface (cli) calls this once at startup before [create] is invoked.

static Iterable<String> registeredAdapters()

Returns the set of registered cloud-adapter names. Useful for glue doctor and the /runtime slash command.

`static Future<RuntimeSession> create({

required String runtime,
required ShellConfig shellConfig,
required DockerConfig dockerConfig,
required String cwd,
Map<String, Object?> runtimeOptions = const {},
List<MountEntry> sessionMounts = const [],
bool? dockerAvailable,
RuntimeEventSink? eventSink,

})`

Resolves the runtime named [runtime] and returns its session.

• 'host' → [HostExecutor] + identity [LocalWorkspace].
• 'docker' → [DockerExecutor] + identity [LocalWorkspace] (Docker bind-mounts the host cwd so the host filesystem stays authoritative).
• any other value → a registered adapter, or [StateError] if none is registered.

[runtimeOptions] holds the YAML section for the named runtime (e.g. the daytona: block when runtime: daytona is selected). Cloud adapters parse this on startup; host/Docker ignore it.

RuntimeInfoSnapshot

Snapshot of the immutable runtime metadata that surfaces persist alongside the session (SessionMeta) so /resume, glue session …, and the cleanup sweep have a stable handle on what runtime the session used.

Constructor

const RuntimeInfoSnapshot({
    required this.runtimeId,
    required this.sandboxId,
    this.bootstrapSha,
    this.remoteUrl,
  })

factory RuntimeInfoSnapshot.from(RuntimeSession session)

Builds a snapshot from a live [RuntimeSession]. Cheap — just reads getters and shapes the data.

Properties

Property	Type	Description
runtimeId	String
sandboxId	String
bootstrapSha	String?
remoteUrl	String?