Documentation
¶
Index ¶
- Constants
- Variables
- 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 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 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 Reattach(ctx context.Context, rec *runhost.Record, keys *runhost.DeviceKeys, id string, ...) (runhost.JobResult, *runhost.Client, 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 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 VersionSkew(name, server, device string) error
- type Credits
- type CreditsInfo
- type CreditsRemoved
- type Ended
- type FinishOptions
- 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 CreditsScope = "credits:session"
CreditsScope is the one scope a runhost's credits token carries.
const JobsFile = "runhost-jobs.json"
Variables ¶
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 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 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 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 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 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 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 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 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 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.
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"`
}
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.