remote

package
v0.7.27-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source
const (
	AgentStdout = "stdout"
	AgentStderr = "stderr"
	AgentEvents = "events"
)

The agent verb's data frames' streams.

View Source
const CreditsScope = "credits:session"

CreditsScope is the one scope a runhost's credits token carries.

View Source
const JobsFile = "runhost-jobs.json"
View Source
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

View Source
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.

View Source
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.

View Source
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

func AgentSocketKey(name string) (string, bool)

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

func CheckAgentArgs(sub string, args []string) error

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

func Deliver(env *receipt.Envelope, outDir, deliverTo string) string

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 DropJob

func DropJob(home, id string)

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

func Envelope(env *receipt.Envelope, rec *runhost.Record, outDir, jobID string)

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

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 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

func ModelKey(pol *policy.Policy) (string, error)

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 NewJobID

func NewJobID() (string, error)

NewJobID is a fresh job id.

func ParseExactRef

func ParseExactRef(ref string) ([3]string, error)

ParseExactRef splits ns/name@version.

func PutCredits

func PutCredits(ctx context.Context, c *runhost.Client, doc Credits, say func(string)) error

PutCredits sends the credits token to the runhost's store over the run key; say takes the runhost's narration.

func PutJob

func PutJob(home string, j LocalJob) error

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

func RevokeCredits(ctx context.Context, hc *http.Client, c Credits) error

RevokeCredits has the token revoke itself at its registry. A token the registry no longer takes (revoked or expired) is already gone.

func RevokeUnsent

func RevokeUnsent(ctx context.Context, hc *http.Client, reg string, pat authflow.PAT) error

RevokeUnsent revokes a token that never reached the runhost, and says so if it cannot.

func RunSchedule added in v0.7.11

func RunSchedule(ctx context.Context, c *runhost.Client, id string) (runhost.ScheduleFire, error)

RunSchedule runs an occurrence of schedule id now; its job is collected as any other.

func Schedules added in v0.7.11

func Schedules(ctx context.Context, c *runhost.Client) ([]runhost.ScheduleInfo, error)

Schedules lists the runhost's schedules.

func SendClass

func SendClass(err error) int

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

func TakesSchedules(ctx context.Context, c *runhost.Client) (bool, error)

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

func VersionSkew(name, server, device string) error

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

type AgentIO struct {
	Stdin          io.Reader
	Value          string
	Stdout, Stderr io.Writer
	Events         io.Writer
}

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.

func (Credits) Info

func (c Credits) Info() *CreditsInfo

Info is c without its token.

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

func RemoveCredits(ctx context.Context, c *runhost.Client) (CreditsRemoved, error)

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

func EndAll(ctx context.Context, c *runhost.Client, say func(string)) Ended

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

LocalJob is one job this device sent, until it is collected.

func FindJob

func FindJob(home, runhostName, id string) (LocalJob, bool)

func JobOf

func JobOf(home string, rec *runhost.Record, id string, ref string) LocalJob

jobOf is the local record of a job this device sent; a job sent from another device, or one whose record is gone, gets one from the runhost's own answer.

func LoadJobs

func LoadJobs(home string) ([]LocalJob, error)

type Refusal

type Refusal struct {
	Code   int
	Reason string
}

Refusal is a job the runhost answered without running it, with the exit class it gave.

func (*Refusal) Error

func (r *Refusal) Error() string

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

func (s *Session) AddInput(ctx context.Context, hostPath string) error

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

func (s *Session) End(ctx context.Context, finish bool) (*receipt.Envelope, error)

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.

func (*Session) Ended

func (s *Session) Ended() (bool, session.EndReason)

func (*Session) Events

func (s *Session) Events() <-chan session.Event

func (*Session) Frame

func (s *Session) Frame(f runhost.Frame)

Frame takes one event frame from the runhost.

func (*Session) Input

func (s *Session) Input(w io.Writer) error

Input writes the session's commands to the job's input until End.

func (*Session) Over

func (s *Session) Over(res runhost.JobResult, err error, next int)

Over marks the call ended: the job's result, or the connection lost.

func (*Session) Send

func (s *Session) Send(ctx context.Context, text string) error

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.

func (*SkewError) Error added in v0.7.10

func (e *SkewError) Error() string

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.

func ListStore

func ListStore(ctx context.Context, c *runhost.Client) (StoreList, error)

ListStore asks the runhost what its store keeps.

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

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.

type Version

type Version struct {
	Version string `json:"version"`
	// Arch is the runhost's architecture in Go's words.
	Arch string `json:"arch,omitempty"`
	// UnsafeMode is the runhost's own Unsafe Mode setting.
	UnsafeMode bool `json:"unsafeMode"`
}

Version is the version verb's answer.

func SameVersion

func SameVersion(ctx context.Context, c *runhost.Client, name string) (Version, error)

SameVersion refuses a runhost whose CLI is not this device's version: the run's plan, policy and envelope are this version's. It returns what the runhost said of itself.

Jump to

Keyboard shortcuts

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