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
- func Reasons() []string
- func Statuses() []string
- type Credentials
- func (c *Credentials) Format(f fmt.State, _ rune)
- func (c *Credentials) Get() apiclient.GitCredential
- func (c *Credentials) LogValue() slog.Value
- func (c *Credentials) MarshalJSON() ([]byte, error)
- func (c *Credentials) Reads() []apiclient.GitCredential
- func (c *Credentials) Set(n apiclient.GitCredential)
- func (c *Credentials) SetReads(read []apiclient.GitCredential)
- func (c *Credentials) String() string
- type Func
- type Job
- type Outcome
- type Runner
- type Sink
- type UsageDelta
Constants ¶
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).
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 ¶
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 ¶
func (c *Credentials) Get() apiclient.GitCredential
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 ¶
func (c *Credentials) Set(n apiclient.GitCredential)
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 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.
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 ¶
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 ¶
UsageDelta is usage since the previous report. CostUSD is nil for subscription runs.