executor

Documentation

Overview

Package agent defines the lifecycle contract for a running agent and the shared status tracker used by concrete backends.

Index

• type Agent
• type ObjectPromptRequest
• type ObjectPrompter
• type PromptEvent
• type PromptRequest
• type Prompter
• type Provenance
• type Provider
• type ResolvedConfig
• type ResolvedTool
• type Runtime
  • func LoadRuntime(fs billy.Filesystem) (*Runtime, error)
  • func (rt *Runtime) WriteTo(fs billy.Filesystem) error
• type SessionMessage
• type SessionReader
• type Status
  • func WaitForStatus(ctx context.Context, o StatusObserver, target ...Status) (Status, error)
  • func (s Status) String() string
• type StatusObserver
• type StatusTracker
  • func NewStatusTracker() *StatusTracker
  • func (t *StatusTracker) Get() Status
  • func (t *StatusTracker) Set(s Status)
  • func (t *StatusTracker) Subscribe() (<-chan Status, func())
• type StreamPrompter

Types

type Agent

type Agent interface {
	UUID() uuid.UUID
	Runtime() *Runtime
	Prepare(ctx context.Context) error
	Run(ctx context.Context) error
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
	Remove(ctx context.Context) error

	StatusObserver
}

Agent defines the lifecycle contract for a running agent.

Prepare materializes the workspace synchronously without starting the runtime process. It's idempotent and safe to call concurrently; repeat calls return the same error. Callers who want init errors to surface before any Run goroutine is spawned should call Prepare first.

Run starts the runtime subprocess, blocking until it exits or ctx is cancelled. Run calls Prepare internally if the workspace has not yet been materialized; initialization errors are returned directly and also surfaced via Status (StatusInitError / StatusPullError / StatusModelError).

Start re-runs a previously-stopped agent on the already-materialized workspace. Blocks until the subprocess exits or ctx is cancelled, same contract as Run. Returns an error if the agent is already running or has been removed. Reuses the same workspace and loopback address.

Stop signals the running agent to exit and blocks until Run has returned or ctx is cancelled. Calling Stop on a non-running agent is a no-op.

Remove deletes the agent's on-disk state. Callers must Stop first and wait for Run to return before Remove; Remove transitions Status through StatusRemoving → StatusRemoved on success.

type ObjectPromptRequest

type ObjectPromptRequest struct {
	Prompt            string
	Schema            []byte
	SchemaName        string
	SchemaDescription string
}

ObjectPromptRequest carries a one-shot structured-output request: a user prompt plus a JSON Schema describing the response shape. No session id — structured generation is stateless and bypasses the agent's tool loop. SchemaName / SchemaDescription surface in tool-mode providers as the synthetic tool's name / description; they're optional.

type ObjectPrompter

type ObjectPrompter interface {
	PromptObject(ctx context.Context, req ObjectPromptRequest) ([]byte, error)
}

ObjectPrompter generates a JSON object that conforms to the supplied schema. The returned bytes are valid JSON suitable for piping into jq or for json.Unmarshal. Rare providers may produce invalid JSON even with repair; callers should treat a returned error as "no usable object" rather than checking bytes shape.

type PromptEvent

type PromptEvent struct {
	Type    string
	Step    int32
	Tool    string
	Content string
}

PromptEvent is a typed chat event yielded by StreamPrompter. Mirrors the runtime's gRPC ChatStreamEvent so callers can render progress (steps, tool calls, streaming text) without merging everything into one blob.

Known Type values: "step.start", "step.finish", "text.delta", "tool.call", "tool.result", "message.create", "error".

type PromptRequest

type PromptRequest struct {
	SessionID string
	Prompt    string
}

PromptRequest carries a chat request addressed at a specific session. Empty SessionID lets the runtime pick/create a default session.

type Prompter

type Prompter interface {
	Prompt(ctx context.Context, req PromptRequest, w io.Writer) error
}

Prompter returns the full assistant response as a single blob, discarding intermediate events. Use for simple unary request/response callers.

type Provenance

type Provenance struct {
	ImageDigest   string `yaml:"image_digest,omitempty" json:"image_digest,omitempty"`
	RuntimeRef    string `yaml:"runtime_ref,omitempty" json:"runtime_ref,omitempty"`
	RuntimeDigest string `yaml:"runtime_digest,omitempty" json:"runtime_digest,omitempty"`
}

Provenance records the OCI digests of the artifacts that materialise an agent: the agent image itself, the runtime image it executes against, and the BIN tool images per ResolvedTool. Optional — populated only when the workspace is given a digest resolver (today: the openotters daemon's local registry resolver). Lets a host operator answer "exactly which bytes is this agent running?" without re-querying any registry.

type Provider

type Provider interface {
	// Create materializes and prepares an agent with the given ID, returning it ready to Run.
	Create(ctx context.Context, id uuid.UUID, ref spec.Reference, opts ...spec.Override) (Agent, error)

	// Load recovers previously created agents from the backend.
	Load(ctx context.Context) ([]Agent, error)

	// Destroy removes all agents and associated artifacts.
	Destroy(ctx context.Context) error
}

Provider manages agent lifecycle on a specific backend (system, docker, etc.).

type ResolvedConfig

type ResolvedConfig struct {
	Name       string         `yaml:"name" json:"name"`
	Model      string         `yaml:"model" json:"model"`
	Addr       string         `yaml:"addr,omitempty" json:"addr,omitempty"`
	APIBase    string         `yaml:"-" json:"-"`
	APIKey     string         `yaml:"-" json:"-"`
	Exec       []string       `yaml:"exec,omitempty" json:"exec,omitempty"`
	Provenance *Provenance    `yaml:"provenance,omitempty" json:"provenance,omitempty"`
	Tools      []ResolvedTool `yaml:"tools,omitempty" json:"tools,omitempty"`
}

ResolvedConfig holds the merged configuration after applying spec overrides. APIBase and APIKey are intentionally non-serialised (`yaml:"-"` / `json:"-"`): they are credentials resolved from providers.yaml on every (re)start and travel to the runtime subprocess via env (<PROVIDER>_API_KEY / <PROVIDER>_API_BASE), not via disk or argv. Older agent.yaml files that contain these fields are tolerated on load — yaml/json simply skip them.

type ResolvedTool

type ResolvedTool struct {
	Name        string `yaml:"name" json:"name"`
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	Binary      string `yaml:"binary" json:"binary"`
	Ref         string `yaml:"ref,omitempty" json:"ref,omitempty"`
	Digest      string `yaml:"digest,omitempty" json:"digest,omitempty"`
}

ResolvedTool describes a tool binary with its resolved filesystem path plus, when known, its source ref and OCI digest.

type Runtime

type Runtime struct {
	ID             uuid.UUID       `yaml:"id" json:"id"`
	Source         *spec.Agentfile `yaml:"source" json:"source"`
	ResolvedConfig `yaml:",inline" json:",inline"`
}

Runtime is the persistable result of creating an agent. It contains the original spec (source of truth) and the resolved configuration.

func LoadRuntime

func LoadRuntime(fs billy.Filesystem) (*Runtime, error)

LoadRuntime reads an Runtime from the given filesystem.

func (*Runtime) WriteTo

func (rt *Runtime) WriteTo(fs billy.Filesystem) error

WriteTo serializes the runtime to the given filesystem as YAML.

Source's nested types (spec.Agentfile, spec.Agent, …) carry json+yaml tags via the spec package; the linter's musttag check only inspects the top-level concrete type and misses the transitive coverage.

type SessionMessage

type SessionMessage struct {
	Role      string
	Content   string
	CreatedAt time.Time
}

SessionMessage is one stored turn from an agent's memory store. Role is conventionally "user" or "assistant".

type SessionReader

type SessionReader interface {
	ListSessionMessages(ctx context.Context, sessionID string, limit int) ([]SessionMessage, error)
}

SessionReader retrieves historical messages for a session from the running agent's memory store. Optional companion to Prompter / StreamPrompter: backends that don't expose session history simply don't implement it, and callers should type-assert and handle the negative case cleanly.

type Status

type Status uint8

Status represents the lifecycle state of an agent.

const (
	StatusCreated Status = iota
	StatusRunning
	StatusStopped
	StatusRemoving
	StatusRemoved
	StatusInitError
	StatusPullError
	StatusModelError
)

func WaitForStatus

func WaitForStatus(ctx context.Context, o StatusObserver, target ...Status) (Status, error)

WaitForStatus blocks until the observer reaches one of target or ctx is cancelled. Returns the observed status on hit, or ctx.Err() otherwise. The current status is checked first, so callers do not race the transition they are waiting for.

func (Status) String

func (s Status) String() string

String returns the lowercase name of the Status — used for logs and the `otters ps` STATUS column. Unknown numeric values render as "unknown" rather than panicking.

type StatusObserver

type StatusObserver interface {
	// Status returns the current state.
	Status() Status
	// SubscribeStatus returns a channel of status transitions and a cancel
	// function that closes the channel. Sends are non-blocking: slow
	// subscribers may miss intermediate transitions; call Status() to
	// resync. Always call cancel to avoid leaking the subscription.
	SubscribeStatus() (<-chan Status, func())
}

StatusObserver provides status tracking.

type StatusTracker

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

StatusTracker manages agent status and broadcasts transitions to subscribers.

func NewStatusTracker

func NewStatusTracker() *StatusTracker

NewStatusTracker creates a new status tracker.

func (*StatusTracker) Get

func (t *StatusTracker) Get() Status

Get returns the current status.

func (*StatusTracker) Set

func (t *StatusTracker) Set(s Status)

Set updates the status and broadcasts to all subscribers. Sends are non-blocking; a slow subscriber's channel may drop values.

func (*StatusTracker) Subscribe

func (t *StatusTracker) Subscribe() (<-chan Status, func())

Subscribe returns a channel of status transitions and a cancel function. Cancel closes the channel and removes the subscription. Callers must call cancel to avoid leaking the subscription; typical use is `defer cancel()`.

type StreamPrompter

type StreamPrompter interface {
	PromptStream(ctx context.Context, req PromptRequest, cb func(PromptEvent)) error
}

StreamPrompter delivers typed events as they arrive from the runtime's gRPC server — steps, tool calls, token deltas, and the final message.create with the rendered response. cb is invoked synchronously from the stream goroutine; slow callbacks backpressure the stream.