runbundle

package
v0.3.0 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: 27 Imported by: 0

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

View Source
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.

View Source
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.

View Source
const (
	EventStart    = "start"
	EventStep     = "step"
	EventProgress = "progress"
	EventUsage    = "usage"
	EventOutcome  = "outcome"
)

Event types.

View Source
const (
	StepOK    = "ok"
	StepError = "error"
)

Step states.

View Source
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).

View Source
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).

View Source
const EventVersion = 1

EventVersion is the event stream's version: every event's "v".

View Source
const MaxEventBytes = 64 << 10

MaxEventBytes caps one event's line, its newline included.

View Source
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.

View Source
const MaxStepError = 8 << 10

MaxStepError bounds a step event's Error (envrun's tail size), so a long error still fits its event line.

View Source
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.

View Source
const MinThrottle = time.Minute

MinThrottle is the throttle ClampThrottle gives a throttled outcome whose time is zero or not after now.

View Source
const Version = 1

Version is the bundle format's version: bundle.json's "version".

Variables

This section is empty.

Functions

func LooksLikeToken

func LooksLikeToken(s string) bool

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

UsageOf is u in apiclient.UsageDelta's wire shape.

func Write

func Write(dir string, m Manifest, f Files) (err error)

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

func WriteOutcome(outDir string, o Outcome) error

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

func Read(dir string) (*Bundle, error)

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

func (b *Bundle) ContextItem(i int) (c apiclient.TaskContext, gone bool, err error)

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.

func (*Bundle) Path

func (b *Bundle) Path(rel string) string

Path is the absolute path of a bundle-relative path.

func (*Bundle) Skills

func (b *Bundle) Skills() []Skill

Skills are the manifest's skills with Dir absolute, as harness.Skill has it.

func (*Bundle) TaskID

func (b *Bundle) TaskID() string

TaskID is the bundle's task id.

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 NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder reads from r.

func (*Decoder) Next

func (d *Decoder) Next() (Event, error)

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

func NewEncoder(w io.Writer, now func() time.Time) *Encoder

NewEncoder writes to w; now stamps an event whose At is zero.

func (*Encoder) Encode

func (enc *Encoder) Encode(e Event) error

Encode writes e as one line, its V set to EventVersion. A line over MaxEventBytes is refused and nothing is written.

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

func OutcomeEvent(o Outcome) Event

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 GitRead

type GitRead struct {
	Repo      string   `json:"repo"`
	ReadRepos []string `json:"readRepos,omitempty"`
}

GitRead is one read credential's scope.

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

func (m Manifest) Validate() error

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 OutcomeOf

func OutcomeOf(o runner.Outcome, transcript string) Outcome

OutcomeOf is the wire form of o; transcript is the transcript's file name, or "".

func ReadOutcome

func ReadOutcome(outDir string, now time.Time) (Outcome, error)

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

func (o Outcome) ClampThrottle(now time.Time) Outcome

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.

func (Outcome) Runner

func (o Outcome) Runner() runner.Outcome

Runner is o as a runner.Outcome. TranscriptRef is left empty: the supervisor uploads the transcript and sets it.

func (Outcome) Validate

func (o Outcome) Validate() error

Validate checks Status and Reason against runner.Statuses and runner.Reasons, that ThrottledUntil is set only for a throttled outcome, and Transcript. Its errors never quote a value: an outcome comes from the untrusted VM.

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.

func StepOf

func StepOf(name string, d time.Duration, err error) *Step

StepOf is the Step for an OnStep call. An error over MaxStepError bytes is cut there, on a UTF-8 boundary, and ends with "…(truncated)".

type ValidationError

type ValidationError struct {
	Field   string
	Message string
}

ValidationError is a bundle, an outcome or an event that breaks a rule.

func (*ValidationError) Error

func (e *ValidationError) Error() string

Jump to

Keyboard shortcuts

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