job

package
v0.7.51-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package job is the document a device sends a remote runhost to start one run: the release it verified, what it decided about the run, and what the run needs from the device. It is typed and versioned, and it is the only thing the service reads from a device before it runs anything.

On the wire a job is one length-prefixed JSON document at the start of the `job` verb's input. The service then answers whether it needs the release's archive (FrameRelease); when it does, the archive's bytes follow the document, exactly Release.Size of them.

Index

Constants

View Source
const (
	StateVerified  = "verified"
	StateUnsigned  = "unsigned"
	StateUnscanned = "unscanned"
)

Attestation states a release may arrive in, as the device judged it.

View Source
const (
	AdapterDockerAgent = "docker-agent"
	AdapterClaudeImage = "claude-image"
	AdapterCodexImage  = "codex-image"
	AdapterCopilot     = "copilot-image"
)

The adapters a run on a runhost may name: the default and the vendors' container harnesses, every one a container under gVisor.

View Source
const (
	MaxSecret  = 64 << 10
	MaxSecrets = 256
)

MaxSecret bounds one secret's value, and MaxSecrets their number.

View Source
const MaxArchive = 512 << 20

MaxArchive bounds a release archive a job carries: the CLI's own cap on a downloaded archive.

View Source
const MaxDesktopToken = 512

MaxDesktopToken bounds the run token a binding carries.

View Source
const MaxDocument = 1 << 20

MaxDocument bounds a job document on the wire.

View Source
const MaxKnownLines = 32

MaxKnownLines bounds the known_hosts lines one target host carries.

View Source
const RunhostDefault = "default"

RunhostDefault is RunhostModel's word for the runhost's default saved model, whichever it is when the run starts.

View Source
const Version = 1

Version is the job document's version.

Variables

ImageAdapters are the adapters a runhost runs.

Functions

func RunhostAdapter added in v0.7.6

func RunhostAdapter(asked string) (name string, mapped bool, err error)

RunhostAdapter is the adapter a runhost runs for the one a person asked for: Claude Code's and Codex's images for the installed claude and codex, which are host processes, and any image adapter as it is. mapped says the asked adapter was replaced.

func SecretValueOK added in v0.6.1019

func SecretValueOK(v string) bool

SecretValueOK says whether v is a value the job's secrets file carries as it is: one line, with no NUL and no space at either end, which the file's reader would trim.

func ValidID

func ValidID(id string) bool

ValidID says whether id can name a job or a device.

func ValidKeyEnv

func ValidKeyEnv(name string) bool

ValidKeyEnv says whether name may carry a model key into a run on a runhost: a key's name, and none the run's environment reserves.

func ValidRunhostModel added in v0.7.39

func ValidRunhostModel(ref string) bool

ValidRunhostModel says whether ref can name a saved model of the runhost's: a saved model's id, or RunhostDefault.

func Write

func Write(w io.Writer, j *Job) error

Write writes the job document to w, length-prefixed.

Types

type Connection added in v0.6.1019

type Connection struct {
	AccessToken string    `json:"accessToken"`
	ExpiresAt   time.Time `json:"expiresAt"`
	Issuer      string    `json:"issuer,omitempty"`
	Scopes      []string  `json:"scopes,omitempty"`
}

Connection is one OAuth server's access token for the run.

type Desktop added in v0.7.33

type Desktop struct {
	Run   string        `json:"run"`
	Bound desktop.Bound `json:"bound"`
}

Desktop is a device's binding to Agentry Desktop, carried to the runhost: the run id the device bound, the run token Agentry Desktop issued, and the bound servers' tools and computer use as Agentry Desktop answered the bind. The token lives in the job's own 0600 file on the runhost while the run lasts, and is deleted with it.

type Destination added in v0.6.1019

type Destination struct {
	Name          string `json:"name"`
	Kind          string `json:"kind"`
	URL           string `json:"url,omitempty"`
	Bucket        string `json:"bucket,omitempty"`
	Prefix        string `json:"prefix,omitempty"`
	Region        string `json:"region,omitempty"`
	Endpoint      string `json:"endpoint,omitempty"`
	Secret        string `json:"secret"`
	Authorization string `json:"authorization,omitempty"`
	AccessKeyID   string `json:"accessKeyId,omitempty"`
}

Destination is one destination the run delivers to: a webhook or a bucket, at a public address, with its credentials.

type Job

type Job struct {
	V int `json:"v"`
	// ID names the job on the server: its job directory and its sealed
	// output. The device makes it.
	ID string `json:"id"`
	// Device is the id of the device that sent the job, one of the paired
	// devices.
	Device  string  `json:"device"`
	Release Release `json:"release"`
	Run     Run     `json:"run"`
}

Job is one run on a remote runhost.

func Read

func Read(r io.Reader) (*Job, error)

Read reads a job document written by Write and validates it.

func (*Job) Validate

func (j *Job) Validate() error

Validate checks that the job is one this version reads, and that every name in it is one a path or an argument may carry.

type Model

type Model struct {
	Provider string `json:"provider"`
	// ProviderID is the saved model's provider: the vendor's name, or
	// custom-<slug> for one of several endpoints of the person's own.
	ProviderID string `json:"providerId,omitempty"`
	Name       string `json:"name"`
	APIKeyEnv  string `json:"apiKeyEnv"`
	APIKeyKind string `json:"apiKeyKind,omitempty"`
	BaseURL    string `json:"baseUrl,omitempty"`
	// ContextWindow is the policy's model.contextWindow: the harness sizes a
	// model of the operator's own endpoint from it.
	ContextWindow int64    `json:"contextWindow,omitempty"`
	ProxyAllow    []string `json:"proxyAllow"`
	// SavedModelID and SavedModelName are the saved model the run is on, as
	// the receipt names it; empty for a model with no saved model.
	SavedModelID   string `json:"savedModelId,omitempty"`
	SavedModelName string `json:"savedModelName,omitempty"`
}

Model is the model a run uses: the device policy's, less where its key comes from, which on the runhost is always the run's environment.

func ModelOf

func ModelOf(m policy.Model) Model

ModelOf is the job's model for the device policy's m.

func ModelOfSaved added in v0.7.39

func ModelOfSaved(view policy.Model, sm policy.SavedModel) Model

ModelOfSaved is the job's model for the saved model sm, which reads as view (policy.Policy.ForRun).

func (Model) PaysWithCredits added in v0.7.3

func (m Model) PaysWithCredits() bool

PaysWithCredits says whether the model is paid with Agentry credits: the runhost opens its credits session with the token in its store, and the job carries no key.

func (Model) Policy

func (m Model) Policy() policy.Model

Policy is the model as the runhost's policy takes it: the key from the run's environment, or none for a model paid with Agentry credits, with a plan's sign-in the runhost keeps, or at an endpoint that takes no key.

func (Model) Saved added in v0.7.39

func (m Model) Saved() (id string, pr policy.Provider, sm policy.SavedModel, ok bool)

Saved is the model as a policy's saved model and its provider: the provider's id, the provider as the runhost's policy takes it, and the saved model. ok is false for a model with no saved model.

func (Model) SignIn added in v0.7.6

func (m Model) SignIn() bool

SignIn says whether the model is paid by a plan's sign-in (a Claude subscription, a ChatGPT plan, a Copilot plan), which the runhost keeps itself: the job carries no key.

func (Model) TakesNoKey added in v0.7.39

func (m Model) TakesNoKey() bool

TakesNoKey says whether the model is an endpoint of the person's own that takes no key: the job carries none, and the run resolves none.

type Payload added in v0.6.1019

type Payload struct {
	Size   int64  `json:"size"`
	Digest string `json:"digest"`
}

Payload names the tar of the run's files: its length and its digest.

type Release

type Release struct {
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
	Version   string `json:"version"`
	// Digest is the archive's sha256:… digest.
	Digest string `json:"digest"`
	// Size is the archive's length in bytes.
	Size int64 `json:"size"`
	// Registry is the registry the release came from.
	Registry string `json:"registry"`
	// State is the device's verdict: verified, unsigned or unscanned.
	State string `json:"state"`
	// Attestation is the registry's DSSE envelope for the release, as the
	// device fetched it, for a verified release; empty otherwise.
	Attestation json.RawMessage `json:"attestation,omitempty"`
	// Keys are the signing keys the device holds pinned for Registry. The
	// runhost pins them the first time a release from that registry
	// arrives, and verifies every later one against its own pins.
	Keys trust.KeySet `json:"keys"`
}

Release is the release to run, as the device resolved and verified it.

func (Release) Ref

func (r Release) Ref() string

Ref is the release's exact reference, ns/name@version.

type Run

type Run struct {
	// Task is the run's task text; empty sends the agent its own
	// instruction.
	Task string `json:"task,omitempty"`
	// AllowUnsigned and AllowUnscanned are the person's own flags for this
	// run.
	AllowUnsigned  bool `json:"allowUnsigned,omitempty"`
	AllowUnscanned bool `json:"allowUnscanned,omitempty"`
	// Adapter is the harness adapter the run takes, one of ImageAdapters;
	// empty is the policy's default. A runhost runs no host-process harness,
	// which would run outside gVisor: the device sends Claude Code's and
	// Codex's image adapters for them (RunhostAdapter).
	Adapter string `json:"adapter,omitempty"`
	// Timeout, MaxTurns and MaxCost are the person's overrides of the
	// policy's budgets; a negative MaxTurns or MaxCost and a zero Timeout
	// leave the policy's.
	Timeout  int     `json:"timeout,omitempty"`
	MaxTurns int     `json:"maxTurns"`
	MaxCost  float64 `json:"maxCost"`
	// Model is the device policy's model, which the run uses in place of
	// the runhost's: the saved model the run is on. Empty when RunhostModel
	// names one of the runhost's own.
	Model Model `json:"model"`
	// ModelKey is the model's key, read from the device's environment or
	// keychain. It lives in the service's memory and the run's environment
	// only, and never in a file.
	ModelKey string `json:"modelKey,omitempty"`
	// RunhostModel names a saved model the runhost itself holds, by its id,
	// or RunhostDefault for the runhost's default at the time the run
	// starts: the runhost reads the model and its credential from its own
	// list, so the job carries neither (Model and ModelKey are empty). A
	// schedule kept on the runhost names its model this way.
	RunhostModel string `json:"runhostModel,omitempty"`

	// Secrets are the values of the release's declared secrets and its
	// servers', by name, resolved on the device as a local run resolves them
	// (its MCP profile, the intake's secret answers, then the policy's secret
	// source). On the runhost they are written to the job's own secrets file,
	// which is the run's secret source and is deleted when the run ends.
	Secrets map[string]string `json:"secrets,omitempty"`
	// Intake are the intake's answers as --intake takes them, by question
	// id. A file answer names its file in the payload (IntakeFiles) instead.
	Intake      map[string]string `json:"intake,omitempty"`
	IntakeFiles map[string]string `json:"intakeFiles,omitempty"`
	// SourceTokens are the access tokens of the run's input sources, by
	// question id, resolved on the device; on the runhost each reaches the
	// run's environment alone.
	SourceTokens map[string]string `json:"sourceTokens,omitempty"`
	// Inputs, Knowledge, Voice and ReportDesign name the payload's members:
	// each input a --file, each pack a --knowledge, the Writing Voice and
	// the report design. ReportTheme is a built-in theme's name.
	Inputs       []string `json:"inputs,omitempty"`
	Knowledge    []string `json:"knowledge,omitempty"`
	Voice        string   `json:"voice,omitempty"`
	ReportDesign string   `json:"reportDesign,omitempty"`
	ReportTheme  string   `json:"reportTheme,omitempty"`
	// Connections are the access tokens of the release's servers that sign
	// in by OAuth, refreshed on the device; never a refresh token.
	Connections map[string]Connection `json:"connections,omitempty"`
	// Destinations are where the run sends its result once it succeeds,
	// with their credentials, delivered from the runhost.
	Destinations []Destination `json:"destinations,omitempty"`
	// TargetHosts are the release's target hosts, by id, each answered in
	// Intake: the sign-in the device resolved and the known_hosts lines of
	// the keys it has accepted for the host. The runhost resolves the
	// address and checks the key it is offered against those lines alone.
	TargetHosts map[string]TargetHost `json:"targetHosts,omitempty"`
	// HostsAllow and HostsDeny are the device policy's networks a target
	// host's address may and may never be in, which the runhost holds the
	// address it resolves to.
	HostsAllow []string `json:"hostsAllow,omitempty"`
	HostsDeny  []string `json:"hostsDeny,omitempty"`
	// AllowVulnerableMCP is the person's own --allow-vulnerable-mcp.
	AllowVulnerableMCP bool `json:"allowVulnerableMcp,omitempty"`
	// Session makes the job an interactive session, driven over the job's
	// own input by the session protocol's commands, its events coming back
	// as frames.
	Session bool `json:"session,omitempty"`
	// Payload is the tar of the run's files that follows the document (and
	// the release, when the runhost asks for it); nil when there are none.
	Payload *Payload `json:"payload,omitempty"`
	// Desktop is the device's binding to its Agentry Desktop, for a release
	// that declares applications on the person's computer: the device bound
	// the run before it sent the job, and the runhost's run reaches the
	// device's link service through the link session the device keeps open
	// for the job. nil for a release that declares none.
	Desktop *Desktop `json:"desktop,omitempty"`
	// AllowScreen is the person's own --allow-screen.
	AllowScreen bool `json:"allowScreen,omitempty"`
	// Managed is what the sending device's managed settings say of the run:
	// the runhost has its own sign-in, so the organization's locks on the
	// person's device travel with the job, and the runhost applies them
	// beside its own. They can only refuse. Nil when the device holds none.
	Managed *managed.Narrowing `json:"managed,omitempty"`
}

Run is what the device decided about the run.

func (*Run) ValidateCarriedModel added in v0.7.39

func (r *Run) ValidateCarriedModel() error

ValidateCarriedModel checks the model and key a runhost put in place of the runhost model a job named, as it checks a job's own.

type TargetHost added in v0.6.1019

type TargetHost struct {
	// Known are known_hosts lines naming the host, as the device keeps them.
	Known []string `json:"known"`
	// Key is a private key's file, PEM, when the sign-in is a key; Password
	// otherwise. Passphrase opens the key; Sudo is the account's sudo
	// password.
	Key        string `json:"key,omitempty"`
	Passphrase string `json:"passphrase,omitempty"`
	Password   string `json:"password,omitempty"`
	Sudo       string `json:"sudo,omitempty"`
}

TargetHost is one target host's sign-in and the host keys the device has accepted for it.

Jump to

Keyboard shortcuts

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