workspace

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: AGPL-3.0 Imports: 33 Imported by: 0

Documentation

Overview

Package workspace is the seam between factory-agent supervise and the VM a task runs in (P1 §1, design/workstreams/agent/LLD/supervise.md): a Driver creates, starts, fills, runs, empties and destroys one workspace VM per task. The tart driver is in workspace/tart.

Index

Constants

View Source
const (
	// BundleDir is where Put lays the run bundle in the VM: on the root disk, since the
	// bundle's skills hold executables and /run is a noexec tmpfs. vmrun.DefaultBundle agrees.
	BundleDir = "/var/lib/factory/run"
	// VMOutDir is factory-agent run's out/ in the VM (--work /work).
	VMOutDir = "/work/out"
	// AgentCommand is factory-agent in the VM (the base image puts it on PATH).
	AgentCommand = "factory-agent"
)

The workspace runner's fixed places (supervise.md, "The workspace runner").

View Source
const (
	// DefaultGatewayPort is the gateway's port on the VM's gateway address when GatewayPort is
	// zero: workspace.gatewayPort's default, which the host's firewall opens.
	DefaultGatewayPort = config.DefaultGatewayPort
	// DefaultOverrun is how long past the task's wall clock the runner lets the VM run before
	// it cancels it: the VM's own deadline (--remaining) fires first and writes the outcome.
	DefaultOverrun = 2 * time.Minute
	// DefaultDownBudget is how long the runner waits for factory-agent run to exit after its
	// outcome event (its environment's down, at most --down-timeout).
	DefaultDownBudget = pipeline.StackDownTimeout + 30*time.Second
)

Defaults of RunnerOptions.

View Source
const (
	DefaultCPU       = 6
	DefaultMemoryMiB = 8 << 10
)

The default workspace size (P1 §1: local-dev with kind used 1.9 GiB in the guest).

View Source
const Prefix = "ws-"

Prefix starts every workspace's name. A name is Prefix and the task id (tsk_…), so Phase 0's VMs (ws-1, ws-2, ws-gw) are never a workspace: no driver call accepts or lists them.

View Source
const TranscriptNote = "factory.workspace-transcript"

TranscriptNote is the transcript line the runner writes about the VM's transcript: lines it dropped (over the line cap, or a host-only line the VM forged) or why it has none.

Variables

This section is empty.

Functions

func Name

func Name(taskID string) (string, error)

Name is the task's workspace name.

func ValidName

func ValidName(name string) error

ValidName reports whether name is a workspace's name: ws-tsk_ and up to 64 of [A-Za-z0-9_-].

Types

type Bundler

type Bundler interface {
	PrepareBundle(ctx context.Context, job *runner.Job, dir string, x pipeline.BundleExtras) error
	StoreTranscript(ctx context.Context, job *runner.Job, parts [][]byte, extra ...string) (string, error)
	StoreEnvironmentLog(ctx context.Context, job *runner.Job, log []byte, extra ...string) error
}

Bundler is what the runner needs of the host's run pipeline (*pipeline.Pipeline): the run bundle before the VM exists, and the transcript and environment log uploads after.

type Driver

type Driver interface {
	// Create makes the workspace from the driver's warm base, sized by spec (WithDefaults).
	Create(ctx context.Context, name string, spec Spec) error
	// Start boots it, waits until commands run in it, and returns its addresses.
	Start(ctx context.Context, name string) (Network, error)
	// Put copies the host directory srcDir to dstDir in the VM, replacing it, owned by root and
	// read-only to everyone (files 0444, directories and executables 0555).
	Put(ctx context.Context, name, srcDir, dstDir string) error
	// Exec runs argv in the VM. stdin may be nil. A non-zero exit is an *ExitError. When ctx
	// is done the remote process gets SIGTERM, then SIGKILL after the driver's grace; Exec
	// returns, with ctx's error, once it has exited, or after the grace once the local side is
	// stopped too.
	Exec(ctx context.Context, name string, argv []string, stdin io.Reader, stdout, stderr io.Writer) error
	// Get copies the VM directory srcDir to the host directory dstDir, which must not exist
	// (its parent must): all of it, or only the named files when files is given (plain names
	// in srcDir; a missing one is skipped). The copy is capped and refuses links out of dstDir
	// and special files.
	Get(ctx context.Context, name, srcDir, dstDir string, files ...string) error
	// Stop shuts the workspace down and keeps it (--keep-workspace).
	Stop(ctx context.Context, name string) error
	// Destroy stops and deletes it; a workspace that doesn't exist is no error.
	Destroy(ctx context.Context, name string) error
	// List names the driver's workspaces that exist, for the orphan cleanup at start.
	List(ctx context.Context) ([]string, error)
}

Driver runs workspace VMs. Every method takes a workspace name (Name) and refuses any other. Everything a VM returns (Exec's output, Get's files) is untrusted.

type ExitError

type ExitError struct{ Code int }

ExitError is Exec's error when the remote command exits non-zero.

func (*ExitError) Error

func (e *ExitError) Error() string

type Network

type Network struct {
	VM, Gateway netip.Addr
}

Network is a started workspace's addresses: the VM's own, which its gateway pins as its only client, and the agent host's address on the VM's network, where the gateway listens.

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner runs each leased task in its own workspace VM, behind a gateway that holds every credential (supervise.md, "The workspace runner"). It implements runner.Runner.

func NewRunner

func NewRunner(o RunnerOptions) (*Runner, error)

NewRunner checks o and fills in the defaults.

func (*Runner) Run

func (r *Runner) Run(ctx context.Context, job *runner.Job, sink runner.Sink) (runner.Outcome, error)

Run implements runner.Runner.

type RunnerOptions

type RunnerOptions struct {
	Driver Driver
	// Pipeline is the host's pipeline (WorkRoot, GitAuthHelper).
	Pipeline Bundler
	// StateDir is the agent's state dir: runs/<task>/ (the bundle and the VM's out/),
	// gateway-ca/ and logins/.
	StateDir string
	// Spec is the agent's workspace size (WithDefaults): each workspace's, and the most a
	// task's limits.cpus and limits.memory get (taskSize).
	Spec Spec
	// KeepWorkspace stops each workspace instead of destroying it, and keeps runs/<task>/.
	KeepWorkspace bool
	// GatewayPort is the gateway's port on the VM's gateway address: workspace.gatewayPort,
	// the one the host's firewall (the pf anchor, the kata nft table) opens.
	// DefaultGatewayPort when zero.
	GatewayPort int
	// Listen opens the gateway's listener on addr; default a TCP listener on it (tests listen
	// elsewhere).
	Listen func(ctx context.Context, addr netip.AddrPort) (net.Listener, error)
	// Overrun and DownBudget: DefaultOverrun and DefaultDownBudget when zero.
	Overrun, DownBudget time.Duration
	Clock               clock.Clock
	Logger              *slog.Logger
}

RunnerOptions configure a Runner. Driver, Pipeline and StateDir are required.

type Spec

type Spec struct {
	CPU       int
	MemoryMiB int
}

Spec sizes a workspace.

func (Spec) WithDefaults

func (s Spec) WithDefaults() Spec

WithDefaults fills a zero field with the default size.

Directories

Path Synopsis
Package kata is the workspace driver for Linux: each workspace is a Kata microVM made and run by the root helper (design/workstreams/agent/LLD/workspace-kata.md#the-driver-internalagentworkspacekata), which this driver runs as sudo -n kata-helper <verb>.
Package kata is the workspace driver for Linux: each workspace is a Kata microVM made and run by the root helper (design/workstreams/agent/LLD/workspace-kata.md#the-driver-internalagentworkspacekata), which this driver runs as sudo -n kata-helper <verb>.
Package tart is the workspace driver for macOS: it drives the tart CLI (P1 §1, design/workstreams/agent/LLD/supervise.md).
Package tart is the workspace driver for macOS: it drives the tart CLI (P1 §1, design/workstreams/agent/LLD/supervise.md).
Package vmexec is what the workspace drivers share (design/workstreams/agent/LLD/ workspace-kata.md#the-driver-internalagentworkspacekata): running commands in a workspace through the driver's exec command, and over it Put's and Get's tar streams, Exec with its pid-file cancel, and the network read.
Package vmexec is what the workspace drivers share (design/workstreams/agent/LLD/ workspace-kata.md#the-driver-internalagentworkspacekata): running commands in a workspace through the driver's exec command, and over it Put's and Get's tar streams, Exec with its pid-file cancel, and the network read.

Jump to

Keyboard shortcuts

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