Documentation
¶
Index ¶
- Constants
- Variables
- func AgentCommand(ctx context.Context, c Caller, sub string, args []string, o AgentIO) (int, string, error)
- func AgentSocketKey(name string) (string, bool)
- func CheckAgentArgs(sub string, args []string) error
- func CollectEnvelope(ctx context.Context, c *runhost.Client, jobID, device string, ...) ([]byte, error)
- func CollectOutput(ctx context.Context, c *runhost.Client, jobID, device string, ...) error
- func Deliver(env *receipt.Envelope, outDir, deliverTo string) string
- func DropJob(home, id string)
- func Entries(j *job.Job) []runhost.ScheduleEntry
- func Envelope(env *receipt.Envelope, rec *runhost.Record, outDir, jobID string)
- func Finish(ctx context.Context, c *runhost.Client, rec *runhost.Record, ...) (*receipt.Envelope, error)
- func Follow(ctx context.Context, c *runhost.Client, id string, from int, say func(string), ...) (runhost.JobResult, int, error)
- func KeepLink(ctx context.Context, dial LinkDialer, id string, forward LinkForward, ...) error
- func MintCredits(ctx context.Context, reg, name string, open func(url string), wait func()) (authflow.PAT, error)
- func ModelKey(pol *policy.Policy) (string, error)
- func NewJobID() (string, error)
- func ParseExactRef(ref string) ([3]string, error)
- func PutCredits(ctx context.Context, c *runhost.Client, doc Credits, say func(string)) error
- func PutJob(home string, j LocalJob) error
- func PutSchedule(ctx context.Context, c *runhost.Client, h runhost.ScheduleHeader, j *job.Job, ...) (runhost.ScheduleInfo, error)
- func Reattach(ctx context.Context, rec *runhost.Record, keys *runhost.DeviceKeys, id string, ...) (runhost.JobResult, *runhost.Client, error)
- func RelayAgentSocket(ctx context.Context, c Caller, name string) (home, key string, stop func(), err error)
- func RemoveSchedule(ctx context.Context, c *runhost.Client, id string) (runhost.ScheduleInfo, error)
- func RemoveSignIn(ctx context.Context, c *runhost.Client, vendor string, say func(string)) (signin.Removed, error)
- func RevokeCredits(ctx context.Context, hc *http.Client, c Credits) error
- func RevokeUnsent(ctx context.Context, hc *http.Client, reg string, pat authflow.PAT) error
- func RunSchedule(ctx context.Context, c *runhost.Client, id string) (runhost.ScheduleFire, error)
- func Schedules(ctx context.Context, c *runhost.Client) ([]runhost.ScheduleInfo, error)
- func SendClass(err error) int
- func Start(ctx context.Context, c *runhost.Client, j *job.Job, archive []byte, ...) (res runhost.JobResult, started bool, next int, err error)
- func TakesSchedules(ctx context.Context, c *runhost.Client) (bool, error)
- func VersionSkew(name, server, device string) error
- type AgentIO
- type Caller
- type Credits
- type CreditsInfo
- type CreditsRemoved
- type Ended
- type FinishOptions
- type LinkDialer
- type LinkForward
- type LocalJob
- type Refusal
- type Session
- func (s *Session) AddInput(ctx context.Context, hostPath string) error
- func (s *Session) End(ctx context.Context, finish bool) (*receipt.Envelope, error)
- func (s *Session) Ended() (bool, session.EndReason)
- func (s *Session) Events() <-chan session.Event
- func (s *Session) Frame(f runhost.Frame)
- func (s *Session) Input(w io.Writer) error
- func (s *Session) Over(res runhost.JobResult, err error, next int)
- func (s *Session) Send(ctx context.Context, text string) error
- type SkewError
- type StoreList
- type Unpaired
- type UpdateOptions
- type UpdateOutcome
- type Version
Constants ¶
const ( AgentStdout = "stdout" AgentStderr = "stderr" AgentEvents = "events" )
The agent verb's data frames' streams.
const CreditsScope = "credits:session"
CreditsScope is the one scope a runhost's credits token carries.
const DesktopUnreachableMessage = "" /* 128-byte string literal not displayed */
DesktopUnreachableMessage is what the run is told when this computer's Agentry Desktop does not answer a call the runhost relayed.
const JobsFile = "runhost-jobs.json"
const MessengerUserFlag = "user"
MessengerUserFlag is messenger add's Matrix user, whose password signs in on the device: the runhost is sent the session's access token, never the password, so the flag never reaches it.
Variables ¶
var ( LinkStartWait = 15 * time.Minute LinkRetry = time.Second )
LinkStartWait bounds how long the device waits for the runhost to run the job before its first link session opens (the release and the run's files may be uploading meanwhile), and LinkRetry how often it asks.
var AgentCommands = []string{"list", "show", "start", "stop", "attach", "enable", "disable", "reset", "grant", "configure", "tasks", "secret", "messenger"}
AgentCommands are the agent subcommands a device runs on a runhost.
var AgentRefusedFlags = []string{
"policy", "personality-file", "share", "knowledge", "subagent",
"calendar-sign-in", "google-client", "google-sign-in",
"dev-host", "dev-key", "dev-passphrase", "dev-password",
}
AgentRefusedFlags name a file, a sign-in or a credential on the device, which the runhost's CLI would look for on the server instead. A sign-in whose browser answer is a callback in a container on the runhost (Google Workspace's, a calendar's) is refused too: nothing relays it yet.
var ReattachWaits = []time.Duration{2 * time.Second, 10 * time.Second, 30 * time.Second}
ReattachWaits are how long the device waits before each attempt to reach a runhost again after losing it mid-job.
Functions ¶
func AgentCommand ¶ added in v0.7.14
func AgentCommand(ctx context.Context, c Caller, sub string, args []string, o AgentIO) (int, string, error)
AgentCommand runs `agentry agent sub args…` on the runhost c reaches and answers with its exit code and what it wrote to stderr (at most 64 KiB).
func AgentSocketKey ¶ added in v0.7.14
AgentSocketKey is the name the runner home keys the agent name or ref names by: a built-in's name, or an installed agent's ns.name.
func CheckAgentArgs ¶ added in v0.7.14
CheckAgentArgs refuses a subcommand the runhost does not run and a flag that names something on the device.
func CollectEnvelope ¶
func CollectEnvelope(ctx context.Context, c *runhost.Client, jobID, device string, keys *runhost.DeviceKeys) ([]byte, error)
CollectEnvelope fetches a finished job's sealed envelope and opens it with this device's sealing key.
func CollectOutput ¶
func CollectOutput(ctx context.Context, c *runhost.Client, jobID, device string, keys *runhost.DeviceKeys, outDir string) error
runOnCollect fetches the job's sealed output and opens it with this device's sealing key into outDir. An output that does not open, or holds anything a run's output does not, leaves nothing in outDir.
func Deliver ¶
Deliver copies a successful run's deliverables to the folder the device delivers to, as a local run does at its end, recording each copy in the envelope and the deliveries ledger. It answers a warning when the ledger could not be written.
func Entries ¶ added in v0.7.11
func Entries(j *job.Job) []runhost.ScheduleEntry
Entries are what a schedule of j keeps in the runhost's store, besides the release.
func Envelope ¶
Envelope takes the runhost CLI's envelope as this device's record: its folders are this device's, and it names the runhost it ran on.
func Finish ¶
func Finish(ctx context.Context, c *runhost.Client, rec *runhost.Record, keys *runhost.DeviceKeys, lj LocalJob, code int, o FinishOptions) (*receipt.Envelope, error)
Finish collects a finished job: its sealed envelope and its sealed output, opened into the output folder; the envelope the runhost's CLI printed is this device's record, with the runhost it ran on; the deliverables are copied to the device's deliver folder; the runhost is told to delete the job, and the device forgets it. A run that failed answers its envelope and its class.
func Follow ¶
func Follow(ctx context.Context, c *runhost.Client, id string, from int, say func(string), each func(runhost.Frame)) (runhost.JobResult, int, error)
Follow attaches to a job from frame index from and follows it to its end.
func KeepLink ¶ added in v0.7.33
func KeepLink(ctx context.Context, dial LinkDialer, id string, forward LinkForward, linked func()) error
KeepLink keeps job id's link session open while the job runs, answering each message with forward. It returns nil once the job has ended (or never ran with a desktop link), and the runhost's refusal when it refuses this device the link. A lost connection is reached again after ReattachWaits; once they are spent, KeepLink gives up and the job's later calls are refused desktop-unreachable there. linked, when set, is told each time a session opens.
func MintCredits ¶
func MintCredits(ctx context.Context, reg, name string, open func(url string), wait func()) (authflow.PAT, error)
MintCredits has the person approve a runhost's credits token in their browser, through the registry's authorize page for runhost name, and holds what comes back to a token that carries the credits scope alone, with an id the runhost can revoke it by. open is handed the page to open; wait says the device waits for the browser.
func ModelKey ¶
ModelKey is the device policy's model key, which the run carries in flight: the variable the policy names, else its keychain entry. A model paid with Agentry credits or a plan's sign-in carries none: the runhost pays with the credits token, or the sign-in, it keeps (agentry runhost model). A model a runhost cannot be handed this way is refused here.
func ParseExactRef ¶
ParseExactRef splits ns/name@version.
func PutCredits ¶
PutCredits sends the credits token to the runhost's store over the run key; say takes the runhost's narration.
func PutSchedule ¶ added in v0.7.11
func PutSchedule(ctx context.Context, c *runhost.Client, h runhost.ScheduleHeader, j *job.Job, archive []byte, files *payload.Packed, say func(string)) (runhost.ScheduleInfo, error)
PutSchedule sends the schedule h with its job, its release when the runhost asks for it, and its files. say takes the runhost's narration.
func Reattach ¶
func Reattach(ctx context.Context, rec *runhost.Record, keys *runhost.DeviceKeys, id string, from int, errOut io.Writer, say func(string), each func(runhost.Frame)) (runhost.JobResult, *runhost.Client, error)
Reattach reaches the runhost again after the connection was lost while the job ran, and follows the job from where the device lost it. It answers the client it reached the runhost with.
func RelayAgentSocket ¶ added in v0.7.14
func RelayAgentSocket(ctx context.Context, c Caller, name string) (home, key string, stop func(), err error)
RelayAgentSocket listens on an owner socket of this device's own, in a runner home made for it, and relays each connection to the owner socket of the agent name on the runhost c reaches. persistent's socket calls (Attach, QueryStatus, RequestStop) are given the home and the key; stop closes the listener and removes the home.
func RemoveSchedule ¶ added in v0.7.11
func RemoveSchedule(ctx context.Context, c *runhost.Client, id string) (runhost.ScheduleInfo, error)
RemoveSchedule takes schedule id off the runhost, with what it kept.
func RemoveSignIn ¶
func RemoveSignIn(ctx context.Context, c *runhost.Client, vendor string, say func(string)) (signin.Removed, error)
RemoveSignIn has the runhost end its sign-in to vendor and remove it; say takes the runhost's narration.
func RevokeCredits ¶
RevokeCredits has the token revoke itself at its registry. A token the registry no longer takes (revoked or expired) is already gone.
func RevokeUnsent ¶
RevokeUnsent revokes a token that never reached the runhost, and says so if it cannot.
func RunSchedule ¶ added in v0.7.11
RunSchedule runs an occurrence of schedule id now; its job is collected as any other.
func SendClass ¶
SendClass is the exit class of a job that did not run: a refusal the runhost classed as usage, verify or policy keeps that class, and anything else, a transport failure among them, is the gateway's.
func Start ¶
func Start(ctx context.Context, c *runhost.Client, j *job.Job, archive []byte, files *payload.Packed, detach bool, say func(string), each func(runhost.Frame), moreInput func(io.Writer) error) (res runhost.JobResult, started bool, next int, err error)
Start sends the job, and its release and files when the runhost asks for them, over one session, and follows the job's frames. started says whether the runhost said it runs the job: an error after that is a connection lost while the job runs on, which next and attach resume. With detach, it returns as soon as the job runs. each, when set, takes the frames a session's driver reads (events), and moreInput, when set, writes the session's commands after the files.
func TakesSchedules ¶ added in v0.7.11
TakesSchedules says whether the runhost takes schedules (its store's key sealed by its systemd), as its status says, and why not.
func VersionSkew ¶ added in v0.7.10
VersionSkew is the refusal of a run on runhost name, whose CLI is server, from a device whose CLI is device: both versions, and what brings them together. A runhost follows the newest of its devices, so an older device is the one to update.
Types ¶
type AgentIO ¶ added in v0.7.14
AgentIO is where an agent command's streams go, and what it reads: Stdin is attach's input (nil for none), Value one line sent on stdin to the commands that keep a value (secret and configure), and Events attach's events (nil drops them).
type Caller ¶ added in v0.7.14
type Caller interface {
Call(ctx context.Context, verb string, args []string, send func(io.Writer) error, each func(runhost.Frame) error) (runhost.Answer, error)
}
Caller is the runhost connection the agent calls go over: a *runhost.Client.
type Credits ¶
type Credits struct {
Registry string `json:"registry"`
TokenID string `json:"tokenId"`
Name string `json:"name"`
Token string `json:"token"`
Device string `json:"device"`
StoredAt string `json:"storedAt,omitempty"`
}
Credits is the credits token as the runhost's store keeps it.
type CreditsInfo ¶
type CreditsInfo struct {
Registry string `json:"registry"`
TokenID string `json:"tokenId"`
Name string `json:"name"`
Device string `json:"device"`
StoredAt string `json:"storedAt"`
}
CreditsInfo is what the runhost says of its credits token: never the token.
type CreditsRemoved ¶
type CreditsRemoved struct {
Removed bool `json:"removed"`
Revoked bool `json:"revoked"`
Credits *CreditsInfo `json:"credits,omitempty"`
// RevokeError says why the registry did not revoke the token, which
// the person then revokes there.
RevokeError string `json:"revokeError,omitempty"`
}
CreditsRemoved is what removing the credits token did.
func RemoveCredits ¶
RemoveCredits has the runhost revoke its credits token and remove it from its store.
type Ended ¶
type Ended struct {
Credits CreditsRemoved
SignIns []signin.Removed
// Failed names what could not be ended, by "credits" or the vendor.
Failed map[string]error
}
Ended is what EndAll ended on a runhost before its removal.
func EndAll ¶
EndAll ends what the runhost holds of the person's before it is removed, over the run key: its credits token revokes itself, and each model sign-in ends at its vendor (Claude Code's own logout and its volume deleted, which the Docker daemon would otherwise keep after the account goes).
type FinishOptions ¶
type FinishOptions struct {
// Home is the runner home whose job records hold the job.
Home string
// OutDir is the output folder for the run id the envelope names: the
// folder the job was sent with, or the client's default.
OutDir func(runID string) (string, error)
// Warn tells the person something that did not stop the collection.
Warn func(string)
// CollectHint names how the person collects the job later, for an
// error that leaves it on the runhost.
CollectHint string
}
FinishOptions are the device's choices in collecting a finished job.
type LinkDialer ¶ added in v0.7.33
LinkDialer reaches the runhost for a link session: the client, and what to do with it once the session ends.
func LinkDialerFrom ¶ added in v0.7.33
func LinkDialerFrom(c *runhost.Client, rec *runhost.Record, keys *runhost.DeviceKeys) LinkDialer
LinkDialerFrom reaches the runhost for a link session: through c first, which the caller keeps, then over a connection of its own for each later session.
type LinkForward ¶ added in v0.7.33
LinkForward answers one message a job's desktop link carries from the runhost: a tool call or the run's unbind. It never fails: what it cannot answer, it refuses.
func BindingForward ¶ added in v0.7.33
func BindingForward(link *engine.DesktopLink, run string) LinkForward
BindingForward forwards the bound run's tool calls and its unbind to a binding this process holds (Agentry Desktop's own, bound in process), and refuses anything else without sending it.
func SocketForward ¶ added in v0.7.33
func SocketForward(socket, run string) LinkForward
SocketForward forwards the bound run's tool calls and its unbind to the link service on socket, and refuses anything else without sending it.
type LocalJob ¶
type LocalJob struct {
Job string `json:"job"`
Runhost string `json:"runhost"`
Ref string `json:"ref"`
Namespace string `json:"namespace"`
Name string `json:"name"`
Version string `json:"version"`
Digest string `json:"digest"`
// Out is the output folder the run was given, empty for the default.
Out string `json:"out,omitempty"`
// DeliverTo is the folder the device copies the deliverables to.
DeliverTo string `json:"deliverTo,omitempty"`
Session bool `json:"session,omitempty"`
StartedAt string `json:"startedAt"`
// Adapter is the adapter the job named, and AdapterAsked the one the
// person asked for when the runhost runs another in its place.
Adapter string `json:"adapter,omitempty"`
AdapterAsked string `json:"adapterAsked,omitempty"`
// UnsafeMode is whether the runhost's Unsafe Mode setting was on when
// the job was sent.
UnsafeMode bool `json:"unsafeMode,omitempty"`
// Desktop is the run this device bound on its Agentry Desktop for the
// job, whose desktop link a later attach opens again; empty for a job
// that uses no application on this computer.
Desktop string `json:"desktop,omitempty"`
}
LocalJob is one job this device sent, until it is collected.
type Refusal ¶
Refusal is a job the runhost answered without running it, with the exit class it gave.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is a session.Session whose session runs on a runhost: its commands go over the job's input and its events come back as frames.
func NewSession ¶
func NewSession(finish func(ctx context.Context, res runhost.JobResult, err error, next int) (*receipt.Envelope, error)) *Session
NewSession is a session that runs on a runhost: drive Start with its Frame and Input, hand its outcome to Over, and End calls finish to collect it.
func (*Session) AddInput ¶
AddInput sends a regular file of this device's to the session's inputs folder on the runhost, then has the session add it.
func (*Session) End ¶
End ends the session (with finish, asking for its final result), waits for the job to end on the runhost, and collects its output and envelope.
type SkewError ¶ added in v0.7.10
type SkewError struct {
// contains filtered or unexported fields
}
SkewError is a refusal for a version skew between a runhost and this device, which only an update ends.
type StoreList ¶
type StoreList struct {
Releases int `json:"releases"`
Credits *CreditsInfo `json:"credits,omitempty"`
// SignIns are the model sign-ins the runhost keeps.
SignIns []signin.Kept `json:"signIns,omitempty"`
// Schedules are the runhost's schedules, each with what it keeps.
Schedules []runhost.ScheduleInfo `json:"schedules,omitempty"`
// Sealed says whether the store's key is sealed by systemd.
Sealed bool `json:"sealed"`
}
StoreList is the store verb's list: never a credential.
type Unpaired ¶ added in v0.7.10
type Unpaired struct {
Device string `json:"device"`
Credits CreditsRemoved `json:"credits"`
}
Unpaired is the unpair verb's answer: the device that left, and the credits token it had minted, revoked and removed with it.
func Unpair ¶ added in v0.7.10
func Unpair(ctx context.Context, rec runhost.Record, keys *runhost.DeviceKeys, say func(string)) (Unpaired, error)
Unpair takes this device off the runhost of rec: the runhost drops its run key and sealing key, and revokes the credits token this device minted. The caller then drops the device's keys and record.
type UpdateOptions ¶ added in v0.7.10
type UpdateOptions struct {
// Version is this device's CLI version; empty is this build's.
Version string
// Keys are the update-signing keys a release is checked against.
Keys *clirelease.KeySet
// HTTP downloads the release and gVisor.
HTTP *http.Client
// FetchCLI and FetchGVisor default to those downloads, each checked;
// tests replace them.
FetchCLI func(ctx context.Context, version, arch string) (*clirelease.Binary, error)
FetchGVisor func(ctx context.Context, arch string) ([]byte, error)
// Say narrates the runhost's side, one line at a time.
Say func(string)
// Restart bounds the wait for the service to restart into its new CLI;
// zero is a minute.
Restart time.Duration
}
UpdateOptions are what Update needs.
type UpdateOutcome ¶ added in v0.7.10
type UpdateOutcome struct {
Name string `json:"name"`
// From and To are the runhost's CLI before and after.
From string `json:"from"`
To string `json:"to"`
// Updated is true when the runhost took a new CLI.
Updated bool `json:"updated"`
// WaitsForJobs is how many running jobs the runhost finishes before it
// restarts into the new CLI; To is its version already.
WaitsForJobs int `json:"waitsForJobs,omitempty"`
// GVisor is the runhost's gVisor release after, and GVisorUpdated true
// when it changed.
GVisor string `json:"gvisor,omitempty"`
GVisorUpdated bool `json:"gvisorUpdated,omitempty"`
// DeviceBehind is the runhost's CLI when it is newer than this
// device's: update this device before running there.
DeviceBehind string `json:"deviceBehind,omitempty"`
// NeedsAttention says what only the admin sign-in can change.
NeedsAttention []string `json:"needsAttention,omitempty"`
}
UpdateOutcome is what Update did to one runhost.
func Update ¶ added in v0.7.10
func Update(ctx context.Context, rec *runhost.Record, keys *runhost.DeviceKeys, o UpdateOptions) (UpdateOutcome, error)
Update brings the runhost of rec to this device's CLI version and its gVisor release, then has its doctor check it. It updates rec's versions; the caller saves the records.