agent

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ResolveTaskWorkDir

func ResolveTaskWorkDir() (string, error)

ResolveTaskWorkDir returns the directory host-mode tasks start in: the runner process user's home directory, or "." when HOME is unavailable.

func SweepDockerOrphans

func SweepDockerOrphans(ctx context.Context, runnerID string) (removed int, err error)

SweepDockerOrphans removes containers left over from previous runs of this runner (e.g. after a crash or SIGKILL where the per-task defer cleanup did not get a chance to run). It is a no-op when docker is not on PATH or the daemon is unreachable.

Types

type Agent

type Agent struct {
	HTTP   *http.Client
	Config Config
}

func (*Agent) Run

func (a *Agent) Run(ctx context.Context) error

Run executes one task for an ephemeral runner or continues accepting tasks for a reusable runner. A task completes only after all retained logs and its terminal result have been acknowledged.

type Config

type Config struct {
	BaseURL      string
	Registration protocol.Registration
	Version      string

	MaxOutputBytes      int
	MaxExecutionSeconds int
	TaskWorkDir         string
	ResetTaskHome       bool

	LogSpoolDirectory string
	LogChunkBytes     int64
	LogSpoolMaxBytes  int64

	ReconnectMin  time.Duration
	ReconnectMax  time.Duration
	Shutdown      <-chan struct{}
	ShutdownGrace time.Duration
	Log           *slog.Logger
}

func DefaultConfig

func DefaultConfig() Config

type DockerExecutor

type DockerExecutor struct {
	MaxOutputBytes int
	RunnerID       string
}

DockerExecutor runs a task inside a Docker container using a pull -> run -d --name -> exec -> stop+rm lifecycle. Cleanup runs in a deferred function so cancelled / panicked tasks do not leak containers.

Multi-line `commands` are bundled into a single `sh -c` invocation with `set -e` so env / cwd persist across directives and the script fails fast on the first non-zero exit code (POSIX sh chosen over bash so minimal images like alpine work out of the box; see dockerExecTask). Argv (`command`) is dispatched via `docker exec <name> <argv...>`.

`docker exec` is invoked without `-t`, so the task runs in a non-TTY context. CLI tools that probe `isatty()` (color output, progress bars, interactive prompts) will see stdout/stderr as a pipe rather than a terminal. This is intentional and matches what callers get from `docker run` without `-t`; it is also more predictable for batch / CI workloads.

func (*DockerExecutor) Execute

func (d *DockerExecutor) Execute(ctx context.Context, task *api.TaskPayload, live io.Writer, resultHostPath string) (int, string, error)

type Executor

type Executor interface {
	Execute(ctx context.Context, task *api.TaskPayload, live io.Writer, resultHostPath string) (exit int, output string, err error)
}

Executor runs one task end-to-end and is responsible for its own setup and teardown. Concrete implementations exist for host execution (HostExecutor) and containerized execution (DockerExecutor).

Implementations must ensure that any resources they create (e.g. Docker containers) are released even when ctx is cancelled or Execute returns an error — typically by performing cleanup inside a deferred function.

live, when non-nil, receives a copy of every stdout/stderr byte the task produces as it runs. Executors may still accumulate output internally for tests and diagnostics; it is not sent on complete.

type HostExecutor

type HostExecutor struct {
	MaxOutputBytes int
	TaskWorkDir    string
	// ResetTaskHome gives each host task a fresh HOME and cwd under
	// TaskWorkDir/.superplane/homes/<task-id>, then deletes that tree.
	// Local long-lived workers set this so leftover clone dirs cannot leak.
	ResetTaskHome bool
}

HostExecutor runs tasks directly on the host process. It is a thin wrapper around the existing host shell directive path (PTY+markers or pipe-bundle via RUNNER_SHELL_USE_PIPE) and the argv-subprocess path.

func (*HostExecutor) Execute

func (h *HostExecutor) Execute(ctx context.Context, task *api.TaskPayload, live io.Writer, resultHostPath string) (int, string, error)

Jump to

Keyboard shortcuts

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