job

package
v0.7.6-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 11 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 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 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 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 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"`
	Name       string   `json:"name"`
	APIKeyEnv  string   `json:"apiKeyEnv"`
	APIKeyKind string   `json:"apiKeyKind,omitempty"`
	BaseURL    string   `json:"baseUrl,omitempty"`
	ProxyAllow []string `json:"proxyAllow"`
}

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 (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 or with a plan's sign-in the runhost keeps.

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.

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.
	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"`

	// 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"`
}

Run is what the device decided about the run.

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