Documentation
¶
Overview ¶
Package runbundle is the run bundle the supervisor writes for a VM workspace, the outcome the VM writes back and the event stream between them (workspace-run.md §The run bundle). It imports only v1alpha1, the apiclient and runner types and the standard library, and it has no network code. The bundle holds no secret: no field of any type here carries a token.
Index ¶
- Constants
- func LooksLikeToken(s string) bool
- func RunnerUsage(w apiclient.UsageDelta) runner.UsageDelta
- func UsageOf(u runner.UsageDelta) *apiclient.UsageDelta
- func Write(dir string, m Manifest, f Files) (err error)
- func WriteOutcome(outDir string, o Outcome) error
- type Bundle
- type CodexAccount
- type ContextFile
- type Decoder
- type Encoder
- type Event
- type Files
- type Gateway
- type GitAccess
- type GitRead
- type Manifest
- type Outcome
- type Skill
- type Start
- type Step
- type ValidationError
Constants ¶
const ( ManifestFile = "bundle.json" TaskFile = "task.json" PromptFile = "prompt.md" ContextDir = "context" SchemaFile = "output-schema.json" SkillsDir = "skills" CAFile = "gateway/ca.pem" CodexFile = "codex/account.json" )
The bundle's files, relative to its root.
const ( MaxManifestBytes = 1 << 20 MaxTaskBytes = 1 << 20 MaxPromptBytes = 1 << 20 MaxContextBytes = 4 << 20 MaxContextFile = 2 * MaxContextBytes MaxSchemaBytes = 1 << 20 MaxCABytes = 1 << 20 )
The caps Read and Write apply: the bounds the pipeline applies on the host (the prompt maxPrompt, a context item's content maxContext, the schema maxSchema). A context file is the item's JSON, so its file may be up to MaxContextFile.
const ( EventStart = "start" EventStep = "step" EventProgress = "progress" EventUsage = "usage" EventOutcome = "outcome" )
Event types.
const ( StepOK = "ok" StepError = "error" )
Step states.
const ( OutDir = "out" OutcomeFile = "outcome.json" TranscriptFile = "transcript.jsonl.gz" EnvironmentLog = "environment.log" )
The VM's outputs, under the workspace root's OutDir (/work/out).
const DefaultDispatcherURL = "http://dispatcher.factory.internal"
DefaultDispatcherURL is the dispatcher as the VM sees it: the gateway serves the name and adds the run's credential (phase 4).
const EventVersion = 1
EventVersion is the event stream's version: every event's "v".
const MaxEventBytes = 64 << 10
MaxEventBytes caps one event's line, its newline included.
const MaxOutcomeBytes = 2 << 20
MaxOutcomeBytes caps outcome.json. The outcome event carries the Outcome without its Result (see OutcomeEvent), so it fits an event line.
const MaxStepError = 8 << 10
MaxStepError bounds a step event's Error (envrun's tail size), so a long error still fits its event line.
const MaxThrottle = 6 * time.Hour
MaxThrottle bounds a VM's throttle: ReadOutcome and ClampThrottle move a later ThrottledUntil to now + MaxThrottle, so one VM can't park the agent host. A longer real limit (codex's weekly cap) throttles again each window.
const MinThrottle = time.Minute
MinThrottle is the throttle ClampThrottle gives a throttled outcome whose time is zero or not after now.
const Version = 1
Version is the bundle format's version: bundle.json's "version".
Variables ¶
This section is empty.
Functions ¶
func LooksLikeToken ¶
LooksLikeToken reports whether s holds something shaped like a credential.
func RunnerUsage ¶
func RunnerUsage(w apiclient.UsageDelta) runner.UsageDelta
RunnerUsage is a usage payload as a runner.UsageDelta.
func UsageOf ¶
func UsageOf(u runner.UsageDelta) *apiclient.UsageDelta
UsageOf is u in apiclient.UsageDelta's wire shape.
func Write ¶
Write lays out the bundle at dir, atomically: it refuses an existing dir, removes a leftover dir+".tmp", writes everything there (directories 0700, files 0600, a skill's executable files 0700), fsyncs the files and renames it to dir. A failure removes the temp dir. Write sets what it lays out in m (Version when 0, the default Dispatcher, the file names, Context from the task and f.Context, Codex from f) and refuses what Read would.
func WriteOutcome ¶
WriteOutcome validates o and writes it to outDir/OutcomeFile through a temp file and a rename, creating outDir (0700) when needed.
Types ¶
type Bundle ¶
type Bundle struct {
Dir string
Manifest Manifest
Task v1alpha1.Task
Prompt []byte
// Context holds the items that have a file; Gone items are absent (see ContextItem).
Context map[int]apiclient.TaskContext
// OutputSchema is nil when the schema answered 404.
OutputSchema []byte
// CAFile is the gateway CA's absolute path; "" when the bundle has none.
CAFile string
}
Bundle is a bundle Read and validated.
func Read ¶
Read opens the bundle at dir through an os.Root, reads bundle.json, task.json, the prompt, the context files and the schema, each capped, refuses a symlink on the way to any of them, and validates the manifest against the task. It doesn't read the skills (they were bounded when materialised); it checks each skill's Dir is a directory.
func (*Bundle) ContextItem ¶
ContextItem is the non-repo context item i, as pipeline.PromptSource's Context gives it: gone is true when it answered 404. An index the bundle doesn't list is an error.
type CodexAccount ¶
type CodexAccount struct {
AccountID string `json:"accountId"`
UserID string `json:"userId"`
PlanType string `json:"planType"`
}
CodexAccount identifies the ChatGPT account codex runs as. Identifiers, not credentials (P1 §5): the gateway adds the credential.
type ContextFile ¶
type ContextFile struct {
Index int `json:"index"`
File string `json:"file,omitempty"`
Gone bool `json:"gone,omitempty"`
}
ContextFile is one non-repo context item: its file, or Gone when it answered 404.
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder reads the events an untrusted VM wrote.
func (*Decoder) Next ¶
Next returns the next event, or io.EOF at the end. It skips events of unknown types (a newer VM may talk to an older supervisor) and blank lines. A line over MaxEventBytes, one that isn't an event, and an event of an unknown version or without its payload are each a *ValidationError; the line is consumed, so the caller may go on to the next.
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder writes events as JSON Lines. It's safe for concurrent use: the pipeline's Sink is called from several goroutines.
func NewEncoder ¶
NewEncoder writes to w; now stamps an event whose At is zero.
type Event ¶
type Event struct {
V int `json:"v"`
Type string `json:"type"`
At time.Time `json:"at"`
Start *Start `json:"start,omitempty"`
Step *Step `json:"step,omitempty"`
Progress *v1alpha1.ProgressEvent `json:"progress,omitempty"`
Usage *apiclient.UsageDelta `json:"usage,omitempty"`
Outcome *Outcome `json:"outcome,omitempty"`
}
Event is one line of factory-agent run's stdout. It has one payload: the pointer for its Type. An outcome event's Outcome has no Result (OutcomeEvent): the Result is in outcome.json.
func OutcomeEvent ¶
OutcomeEvent is the outcome event for o: o without its Result, which can be larger than an event line and lives in outcome.json (written first).
type Files ¶
type Files struct {
// Task is the lease's Task (never the Lease: it has the credentials).
Task v1alpha1.Task
// Prompt is GET /tasks/{id}/prompt, byte-exact.
Prompt []byte
// Context holds, by index, the apiclient.TaskContext JSON of each non-repo context item
// that answered 200. A non-repo item missing from it is Gone.
Context map[int][]byte
// OutputSchema is GET /tasks/{id}/output-schema; nil when it answered 404.
OutputSchema []byte
// SkillsDir holds the materialised plugin dirs; "" when there are no skills.
SkillsDir string
// CA is the gateway CA's PEM (the public half).
CA []byte
// Codex is the account, only when the task's harness is codex.
Codex *CodexAccount
}
Files is what Write lays out beside bundle.json.
type Gateway ¶
type Gateway struct {
CAFile string `json:"caFile,omitempty"`
NoProxy []string `json:"noProxy,omitempty"`
}
Gateway is what the VM needs to use its gateway; its address is the --proxy flag.
type GitAccess ¶
type GitAccess struct {
Provider string `json:"provider"`
Host string `json:"host"`
Repo string `json:"repo"`
// Permissions are the credential's permissions (contents: read|write, …).
Permissions map[string]string `json:"permissions,omitempty"`
// Reads are the read credentials' scopes.
Reads []GitRead `json:"reads,omitempty"`
}
GitAccess is the lease's gitCredential and readCredentials without their tokens. It has no token field: the gateway holds the tokens.
type Manifest ¶
type Manifest struct {
Version int `json:"version"`
RunID string `json:"runId"` // run_…; never a token
LeaseID string `json:"leaseId"`
TaskID string `json:"taskId"`
// StartedAt is the lease's start, for the record; limits use --remaining.
StartedAt time.Time `json:"startedAt"`
// Dispatcher is FACTORY_API in the VM; Write defaults it to DefaultDispatcherURL.
Dispatcher string `json:"dispatcher"`
Gateway Gateway `json:"gateway"`
Git GitAccess `json:"git"`
// Prompt, Context's files, OutputSchema ("" when the schema answered 404) and
// Gateway.CAFile are paths relative to the bundle; Write sets them.
Prompt string `json:"prompt"`
Context []ContextFile `json:"context,omitempty"`
OutputSchema string `json:"outputSchema,omitempty"`
// Skills are the materialised skills, their Dir relative to the bundle.
Skills []Skill `json:"skills,omitempty"`
// Codex is set only when the task's harness is codex.
Codex *CodexAccount `json:"codex,omitempty"`
}
Manifest is bundle.json.
func (Manifest) Validate ¶
Validate checks the rules that need only the manifest: the version, the ids, the dispatcher URL, every path, the skills, NoProxy and that no field is shaped like a token. Read and Write also check it against task.json, and scan task.json and every context file for tokens too.
type Outcome ¶
type Outcome struct {
Status string `json:"status"`
Reason string `json:"reason,omitempty"`
ThrottledUntil *time.Time `json:"throttledUntil,omitempty"`
Result *v1alpha1.Result `json:"result,omitempty"`
Transcript string `json:"transcript,omitempty"`
}
Outcome is runner.Outcome on the wire: outcome.json and the outcome event. Transcript is the transcript's file name under OutDir (TranscriptFile), or "" when the run has none.
func ReadOutcome ¶
ReadOutcome reads outDir/OutcomeFile, written by the untrusted VM: outDir must be a real directory (not a symlink), and the file a regular file with one link (no symlink, FIFO, device or second link, checked before and after opening it, and opened non-blocking), at most MaxOutcomeBytes and valid. Its ThrottledUntil is clamped by now (ClampThrottle).
func (Outcome) ClampThrottle ¶
ClampThrottle bounds a throttled outcome's ThrottledUntil by the reader's now: a time after now + MaxThrottle becomes that, and a zero time or one not after now becomes now + MinThrottle. A nil ThrottledUntil (unknown) stays nil: the worker applies its default. ReadOutcome applies it; the supervisor applies it to an outcome event too.
type Skill ¶
type Skill struct {
Name string `json:"name"`
Plugin string `json:"plugin"`
Dir string `json:"dir"`
}
Skill is harness.Skill with Dir relative to the bundle: skills/<plugin>/skills/<name>.
type Start ¶
type Start struct {
Version int `json:"version"`
RunID string `json:"runId"`
TaskID string `json:"taskId"`
}
Start is sent once the bundle is read: Version is the bundle's.
type Step ¶
type Step struct {
Name string `json:"name"`
State string `json:"state"`
MS int64 `json:"ms"`
Error string `json:"error,omitempty"`
}
Step is one OnStep call: a pipeline step or an environment sub-step. Error is the step's redacted error.
type ValidationError ¶
ValidationError is a bundle, an outcome or an event that breaks a rule.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string