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 ValidRunhostModel(ref string) bool
- func Write(w io.Writer, j *Job) error
- type Connection
- type Desktop
- 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 MaxDesktopToken = 512
MaxDesktopToken bounds the run token a binding carries.
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 RunhostDefault = "default"
RunhostDefault is RunhostModel's word for the runhost's default saved model, whichever it is when the run starts.
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.
func ValidRunhostModel ¶ added in v0.7.39
ValidRunhostModel says whether ref can name a saved model of the runhost's: a saved model's id, or RunhostDefault.
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
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.
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 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
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 ¶
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
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
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
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
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: 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
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.