runner

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Sep 15, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package runner provides a durable, authenticated local execution service.

Index

Constants

View Source 
const (
	EventAccepted   = "accepted"
	EventStarted    = "started"
	EventProgress   = "progress"
	EventCheckpoint = "checkpoint"
	EventNeedsInput = "needs_input"
	EventArtifact   = "artifact"
	EventCompleted  = "completed"
	EventFailed     = "failed"
	EventCancelled  = "cancelled"
)

EventType values are the bounded, replayable events exposed by the runner.

View Source 
const (
	ErrorInvalidRequest        = "invalid_request"
	ErrorUnauthorized          = "unauthorized"
	ErrorForbidden             = "forbidden"
	ErrorUnsupportedVersion    = "unsupported_version"
	ErrorUnsupportedCapability = "unsupported_capability"
	ErrorBusy                  = "busy"
	ErrorStaleAttempt          = "stale_attempt"
	ErrorIdempotencyConflict   = "idempotency_conflict"
	ErrorCheckpointUnavailable = "checkpoint_unavailable"
	ErrorCursorExpired         = "cursor_expired"
	ErrorUnavailable           = "unavailable"
)

ErrorCode values are stable protocol errors. Callers should branch on Code, not on Message.

View Source 
const ProtocolVersion = "runner/v1"

ProtocolVersion is the wire protocol implemented by the local runner.

Variables

This section is empty.

Functions

This section is empty.

Types

type Artifact 

type Artifact struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	Digest    string    `json:"digest"`
	Length    int64     `json:"length"`
	MediaType string    `json:"mediaType"`
	CreatedAt time.Time `json:"createdAt"`
}

Artifact is an immutable, named result reference.

type ArtifactResponse 

type ArtifactResponse struct {
	Artifact
}

ArtifactResponse contains immutable artifact metadata and bytes are served by the artifact endpoint. It is kept separate so callers never receive a filesystem path.

type ArtifactSpec 

type ArtifactSpec struct {
	Name      string `json:"name"`
	Path      string `json:"path,omitempty"`
	MediaType string `json:"mediaType,omitempty"`
	Digest    string `json:"digest,omitempty"`
}

ArtifactSpec is an approved logical artifact. Path is relative to the task worktree and is only used when the adapter reports an artifact event.

type CancelRequest 

type CancelRequest struct {
	ProtocolVersion string `json:"protocolVersion,omitempty"`
	RequestID       string `json:"requestID"`
	TaskID          string `json:"taskID"`
	AttemptID       string `json:"attemptID"`
	AttemptEpoch    uint64 `json:"attemptEpoch"`
}

CancelRequest requests cancellation of an active attempt.

type Capabilities 

type Capabilities struct {
	ProtocolVersion string              `json:"protocolVersion"`
	RunnerID        string              `json:"runnerID"`
	Version         string              `json:"version"`
	OS              string              `json:"os"`
	Architecture    string              `json:"architecture"`
	Harnesses       []HarnessCapability `json:"harnesses,omitempty"`
	Toolchains      []string            `json:"toolchains,omitempty"`
	Environment     []string            `json:"environment,omitempty"`
	Verification    []string            `json:"verificationCapabilities,omitempty"`
	Capacity        Capacity            `json:"capacity"`
	Ready           bool                `json:"ready"`
	Reasons         []string            `json:"reasons,omitempty"`
}

Capabilities is returned by GET /runner/v1/capabilities.

type Capacity 

type Capacity struct {
	Maximum int `json:"maximum"`
	Used    int `json:"used"`
}

Capacity is the execution capacity advertised by a runner.

type Clarification 

type Clarification struct {
	ID   string `json:"id"`
	Text string `json:"text"`
}

Clarification is a bounded product question captured from a genuine request-user-input harness interaction. Its ID is stable for one session, turn, and interaction item and must be echoed by a matching resume.

type Config 

type Config struct {
	ProtocolVersion string                      `json:"protocolVersion,omitempty"`
	RunnerID        string                      `json:"runnerID"`
	Version         string                      `json:"version,omitempty"`
	Listen          string                      `json:"listen,omitempty"`
	StateDir        string                      `json:"stateDir"`
	TokenFile       string                      `json:"tokenFile"`
	Token           string                      `json:"-"`
	Toolchains      []string                    `json:"toolchains,omitempty"`
	Environment     []string                    `json:"environment,omitempty"`
	Verification    []string                    `json:"verificationCapabilities,omitempty"`
	MaximumCapacity int                         `json:"maximumCapacity,omitempty"`
	MaxEvents       int                         `json:"maxEvents,omitempty"`
	MaxEventBytes   int                         `json:"maxEventBytes,omitempty"`
	MaxBodyBytes    int                         `json:"maxBodyBytes,omitempty"`
	MaxArtifactSize int64                       `json:"maxArtifactSize,omitempty"`
	Repositories    map[string]RepositoryConfig `json:"repositories,omitempty"`
	Resources       map[string]ResourceConfig   `json:"resources,omitempty"`
}

Config contains local runner identity, enrollment, persistence, and capability settings. It is intentionally independent of the Codex adapter.

func LoadConfig 

func LoadConfig(path string) (Config, error)

LoadConfig reads a JSON runner configuration. A missing path is equivalent to an empty configuration and is useful for callers that supply Config directly; the CLI requires a path when --config is set.

type Error 

type Error struct {
	Code             string   `json:"code"`
	Retryable        bool     `json:"retryable"`
	Message          string   `json:"message"`
	Receipt          *Receipt `json:"receipt,omitempty"`
	SnapshotRequired bool     `json:"snapshotRequired,omitempty"`
}

Error describes a structured protocol failure.

func (*Error) Error 

func (e *Error) Error() string

type Event 

type Event struct {
	Cursor       uint64          `json:"cursor"`
	Timestamp    time.Time       `json:"timestamp"`
	AttemptEpoch uint64          `json:"attemptEpoch"`
	Type         string          `json:"type"`
	Message      string          `json:"message,omitempty"`
	Data         json.RawMessage `json:"data,omitempty"`
}

Event is an ordered, durable attempt event. Data is bounded by the runner before the event is persisted.

type ExecutionLimits 

type ExecutionLimits struct {
	MaxDurationSeconds int `json:"maxDurationSeconds,omitempty"`
	MaxOutputBytes     int `json:"maxOutputBytes,omitempty"`
	MaxTurns           int `json:"maxTurns,omitempty"`
}

ExecutionLimits bounds adapter execution. The runner enforces duration and emitted-output limits; MaxTurns is limited to one because one adapter launch represents one turn in this protocol revision.

type HarnessCapability 

type HarnessCapability struct {
	Name    string   `json:"name"`
	Version string   `json:"version"`
	Ready   bool     `json:"ready"`
	Reasons []string `json:"reasons,omitempty"`
}

HarnessCapability describes an installed harness and its readiness.

type Phase 

type Phase string

Phase describes the durable lifecycle of an attempt. 

const (
	PhaseAccepted   Phase = "accepted"
	PhaseStarting   Phase = "starting"
	PhaseRunning    Phase = "running"
	PhaseNeedsInput Phase = "needs_input"
	PhaseCancelling Phase = "cancelling"
	PhaseCancelled  Phase = "cancelled"
	PhaseCompleted  Phase = "completed"
	PhaseFailed     Phase = "failed"
)

func (Phase) IsTerminal 

func (p Phase) IsTerminal() bool

IsTerminal reports whether p no longer has a live execution.

type Receipt 

type Receipt struct {
	ProtocolVersion string         `json:"protocolVersion"`
	TaskID          string         `json:"taskID"`
	AttemptID       string         `json:"attemptID"`
	AttemptEpoch    uint64         `json:"attemptEpoch"`
	Phase           Phase          `json:"phase"`
	SessionID       string         `json:"sessionID,omitempty"`
	Workdir         string         `json:"workdir,omitempty"`
	Cursor          uint64         `json:"cursor"`
	Blocker         string         `json:"blocker,omitempty"`
	Clarification   *Clarification `json:"clarification,omitempty"`
	Resources       []string       `json:"resources,omitempty"`
	LastError       *Error         `json:"lastError,omitempty"`
	Artifacts       []Artifact     `json:"artifacts,omitempty"`
	AcceptedAt      time.Time      `json:"acceptedAt"`
	UpdatedAt       time.Time      `json:"updatedAt"`
}

Receipt is the durable view of an attempt returned by start and inspect.

type RepositoryConfig 

type RepositoryConfig struct {
	Source         string `json:"source"`
	BaseCommit     string `json:"baseCommit,omitempty"`
	FetchRemoteURL string `json:"fetchRemoteURL,omitempty"`
}

RepositoryConfig enrolls one local Git source. The source is read-only from the runner's point of view; attempts are cloned into task-owned worktrees. FetchRemoteURL is operator-only enrollment data; it is never accepted from a start request or exposed as a runner protocol field.

type ResourceConfig 

type ResourceConfig struct {
	Kind     string            `json:"kind,omitempty"`
	Capacity int               `json:"capacity,omitempty"`
	Labels   map[string]string `json:"labels,omitempty"`
}

ResourceConfig names a preconfigured shared resource. Capacity is a count of simultaneous reservations; it does not cause the runner to provision the resource.

type ResourceRequest 

type ResourceRequest struct {
	Name string `json:"name"`
}

ResourceRequest identifies a preconfigured shared resource. Resource values are names only: the runner never provisions ports, containers, or clusters.

type ResumeRequest 

type ResumeRequest struct {
	ProtocolVersion string          `json:"protocolVersion,omitempty"`
	RequestID       string          `json:"requestID"`
	TaskID          string          `json:"taskID"`
	AttemptID       string          `json:"attemptID"`
	AttemptEpoch    uint64          `json:"attemptEpoch"`
	SessionID       string          `json:"sessionID,omitempty"`
	ClarificationID string          `json:"clarificationID,omitempty"`
	ApprovedInput   json.RawMessage `json:"approvedInput,omitempty"`
	Resolution      string          `json:"resolution,omitempty"`
	Instructions    string          `json:"instructions,omitempty"`
}

ResumeRequest continues a needs-input attempt in its existing session.

type Runner 

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

Runner is the generic local execution service. It owns protocol state and workspace/resource boundaries; harness.Adapter owns the child process.

func New 

func New(cfg Config, adapter harness.Adapter) (*Runner, error)

New creates a runner, loads durable state, probes the harness without model calls, and acquires the state-directory singleton lock.

func NewRunner 

func NewRunner(cfg Config, adapter harness.Adapter) (*Runner, error)

NewRunner is an explicit alias for callers that prefer the type name.

func NewServer 

func NewServer(cfg Config, adapter harness.Adapter) (*Runner, error)

NewServer is retained as a transport-oriented constructor alias.

func (*Runner) Cancel 

func (r *Runner) Cancel(_ context.Context, request CancelRequest) (Receipt, error)

Cancel requests adapter cancellation. Active attempts remain cancelling until adapter exit. Unseen attempts receive a durable cancellation fence before acknowledgement, so a delayed Start cannot launch them.

func (*Runner) Capabilities 

func (r *Runner) Capabilities() Capabilities

Capabilities returns a copy of the current discovery document.

func (*Runner) Close 

func (r *Runner) Close() error

Close gracefully drains active adapters, waits for them to exit, closes the listener, and releases the singleton state lock. An adapter interrupted by this shutdown remains resumable; an explicit Cancel request is still terminal.

func (*Runner) Handler 

func (r *Runner) Handler() http.Handler

Handler returns the authenticated loopback runner protocol handler. The handler itself does not bind a socket; ListenAndServe enforces loopback.

func (*Runner) Inspect 

func (r *Runner) Inspect(_ context.Context, attemptID string) (Receipt, error)

Inspect returns the durable current receipt.

func (*Runner) ListenAndServe 

func (r *Runner) ListenAndServe(ctx context.Context) error

ListenAndServe starts the runner on the configured loopback address and stops when ctx is cancelled.

func (*Runner) Resume 

func (r *Runner) Resume(ctx context.Context, request ResumeRequest) (Receipt, error)

Resume continues a needs-input attempt with its existing session and worktree. It never accepts a different instruction envelope or session ID.

func (*Runner) Start 

func (r *Runner) Start(ctx context.Context, request StartRequest) (Receipt, error)

Start accepts an approved attempt and returns once its receipt and accepted event have been durably persisted. Execution continues asynchronously.

type StartRequest 

type StartRequest struct {
	ProtocolVersion        string                   `json:"protocolVersion,omitempty"`
	RequestID              string                   `json:"requestID"`
	TaskID                 string                   `json:"taskID"`
	AttemptID              string                   `json:"attemptID"`
	AttemptEpoch           uint64                   `json:"attemptEpoch"`
	RepositoryID           string                   `json:"repositoryID"`
	BaseCommit             string                   `json:"baseCommit"`
	Instructions           string                   `json:"instructions"`
	Model                  string                   `json:"model,omitempty"`
	ApprovedInput          json.RawMessage          `json:"approvedInput,omitempty"`
	RequiredCapabilities   []string                 `json:"requiredCapabilities,omitempty"`
	RequiredToolchains     []string                 `json:"requiredToolchains,omitempty"`
	RequiredEnvironment    []string                 `json:"requiredEnvironment,omitempty"`
	RequiredHarness        string                   `json:"requiredHarness,omitempty"`
	RequiredHarnessVersion string                   `json:"requiredHarnessVersion,omitempty"`
	ExportGitResult        bool                     `json:"exportGitResult,omitempty"`
	Limits                 ExecutionLimits          `json:"limits,omitempty"`
	Verification           VerificationRequirements `json:"verification,omitempty"`
	Resources              []ResourceRequest        `json:"resources,omitempty"`
	Artifacts              []ArtifactSpec           `json:"artifacts,omitempty"`
}

StartRequest is the approved execution envelope accepted by Start.

type VerificationRequirements 

type VerificationRequirements struct {
	Names    []string `json:"names,omitempty"`
	Commands []string `json:"commands,omitempty"`
}

VerificationRequirements records the checks approved for an attempt.

Source Files

View all Source files

Directories

Path Synopsis
Package harness defines the public execution seam for runner adapters.
 Package harness defines the public execution seam for runner adapters.
codex
Package codex adapts the Codex app-server protocol to the runner harness.
 Package codex adapts the Codex app-server protocol to the runner harness.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.