executor

package
v0.195.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 27, 2026 License: BSD-2-Clause Imports: 25 Imported by: 0

Documentation

Overview

Package executor runs prompt files inside Docker containers.

Index

Constants

View Source
const EnvManagedMarker = "DARK_FACTORY_MANAGED"

EnvManagedMarker is the environment variable dark-factory sets on every container it launches. Its presence signals to processes inside the container that the dark-factory daemon manages this container's lifecycle — for example, the generate-prompts-for-spec command skips its host-only `spec mark-prompted` step because the host-side generator finalizes the spec after the container exits (and the dark-factory CLI is not present inside the container).

Variables

View Source
var ErrClaudeNotFound = stderrors.New("claude not found on PATH")

ErrClaudeNotFound signals that the `claude` binary is not on PATH. backend: local requires claude in the environment; the local executor NEVER falls back to docker.

View Source
var ErrDockerDaemonUnavailable = stderrors.New("docker daemon unavailable")

ErrDockerDaemonUnavailable signals that the Docker daemon could not be reached (socket missing, daemon not running). Callers MUST NOT treat this as "container not running" — the container's actual state is unknown.

View Source
var ErrReattachUnsupported = stderrors.New("reattach unsupported for local backend")

ErrReattachUnsupported signals that the local backend cannot reattach to a prior execution: a local subprocess dies with the dark-factory process, so there is nothing to reattach to. The caller must recover by re-running the prompt (safe because execution commits per prompt).

Functions

func BuildDockerRunArgs added in v0.180.0

func BuildDockerRunArgs(opts ContainerLaunchOpts) []string

BuildDockerRunArgs returns the argv for `docker run --rm` from opts. First argv element is "run"; caller invokes via `exec.CommandContext(ctx, "docker", args...)` or `subproc.Runner.RunWithWarnAndTimeout(ctx, op, "docker", args...)`.

The returned argv shape matches what dark-factory's executor produces for prompt containers, minus the prompt-file mount and the YOLO_PROMPT_FILE/YOLO_OUTPUT env vars (those are prompt-specific and not part of the shared launch surface).

Stable argv shape: env keys are sorted, mount order is deterministic. Callers can grep the argv in tests without flakiness.

Types

type ContainerCounter added in v0.82.0

type ContainerCounter interface {
	CountRunning(ctx context.Context) (int, error)
}

ContainerCounter counts running dark-factory containers system-wide.

func NewDockerContainerCounter added in v0.82.0

func NewDockerContainerCounter(runner subproc.Runner) ContainerCounter

NewDockerContainerCounter creates a ContainerCounter that uses docker ps with label filtering.

func NewNoopContainerCounter added in v0.192.0

func NewNoopContainerCounter() ContainerCounter

NewNoopContainerCounter creates a ContainerCounter that always reports zero running containers without invoking docker. Used by the local backend, where there are no containers to count and `docker ps` must never run (no docker daemon is required when backend: local).

type ContainerLaunchOpts added in v0.180.0

type ContainerLaunchOpts = launchpolicy.ContainerLaunchOpts

ContainerLaunchOpts is an alias for launchpolicy.ContainerLaunchOpts. The type definition lives in pkg/launchpolicy to avoid a circular import (executor imports launchpolicy; launchpolicy must not import executor). Callers continue using executor.ContainerLaunchOpts with no source change.

type ExecutionChecker added in v0.186.0

type ExecutionChecker interface {
	IsRunning(ctx context.Context, executionID string) (bool, error)
	// WaitUntilRunning blocks until the named execution is in the running state,
	// the timeout elapses, or ctx is cancelled.
	WaitUntilRunning(ctx context.Context, executionID string, timeout time.Duration) error
}

ExecutionChecker checks whether a unit of execution (identified by executionID) is currently running.

func NewDockerExecutionChecker added in v0.186.0

func NewDockerExecutionChecker(
	currentDateTimeGetter libtime.CurrentDateTimeGetter,
) ExecutionChecker

NewDockerExecutionChecker creates an ExecutionChecker backed by docker inspect.

func NewLocalSubprocessExecutionChecker added in v0.192.0

func NewLocalSubprocessExecutionChecker(
	currentDateTimeGetter libtime.CurrentDateTimeGetter,
) ExecutionChecker

NewLocalSubprocessExecutionChecker creates an ExecutionChecker for the local backend. A local subprocess never survives a dark-factory restart and is not inspectable across restarts, so IsRunning always returns false and WaitUntilRunning returns nil immediately (the Execute call blocks in-process, so "wait until running" is trivially satisfied).

type ExecutionStopper added in v0.186.0

type ExecutionStopper interface {
	StopContainer(ctx context.Context, executionID string) error
}

ExecutionStopper stops a running unit of execution by its executionID.

func NewDockerExecutionStopper added in v0.186.0

func NewDockerExecutionStopper() ExecutionStopper

NewDockerExecutionStopper creates an ExecutionStopper backed by docker stop.

func NewLocalSubprocessExecutionStopper added in v0.192.0

func NewLocalSubprocessExecutionStopper() ExecutionStopper

NewLocalSubprocessExecutionStopper creates an ExecutionStopper for the local backend. Because the local backend's cancellation is driven through the executor's StopAndRemoveContainer (which holds the child process handle via mutex), a standalone stopper keyed only by executionID cannot reach the child. This is a no-op; local cancellation flows through context cancellation or StopAndRemoveContainer instead.

type Executor added in v0.2.0

type Executor interface {
	Execute(ctx context.Context, promptContent string, logFile string, executionID string) error
	// Reattach connects to a running execution's output stream and waits for it to exit.
	// It does not create a new container. The log file is overwritten from the beginning
	// of the container's output (docker logs replays all output from container start).
	// maxPromptDuration is the remaining allowed run time; 0 disables the timeout.
	// Returns nil when the execution exits successfully.
	Reattach(
		ctx context.Context,
		logFile string,
		executionID string,
		maxPromptDuration time.Duration,
	) error
	// StopAndRemoveContainer stops and forcibly removes the named execution.
	// Best-effort: any errors are logged but not returned.
	StopAndRemoveContainer(ctx context.Context, executionID string)
}

Executor executes a prompt.

func NewDockerExecutor added in v0.2.0

func NewDockerExecutor(
	policy launchpolicy.Policy,
	model string,
	maxPromptDuration time.Duration,
	currentDateTimeGetter libtime.CurrentDateTimeGetter,
	fmtr formatter.Formatter,
) Executor

NewDockerExecutor creates a new Executor using Docker. The launch shape (image, project, mounts, base env, netrc/gitconfig, hide-git, capabilities) is sourced from the shared launchpolicy.Policy — see pkg/launchpolicy. Prompt-specific concerns (model, max duration, formatter) remain on the executor itself.

func NewLocalSubprocessExecutor added in v0.192.0

func NewLocalSubprocessExecutor(
	model string,
	maxPromptDuration time.Duration,
	currentDateTimeGetter libtime.CurrentDateTimeGetter,
	fmtr formatter.Formatter,
) Executor

NewLocalSubprocessExecutor creates an Executor that runs claude locally.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL