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
- Variables
- func RunhostAdapter(asked string) (name string, mapped bool, err error)
- func SecretValueOK(v string) bool
- func ValidID(id string) bool
- func ValidKeyEnv(name string) bool
- func Write(w io.Writer, j *Job) error
- type Connection
- type Destination
- type Job
- type Model
- type Payload
- type Release
- type Run
- type TargetHost
Constants ¶
const ( StateVerified = "verified" StateUnsigned = "unsigned" StateUnscanned = "unscanned" )
Attestation states a release may arrive in, as the device judged it.
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.
const ( MaxSecret = 64 << 10 MaxSecrets = 256 )
MaxSecret bounds one secret's value, and MaxSecrets their number.
const MaxArchive = 512 << 20
MaxArchive bounds a release archive a job carries: the CLI's own cap on a downloaded archive.
const MaxDocument = 1 << 20
MaxDocument bounds a job document on the wire.
const MaxKnownLines = 32
MaxKnownLines bounds the known_hosts lines one target host carries.
const Version = 1
Version is the job document's version.
Variables ¶
var ImageAdapters = []string{AdapterDockerAgent, AdapterClaudeImage, AdapterCodexImage, AdapterCopilot}
ImageAdapters are the adapters a runhost runs.
Functions ¶
func RunhostAdapter ¶ added in v0.7.6
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
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 ValidKeyEnv ¶
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.
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.
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 (Model) PaysWithCredits ¶ added in v0.7.3
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.
type Payload ¶ added in v0.6.1019
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.
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.