Documentation
¶
Overview ¶
Package desktop is how a run reaches Agentry Desktop's link service, the far end of the desktop link: the socket Agentry Desktop serves in the runner home while it runs, and the three messages on it. Before the sandbox starts the run binds, naming its release, its desktop line and the application servers it uses; the link service checks each installed server is present and its application reachable, and answers with a run token and each server's tools. While the run lives, each tool call the desktop link carries out of the sandbox is sent as a call with that token, and the link service answers it or refuses it by its reason. At teardown the run unbinds. One JSON line each way on a connection of its own, as the app link's socket takes a call.
A refusal's reason is one of the receipt's desktop-refused details (receipt.DesktopUnavailable and the others), so what the link service says is what the receipt records.
Index ¶
- Constants
- Variables
- func RelayedCallOnly(m Message, run string) bool
- func Serve(ctx context.Context, ln net.Listener, h Handler) error
- func SocketPath(home string) string
- type BindRequest
- type BindServer
- type Bound
- type CallRequest
- type Client
- func (c Client) Bind(ctx context.Context, req BindRequest) (Bound, error)
- func (c Client) Call(ctx context.Context, req CallRequest) (desktoplink.Answer, error)
- func (c Client) Forward(ctx context.Context, m Message) (Message, error)
- func (c Client) Unbind(ctx context.Context, req UnbindRequest) error
- type ComputerBound
- type Handler
- type Message
- type Refusal
- type Relayed
- type UnbindRequest
Constants ¶
const MaxLine = desktoplink.MaxLine
MaxLine bounds a line either way.
const ReportsFolder = "reports/desktop"
ReportsFolder is the folder of a run's output, relative to it, where Agentry Desktop keeps the screenshots the person asked it to keep.
const SocketName = "desktop.sock"
SocketName is the link service's socket in the runner home's socket folder, beside the persistent agents' sockets.
Variables ¶
var BindTimeout = 2 * time.Minute
BindTimeout bounds a bind: the link service may start an installed server and list its tools to answer.
var ErrNoService = errors.New("no Agentry Desktop answers on this computer")
ErrNoService says nothing answers on the socket: Agentry Desktop is not running on this computer.
Functions ¶
func RelayedCallOnly ¶ added in v0.7.33
RelayedCallOnly says whether m is a message a relay carries for run: a tool call or the unbind of that run, and nothing else.
func Serve ¶
Serve answers messages on the listener with h, one connection at a time per message, until ctx is done or the listener closes. A line that is not one message is answered with a refusal and nothing reaches h.
func SocketPath ¶
SocketPath is the link service's socket for a runner home.
Types ¶
type BindRequest ¶
type BindRequest struct {
Run string `json:"run"`
Ref string `json:"ref"`
Digest string `json:"digest,omitempty"`
Servers []BindServer `json:"servers"`
// Agent names a persistent agent the binding is for, for the link
// service's dialogs; empty for a run.
Agent string `json:"agent,omitempty"`
// Lazy binds a persistent agent's segment: an application need not be
// running now, since whether it is is read at each call, which is
// refused desktop-not-installed, with the step to take, while it is
// not. The link service lists each server's tools as its installed
// server lists them when it can start it, else as the catalogue names
// them.
Lazy bool `json:"lazy,omitempty"`
// ComputerUse is "app" or "screen" where the release declares computer
// use, with the computer-use tools the run has: the link service binds
// it in that scope or refuses the bind.
ComputerUse string `json:"computerUse,omitempty"`
ComputerTools []string `json:"computerTools,omitempty"`
// Reports is the run's folder on this computer for what the person
// keeps of computer use: where "Keep what the agent saw" saves each
// screenshot. Empty where the run has no such folder.
Reports string `json:"reports,omitempty"`
}
BindRequest asks the link service to bind a run: the run's id, its release and the application servers the run uses, each with the tools the release allows it.
type BindServer ¶
type BindServer struct {
ID string `json:"id"`
Tools []string `json:"tools"`
// ExecAgreed says the person agreed that the server's tools that run
// code run without asking each time (a persistent agent's switch); a
// run's exec calls always ask.
ExecAgreed bool `json:"execAgreed,omitempty"`
}
BindServer is one application server a run uses: its catalogue id and the tools the release allows, in the catalogue's words.
type Bound ¶
type Bound struct {
Token string `json:"token"`
Servers map[string][]desktoplink.Tool `json:"servers"`
// Computer is the computer use the link service bound, where the run
// asked for it.
Computer *ComputerBound `json:"computer,omitempty"`
}
Bound is a bind's answer: the run token every call carries, and each bound server's tools as the installed server listed them.
type CallRequest ¶
type CallRequest struct {
Run string `json:"run"`
Token string `json:"token"`
Server string `json:"server"`
Tool string `json:"tool"`
Arguments json.RawMessage `json:"arguments,omitempty"`
}
CallRequest is one tool call for a bound server.
type Client ¶
type Client struct {
Socket string
}
Client speaks to a link service on its socket.
func (Client) Call ¶
func (c Client) Call(ctx context.Context, req CallRequest) (desktoplink.Answer, error)
Call sends one tool call. A refusal is returned as a *Refusal.
type ComputerBound ¶ added in v0.7.30
type ComputerBound struct {
// Scope is "app" or "screen", as bound.
Scope string `json:"scope"`
// Windows names what the agent may see and use: the applications whose
// windows app scope holds it to, or the display.
Windows []string `json:"windows,omitempty"`
// MaxEdge is the longest edge of a screenshot, in pixels: a larger
// window is scaled down to it and positions are of the scaled image.
MaxEdge int `json:"maxEdge,omitempty"`
// Enforced says, in the link service's words, which of the scope the
// computer's own system holds (the capture of one window, the input
// held to it) and which only Agentry Desktop's check before each input.
Enforced string `json:"enforced"`
// Session is the display the link service works on, for example
// "Linux, Wayland (KDE Plasma)".
Session string `json:"session,omitempty"`
// KeepScreenshots says the person's "Keep what the agent saw" is on:
// each screenshot is saved in the run's own folder on their computer.
KeepScreenshots bool `json:"keepScreenshots,omitempty"`
// StopKey is the key that stops the agent's use of the computer, as the
// person is told it.
StopKey string `json:"stopKey,omitempty"`
}
ComputerBound is what the link service bound of computer use, for the run's receipt: the scope it holds, the windows it holds it to, how large a screenshot is, what of the scope the computer's own system enforces, and whether the person keeps what the agent saw.
type Handler ¶
type Handler interface {
Bind(ctx context.Context, req BindRequest) (Bound, *Refusal)
Call(ctx context.Context, req CallRequest) (desktoplink.Answer, *Refusal)
Unbind(ctx context.Context, req UnbindRequest) *Refusal
}
Handler answers a link service's messages. The link service, or a stand-in for it, implements it; Serve dispatches to it.
type Message ¶
type Message struct {
Bind *BindRequest `json:"bind,omitempty"`
Call *CallRequest `json:"call,omitempty"`
Unbind *UnbindRequest `json:"unbind,omitempty"`
Bound *Bound `json:"bound,omitempty"`
Answer *desktoplink.Answer `json:"answer,omitempty"`
// Refused says why the link service did not do what was asked.
Refused *Refusal `json:"refused,omitempty"`
OK bool `json:"ok,omitempty"`
}
Message is one line on the socket: exactly one of its fields is set. The run sends Bind, Call or Unbind; the link service answers Bound, Answer, Refused or OK.
func ReadMessage ¶
ReadMessage decodes one message strictly: a field it does not know refuses it.
type Refusal ¶
type Refusal struct {
Reason string `json:"reason"`
Server string `json:"server,omitempty"`
Message string `json:"message,omitempty"`
}
Refusal says why the link service refused a bind or a call: Reason is one of the receipt's desktop-refused details, Server the application server it concerns, and Message what the person is told, in the link service's words.
func NotRelayed ¶ added in v0.7.33
func NotRelayed() *Refusal
NotRelayed is the refusal of a message a relay does not carry.
type Relayed ¶ added in v0.7.33
type Relayed struct {
Socket string `json:"socket"`
Run string `json:"run"`
Bound Bound `json:"bound"`
Via string `json:"via"`
}
Relayed is a binding made on another computer, whose link service the run reaches through a relay: the run id the far link service bound and its binding, the socket on this computer that carries each call there, and how the calls get there, for the receipt.
type UnbindRequest ¶
UnbindRequest ends a run's binding.