system

package
v1.0.0-alpha.53 Latest Latest
Warning

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

Go to latest
Published: Aug 8, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Package system implements executor.Provider using local OS processes and a chrooted billy filesystem per agent.

Index

Constants

This section is empty.

Variables

View Source
var ErrConfig = fmt.Errorf("agent config error")

ErrConfig indicates the resolved agent is not deployable as configured — currently raised when a required CONFIG (trailing `!`) reaches materialise time with no value (see spec.RequiredConfigsProvided).

View Source
var ErrModel = fmt.Errorf("model resolve error")

ErrModel indicates the model resolver could not provide credentials for the agentfile's declared model — typically a missing provider entry in ~/.otters/providers.yaml or a model not in the provider's allowlist.

View Source
var ErrPull = fmt.Errorf("agent pull error")

ErrPull indicates the agent image could not be loaded from the OCI store.

View Source
var (
	RuntimeBin = filepath.Join(runtimeBinDir, "runtime")
)

Path constants for the agent workspace filesystem layout. They use filepath.Join (cross-platform separators), so they can't be declared as `const` — Go const requires compile-time literals.

Functions

func MaterializeContent

func MaterializeContent(
	ctx context.Context,
	fs billy.Filesystem,
	id uuid.UUID,
	addr string,
	opts MaterializeOptions,
) (*executor.Runtime, error)

MaterializeContent runs the system executor's content-only materialisation pipeline against fs: pulls the agent image, extracts CONTEXT + ADD layers, generates AGENT.md / WORKSPACE.md / agent.yaml, resolves model credentials, applies user mount symlinks. Does NOT install runtime / BIN binaries to disk — that step is system-only.

Exposed for the Docker executor to reuse the same FHS layout + metadata generation without copying binaries the container will pick up via image mounts instead.

Errors join ErrPull / ErrModel where appropriate so callers can route them to the right Status (StatusPullError / StatusModelError).

func NewRegistry

func NewRegistry(target oras.Target, addr string, createdAt CreatedAtFunc) executor.Registry

NewRegistry returns an executor.Registry backed by the embedded HTTP registry. Exported so other executors (notably the docker executor) can compose a fallback for agent OCI artifacts — custom mediatypes that Docker's image store can't represent.

target is the oras.Target backing Fetch / Tag / BuildTarget; addr is the embedded registry's HTTP "host:port" used for catalog / manifest endpoints; createdAt is optional and may be nil.

Types

type Agent

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

Agent implements executor.Agent using a local OS process.

mu guards the mutable run state (rt, addr, the daemon-callback pair, and the running/ran/cancel handshake). It is never held across slow I/O: materialisation runs unlocked, and only the resulting descriptor is published under the lock.

func NewAgent

func NewAgent(id uuid.UUID, fs billy.Filesystem, opts ...AgentOption) *Agent

NewAgent creates a system agent.

func (*Agent) Addr

func (a *Agent) Addr() string

Addr returns the loopback host:port the runtime binds.

func (*Agent) Exec

func (a *Agent) Exec(ctx context.Context, bin string, args []string, stdin string) executor.ExecResult

Exec runs a BIN subprocess against the agent's already-materialized spawn env: same locked-down env vars, same workspace cwd, same PATH pointing at <rootDir>/usr/bin (where the agent's declared BINs are installed). Returns when the process exits or ctx is cancelled.

The child runs in its own process group (Setpgid). On ctx cancellation we send SIGKILL to the whole group so any sub-processes the BIN itself spawned (`sh -c "a | b"` style) die with it — no orphaned grandchildren.

The agent MUST be initialized (via Run / Start having reached the running state at least once) before Exec is called: the runtime descriptor populated at initialize time supplies the env. Calling Exec on an un-initialized agent returns an error in ExecResult.Err.

func (*Agent) FailureReason

func (a *Agent) FailureReason() executor.FailureReason

FailureReason returns the cause when Status is StatusFailed.

func (*Agent) Prepare

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

Prepare materialises the workspace, mapping the failure to a FailureReason — unless ctx was cancelled (a deliberate Stop), which endRun settles to Stopped.

func (*Agent) ReapplyMounts

func (a *Agent) ReapplyMounts() error

ReapplyMounts re-runs the mount symlink and MOUNTS.md steps against the existing filesystem, so mounts survive a daemon restart without a rebuild.

func (*Agent) Remove

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

Remove stops the agent (if running) and deletes its workspace directory.

func (*Agent) Run

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

Run materialises the workspace (if needed) and blocks on the runtime process until it exits or ctx is cancelled. Only one Run may be in flight at a time.

Lifecycle: Pulling → Starting → (supervisor sets Ready) → Stopped on exit. The cancel/ran handshake is installed before Prepare, so a Stop during the pull window cancels the run instead of silently no-op'ing.

func (*Agent) Runtime

func (a *Agent) Runtime() *executor.Runtime

Runtime returns the resolved runtime descriptor, or nil before Prepare.

func (*Agent) SetAgentToken

func (a *Agent) SetAgentToken(token string)

SetAgentToken swaps the JWT injected into the spawn env. The running process keeps its token until restart; the next Run reads the new value.

func (*Agent) Start

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

Start re-runs a stopped or failed agent, re-resolving model credentials first so a providers.yaml edit takes effect on the next subprocess.

func (*Agent) Status

func (a *Agent) Status() executor.Status

Status returns the current lifecycle state.

func (*Agent) StatusTracker

func (a *Agent) StatusTracker() *executor.StatusTracker

StatusTracker exposes the tracker for the daemon supervisor's Ready/Working transitions and for tests.

func (*Agent) Stop

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

Stop cancels the run and blocks until Run returns or ctx is cancelled. It is effective in every phase — pull, materialise, or serve — because it cancels the run context installed by beginRun. A no-op if the agent is not running.

func (*Agent) SubscribeStatus

func (a *Agent) SubscribeStatus() (<-chan executor.Status, func())

SubscribeStatus returns a channel of status transitions and a cancel function.

func (*Agent) UUID

func (a *Agent) UUID() uuid.UUID

UUID returns the agent's stable identifier.

type AgentOption

type AgentOption func(*Agent)

AgentOption configures an individual agent.

func WithAddr

func WithAddr(addr string) AgentOption

WithAddr sets the gRPC listen address for the agent.

func WithAgentLocalRuntime

func WithAgentLocalRuntime(path string) AgentOption

WithAgentLocalRuntime sets a local runtime binary path on the agent.

func WithAgentPuller

func WithAgentPuller(p agentoci.Puller) AgentOption

WithAgentPuller sets the OCI puller on the agent.

func WithAgentToken

func WithAgentToken(token string) AgentOption

WithAgentToken sets the JWT minted by the daemon for this agent; injected into the spawn env as OTTERS_AGENT_TOKEN. The runtime presents it as `Authorization: Bearer …` on every outbound RPC. Empty disables the env var (runtime can still spawn — outbound daemon calls would fail Unauthenticated, which is the desired behaviour when the agent isn't supposed to call back).

func WithAgentUsageFetcher

func WithAgentUsageFetcher(f agentoci.UsageFetcher) AgentOption

WithAgentUsageFetcher sets the OCI usage fetcher on the agent. Symmetric with WithAgentPuller: scoped to a single Agent created directly (rather than via Provider, which propagates the Provider-level WithUsageFetcher).

func WithCapabilities

func WithCapabilities(caps []executor.Capability) AgentOption

WithCapabilities sets the list of LLM-facing tool functions the runtime image registers (job_submit, context_show, …) and their descriptions. The daemon supplies the list at create-time; the workspace plumbs it into ResolvedConfig.Capabilities and the AGENT.md generator surfaces it in the system prompt.

func WithDaemonURL

func WithDaemonURL(url string) AgentOption

WithDaemonURL sets the openotters daemon URL the runtime should dial back to. Format is backend-conventional: for the system executor, callers typically pass `unix://<host-path>` (the chrooted runtime can dial host paths directly since the chroot is billy-rooted, not a real syscall chroot). Empty disables the env var.

func WithDigestResolver

func WithDigestResolver(r DigestResolver) AgentOption

WithDigestResolver wires a digest resolver into the workspace. The resolver is consulted for the agent's own image, the RUNTIME image, and every BIN tool, with the results written into the resolved agent.yaml's provenance block + per-tool ref/digest fields.

func WithImageRef

func WithImageRef(ref string) AgentOption

WithImageRef tells the workspace which image ref produced this agent. Without it, agent.yaml's provenance.image_digest stays empty because the workspace materialiser otherwise has no canonical "this is the agent image" handle — the daemon does.

func WithModelResolver

func WithModelResolver(r model.Resolver) AgentOption

WithModelResolver sets the model resolver for API credential resolution.

func WithMounts

func WithMounts(m []executor.Mount) AgentOption

WithMounts attaches bind-mount specs to the agent. The symlinks are created by workspace.applyMounts at the end of materialize (or via Agent.ReapplyMounts on restore).

func WithOverrides

func WithOverrides(overrides ...spec.Override) AgentOption

WithOverrides sets spec-level overrides (model, runtime, etc.).

func WithReference

func WithReference(ref spec.Reference) AgentOption

WithReference sets the OCI reference for the agent image.

func WithSpawner

func WithSpawner(s Spawner) AgentOption

WithSpawner overrides the process spawner used to launch the runtime binary. Production uses defaultSpawner (real os/exec); tests inject a mock so process.serve can be exercised end-to-end without spawning anything real.

func WithStaticModelResolver

func WithStaticModelResolver(apiURL, apiKey string) AgentOption

WithStaticModelResolver sets a static API URL and key for model resolution.

func WithStderr

func WithStderr(w io.Writer) AgentOption

WithStderr sets the writer for agent stderr.

func WithStdout

func WithStdout(w io.Writer) AgentOption

WithStdout sets the writer for agent stdout.

func WithStore

func WithStore(s oras.ReadOnlyTarget) AgentOption

WithStore sets the OCI store for loading the agentfile.

type Cmd

type Cmd interface {
	Start() error
	Wait() error
	Signal(sig os.Signal) error
	Kill() error
	SetStdout(w io.Writer)
	SetStderr(w io.Writer)
	SetEnv(env []string)
	SetDir(dir string)
}

Cmd is the slice of *os/exec.Cmd that process.serve needs: start, wait, signal, force-kill the process group, and wire stdio/env/dir. Signal and Kill must be safe to call before Start and after Wait, returning an error rather than panicking.

type CreatedAtFunc

type CreatedAtFunc func(repo, tag string) int64

CreatedAtFunc returns the unix-seconds when the manifest at (repo, tag) was first written to the embedded registry. The daemon implements this against its on-disk blob mtime; tests may pass nil and accept CreatedUnix=0 in returned ImageInfo.

type DigestResolver

type DigestResolver func(ref string) string

DigestResolver returns the OCI digest of an image reference (or the empty string if the resolver can't answer). Used by workspace materialisation to record provenance into agent.yaml.

type LoopbackAllocator

type LoopbackAllocator interface {
	Reserve() (string, error)
}

LoopbackAllocator reserves a host:port the runtime subprocess will bind for its gRPC server. Abstracted behind an interface so tests don't have to bind real TCP ports (which causes port conflicts and CI flake).

Implementations return absolute addresses like "127.0.0.1:51234". The returned port is expected to be free at the moment Reserve returns, but the window between Reserve and the runtime's bind is inherently racy — good enough for dev; production deployments should inherit a listener fd instead.

type MaterializeOptions

type MaterializeOptions struct {
	Store          oras.ReadOnlyTarget
	Ref            spec.Reference
	Overrides      []spec.Override
	OCIPuller      agentoci.Puller
	UsageFetcher   agentoci.UsageFetcher
	ModelResolver  model.Resolver
	DigestResolver DigestResolver
	ImageRef       string
	LocalRuntime   string
	Mounts         []executor.Mount
	HostFS         billy.Filesystem
	// ToolBinaryPath optionally returns an absolute in-container
	// path for tool `name`. The docker executor returns
	// `/opt/bins/<name>` so the runtime resolves the symlink
	// stamped on the agent root (which the kernel then follows to
	// the read-only image-mount, hidden under /opt/bin-images).
	ToolBinaryPath func(name string) string

	// SymlinkBinAt, when non-nil, is invoked once per declared BIN
	// with (name, target) — name is the BIN's tool name (resolves
	// to opt/bins/<name> on the agent root), target is the
	// container-local string the symlink should point at (e.g.
	// /opt/bin-images/<name>/<name>). Only the docker executor sets
	// this; system installs the binary as a regular file under
	// usr/bin and doesn't need the indirection.
	SymlinkBinAt func(name string) (target string, ok bool)

	// Capabilities is the list of LLM-facing tool functions the
	// runtime image registers, each with a description. Surfaces
	// in agent.yaml's capabilities: block. Daemon-supplied — the
	// agentfile library itself doesn't know which tools exist or
	// what they do.
	Capabilities []executor.Capability

	// View is the agent-visible filesystem layout used to render
	// WORKSPACE.md. Zero-value uses system defaults derived from
	// fs.Root() (host path, no sandbox). The docker executor sets
	// a container-rooted view so the LLM doesn't see the host
	// path of its bind mount.
	View executor.WorkspaceView

	// ViewBinDirsForTools, when non-nil, fills View.BinDirs from
	// the resolved tool name list — invoked once after the spec is
	// parsed and tools are populated, before WORKSPACE.md is
	// rendered. Lets the docker executor produce one
	// `/opt/bins/<name>` entry per BIN without parsing the spec
	// twice.
	ViewBinDirsForTools func(toolNames []string) []string
}

MaterializeOptions packages the inputs MaterializeContent needs. Fields mirror the system workspace's internal struct so the executor that lives elsewhere (today: the Docker executor) can drive the same materialise pipeline without re-implementing it.

type Provider

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

Provider implements executor.Provider using the local filesystem. It prepares the infrastructure (chroot dirs) but does not materialize agents.

func NewProvider

func NewProvider(root billy.Filesystem, storeFor StoreFor, opts ...ProviderOption) *Provider

NewProvider creates a system Provider. storeFor is called once per Create to produce the oras.ReadOnlyTarget backing that agent's image.

func (*Provider) Create

func (a *Provider) Create(
	ctx context.Context, id uuid.UUID, ref spec.Reference, opts ...spec.Override,
) (executor.Agent, error)

Create prepares a chroot directory, reserves a loopback port for the runtime's gRPC server, and returns an Agent bound to both. The agent materializes itself on first Run.

func (*Provider) CreateWithOptions

func (a *Provider) CreateWithOptions(
	_ context.Context, id uuid.UUID, ref spec.Reference,
	extra []AgentOption, overrides ...spec.Override,
) (executor.Agent, error)

CreateWithOptions is Create plus per-instance AgentOptions (mounts, custom stdout, …). Kept separate so executor.Provider stays narrow.

func (*Provider) Destroy

func (a *Provider) Destroy(_ context.Context) error

Destroy removes all agent chroot directories.

func (*Provider) Load

func (a *Provider) Load(_ context.Context) ([]executor.Agent, error)

Load recovers previously created agents from their chroot directories. Each recovered agent gets the same instance options a freshly-created one would (a fresh address, log file, hostFS), and is marked already-materialised so it is not rebuilt. Per-agent load errors are collected and returned alongside the agents that did load, so one corrupt tree does not hide the rest.

func (*Provider) Registry

func (a *Provider) Registry() executor.Registry

Registry returns the executor.Registry façade, built once on first call.

type ProviderOption

type ProviderOption func(*Provider)

ProviderOption configures the system Provider.

func WithAgentDefaults

func WithAgentDefaults(opts ...AgentOption) ProviderOption

WithAgentDefaults sets default AgentOptions applied to every created/loaded agent.

func WithHostFS

func WithHostFS(fs billy.Filesystem) ProviderOption

WithHostFS overrides the non-chrooted billy filesystem the Provider (and the agents it creates) use for real host paths — mount symlink targets, local-runtime source files, and the log directory. Default is osfs.New("/"); tests pass memfs.New() to keep everything in memory. Applied at Provider level so newly-created agents inherit the same hostFS automatically.

func WithLocalRuntime

func WithLocalRuntime(path string) ProviderOption

WithLocalRuntime overrides the runtime binary with a local path (skips OCI pull).

func WithLogDir

func WithLogDir(dir string) ProviderOption

WithLogDir redirects each agent's runtime stdout/stderr to <dir>/<agent-id>.log (append mode). Set by consumers (like the openotters daemon) that want the subprocess output captured on disk rather than bleeding into their own stdout.

func WithLoopbackAllocator

func WithLoopbackAllocator(a LoopbackAllocator) ProviderOption

WithLoopbackAllocator overrides the default net.Listen-based allocator. Tests use it to hand out deterministic addresses without binding real ports. The default is defaultLoopbackAllocator, which binds 127.0.0.1:0 and closes the listener immediately.

func WithPuller

func WithPuller(p agentoci.Puller) ProviderOption

WithPuller sets the OCI puller for pulling runtime and tool binaries.

func WithRegistryAddr

func WithRegistryAddr(addr string) ProviderOption

WithRegistryAddr supplies the embedded registry's HTTP address ("host:port") so the system Registry can do List / Inspect / Remove via the OCI distribution spec endpoints. Empty string means those methods return ErrNotImplemented.

func WithRegistryCreatedAt

func WithRegistryCreatedAt(fn CreatedAtFunc) ProviderOption

WithRegistryCreatedAt supplies a callback returning the unix-seconds when a manifest was first written to the embedded registry. The daemon's EmbeddedRegistry has this info via on-disk mtime. Optional — without it, ImageInfo.CreatedUnix is 0.

func WithRegistryTarget

func WithRegistryTarget(target oras.Target) ProviderOption

WithRegistryTarget supplies the oras.Target the system Registry façade reads from / writes to. The daemon plumbs in its embedded registry's target here. Tests can omit it; the Registry methods then return ErrNotImplemented.

func WithUsageFetcher

func WithUsageFetcher(f agentoci.UsageFetcher) ProviderOption

WithUsageFetcher sets the OCI fetcher used to read each BIN's USAGE.md body at materialisation time. Nil disables doc extraction — materializeContent still stamps the conventional path on each ResolvedTool so the runtime stays consistent, but no file is written and the loader silently skips the doc.

type Spawner

type Spawner interface {
	Command(name string, args ...string) Cmd
}

Spawner produces a Cmd for a binary and args. Abstracted so tests can substitute a scripted stub instead of spawning real subprocesses.

type StoreFor

type StoreFor func(ref spec.Reference) oras.ReadOnlyTarget

StoreFor returns an OCI target backing a specific agent's ref. The Provider invokes it once per Create, so each agent gets a target scoped to its own image — typically a remote.Repository bound to the agent's repo in the caller's local registry.

Jump to

Keyboard shortcuts

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