runner

package
v0.3.1 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: 8 Imported by: 0

Documentation

Overview

Package runner is the seam between the worker's lease loop and what executes a leased task: the worker hands a Runner each Job and reports the Outcome to the dispatcher. The run pipeline (AGT-S1-T02, run-pipeline.md) implements Runner; Stub and Func stand in for it in tests and development.

Index

Constants

View Source
const (
	StatusDone       = string(v1alpha1.ResultDone)
	StatusFailed     = string(v1alpha1.ResultFailed)
	StatusNeedsInput = string(v1alpha1.ResultNeedsInput)
	StatusNoop       = string(v1alpha1.ResultNoop)
	StatusThrottled  = "throttled"
)

Outcome statuses (run-pipeline.md §Outcome to the worker): the Result statuses plus throttled, which is no Result at all (the task goes back to Pending).

View Source
const (
	ReasonLimit         = "limit"
	ReasonInvalidResult = "invalid-result"
	ReasonHarnessError  = "harness-error"
	// ReasonEnvironmentError: the VM workspace's environment (spec.environment) didn't come up,
	// or its system setup failed (workspace-run.md §The environment step).
	ReasonEnvironmentError = "environment-error"
	ReasonCancelled        = "cancelled"
)

Outcome reasons.

Variables

This section is empty.

Functions

func Reasons

func Reasons() []string

Reasons are every Outcome reason, without "" (no reason). A new reason constant goes here too: the run bundle's outcome (runbundle) accepts only these.

func Statuses

func Statuses() []string

Statuses are every Outcome status. A new status constant goes here too: the run bundle's outcome (runbundle) accepts only these.

Types

type Credentials

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

Credentials holds a task's current git credentials, safe for concurrent use: the task token (the lease's gitCredential) and one read-only token per private read repo (its readCredentials). A heartbeat swaps them together. Its String, Format and LogValue never print a token.

func NewCredentials

func NewCredentials(c apiclient.GitCredential, read ...apiclient.GitCredential) *Credentials

NewCredentials holds the task token c and the read-only tokens read.

func (*Credentials) Format

func (c *Credentials) Format(f fmt.State, _ rune)

Format prints String for every verb, so %v, %+v and %#v can't leak the token.

func (*Credentials) Get

Get returns the current task token.

func (*Credentials) LogValue

func (c *Credentials) LogValue() slog.Value

LogValue keeps the token out of slog.

func (*Credentials) MarshalJSON

func (c *Credentials) MarshalJSON() ([]byte, error)

MarshalJSON keeps the token out of JSON dumps.

func (*Credentials) Reads

func (c *Credentials) Reads() []apiclient.GitCredential

Reads returns the current read-only tokens.

func (*Credentials) Set

Set swaps in a refreshed task token.

func (*Credentials) SetReads

func (c *Credentials) SetReads(read []apiclient.GitCredential)

SetReads swaps in refreshed read-only tokens (heartbeat refreshedReadCredentials): they replace the previous ones.

func (*Credentials) String

func (c *Credentials) String() string

String describes the credential without its token.

type Func

type Func func(ctx context.Context, job *Job, sink Sink) (Outcome, error)

Func adapts a function to Runner.

func (Func) Run

func (f Func) Run(ctx context.Context, job *Job, sink Sink) (Outcome, error)

Run calls f.

type Job

type Job struct {
	// Lease is the dispatcher's lease response, passed through unchanged: the lease, the Task
	// and the git credential it came with (plus whatever the contract adds later).
	Lease apiclient.Lease
	// Git is the task's current git credential: the lease's, swapped when a heartbeat
	// returns a refreshed one. The credential helper answers from it.
	Git *Credentials
	// API is the dispatcher client, authenticated as the agent (prompt, context, transcript
	// upload, effects).
	API *apiclient.ClientWithResponses
	// Dispatcher is the dispatcher's base URL (FACTORY_API for the harness).
	Dispatcher string
	// AgentToken returns the agent's current token (FACTORY_TOKEN for the harness). Never log
	// it.
	AgentToken func() string
	// StartedAt is when the worker started the job (the drain deadline counts from it).
	StartedAt time.Time
}

Job is one leased task, as the worker hands it to a Runner.

func (*Job) TaskID

func (j *Job) TaskID() string

TaskID is the leased task's id.

type Outcome

type Outcome struct {
	// Result is the run's Result; nil when the run failed before producing one.
	Result *v1alpha1.Result
	// Status is done, failed, needs_input, noop or throttled.
	Status string
	// Reason qualifies a failure: limit, invalid-result, harness-error,
	// environment-error, cancelled.
	Reason string
	// ThrottledUntil is when the harness's limit resets (Status throttled); nil when unknown.
	ThrottledUntil *time.Time
	// TranscriptRef is the uploaded transcript's reference, if any.
	TranscriptRef string
}

Outcome is what a run ended with (run-pipeline.md).

type Runner

type Runner interface {
	Run(ctx context.Context, job *Job, sink Sink) (Outcome, error)
}

Runner executes one leased task. Run returns when the task is done, failed or throttled, or once ctx is cancelled (the dispatcher cancelled the task, the lease is gone, or the worker is shutting down); the worker decides what to report from the Outcome and why ctx ended. An error means the run broke before it produced an Outcome (reported as failed{harness-error}).

type Sink

type Sink interface {
	// Progress is one progress line (a summary; full detail goes to the transcript).
	Progress(v1alpha1.ProgressEvent)
	// Usage is token usage since the previous call (a delta, not a total).
	Usage(UsageDelta)
}

Sink takes what a run reports while it runs; the worker batches it into heartbeats.

type UsageDelta

type UsageDelta struct {
	InputTokens  int64
	OutputTokens int64
	CostUSD      *float64
}

UsageDelta is usage since the previous report. CostUSD is nil for subscription runs.

Jump to

Keyboard shortcuts

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