desktop

package
v0.7.35-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 11 Imported by: 0

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

View Source
const MaxLine = desktoplink.MaxLine

MaxLine bounds a line either way.

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

View Source
const SocketName = "desktop.sock"

SocketName is the link service's socket in the runner home's socket folder, beside the persistent agents' sockets.

Variables

View Source
var BindTimeout = 2 * time.Minute

BindTimeout bounds a bind: the link service may start an installed server and list its tools to answer.

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

func RelayedCallOnly(m Message, run string) bool

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

func Serve(ctx context.Context, ln net.Listener, h Handler) error

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

func SocketPath(home string) string

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

func (c Client) Bind(ctx context.Context, req BindRequest) (Bound, error)

Bind binds a run. A refusal is returned as a *Refusal.

func (Client) Call

Call sends one tool call. A refusal is returned as a *Refusal.

func (Client) Forward added in v0.7.33

func (c Client) Forward(ctx context.Context, m Message) (Message, error)

Forward sends one message as it is and reads the link service's answer, for a relay that carries a run's calls and its unbind from another computer: a call waits as long as a call does, an unbind as an unbind.

func (Client) Unbind

func (c Client) Unbind(ctx context.Context, req UnbindRequest) error

Unbind ends the run's binding.

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

func ReadMessage(line []byte) (Message, error)

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.

func (*Refusal) Error

func (r *Refusal) Error() string

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

type UnbindRequest struct {
	Run   string `json:"run"`
	Token string `json:"token"`
}

UnbindRequest ends a run's binding.

Jump to

Keyboard shortcuts

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