Documentation
¶
Overview ¶
Package desktoplink is the desktop link: the MCP servers through which a run reaches the applications installed on the person's own computer, and nothing else. For each application server a release declares and the run bound, the gateway launches one entry of this role on the runner image, agentry-desktop-<id>, with no network and one mount, the run's relay volume. Each tool call is written to the relay's socket in that volume as one request; the relay carries it over its own stdio, which the CLI holds through the engine's attach, to Agentry Desktop, which launches the installed server as the person, gates the call by its class and answers it; the answer comes back the same way and is returned as the tool's result. Nothing of the installed server runs in the sandbox, and nothing the agent sends names a command: a call carries a tool's name and its arguments, and the application's server is the one the person approved for it, chosen by Agentry Desktop from the entry's id.
This package is part of the embedded runner-image build context and therefore MUST remain stdlib-only.
Index ¶
- Constants
- Variables
- func Command(id string) []string
- func ComputerToolClass(name string) (string, bool)
- func ComputerToolNames() []string
- func Relay(ctx context.Context, cfg RelayConfig) error
- func Serve(ctx context.Context, in io.Reader, out, logw io.Writer, ...) error
- func ServerName(id string) string
- type Answer
- type Bind
- type Call
- type ComputerTool
- type Content
- type Frame
- type RelayConfig
- type Request
- type Tool
Constants ¶
const ( ComputerRead = "read" ComputerAct = "act" )
The classes of the computer-use tools, as an application server's tools are classed: read looks, act changes something on the person's screen.
const ( MaxWaitSeconds = 30 MaxHoldKeySeconds = 10 )
The longest a wait or a held key may last, in seconds.
const ( SocketDir = "/run/agentry-desktop" SocketMount = SocketDir + "/link.sock" BindFile = SocketDir + "/bind.json" )
SocketDir is the relay volume's mount point in the relay's container and in every desktop link entry; SocketMount the socket the relay serves in it, and BindFile the run's binding the relay writes there for the entries: the run token and each bound server's tools.
const ComputerID = "computer"
ComputerID is the id of the computer-use entry, agentry-desktop-computer, whose tools are ComputerTools.
const MaxLine = 4 << 20
MaxLine bounds a line either way, on the socket and on the relay's stdio.
const RelayRole = "desktoplink-relay"
RelayRole is the relay's command on the runner image.
const ServerPrefix = "agentry-desktop-"
ServerPrefix starts every desktop link entry's name in the gateway's catalog: agentry-desktop-<id> for the application server <id>.
Variables ¶
var CallTimeout = 30 * time.Minute
CallTimeout bounds one call: an exec call waits for the person's answer in Agentry Desktop.
Functions ¶
func Command ¶
Command is a desktop link entry's command, which the run's docker filter knows its container by.
func ComputerToolClass ¶ added in v0.7.30
ComputerToolClass is a computer-use tool's class, and whether the tool is one.
func ComputerToolNames ¶ added in v0.7.30
func ComputerToolNames() []string
ComputerToolNames are the computer-use tools' names, in the same order.
func Relay ¶
func Relay(ctx context.Context, cfg RelayConfig) error
Relay reads the binding from In, writes it beside the socket, serves the socket until In ends or ctx is done.
func Serve ¶
func Serve(ctx context.Context, in io.Reader, out, logw io.Writer, id, bindFile, socket string) error
Serve answers MCP on stdio for the application server id, forwarding each call to the relay's socket with the run token the binding holds. The tools it lists are the bound server's; a server the run did not bind lists none and answers every call as not bound.
func ServerName ¶
ServerName is the catalog entry's name for an application server.
Types ¶
type Answer ¶
type Answer struct {
Content []Content `json:"content,omitempty"`
IsError bool `json:"isError,omitempty"`
// Window names the window a computer-use call saw or acted in, as
// Agentry Desktop names it (the application and the title), for the
// run's call log; the agent is not sent it.
Window string `json:"window,omitempty"`
}
Answer is a call's answer: the content items the installed server returned, or one text item saying why the call was refused.
func TextAnswer ¶
TextAnswer is an answer of one text item.
type Bind ¶
Bind is the run's binding, written by the relay for the desktop link entries alone: the run token Agentry Desktop issued, which every call carries, and each bound server's tools.
type Call ¶
type Call struct {
Tool string `json:"tool"`
Arguments json.RawMessage `json:"arguments,omitempty"`
}
Call is a tool call as a frame carries it.
type ComputerTool ¶ added in v0.7.30
ComputerTool is one computer-use tool and its class.
func ComputerTools ¶ added in v0.7.30
func ComputerTools() []ComputerTool
ComputerTools are the computer-use tools, in a fixed order.
type Content ¶
type Content struct {
Type string `json:"type"`
Text string `json:"text,omitempty"`
Data string `json:"data,omitempty"`
MimeType string `json:"mimeType,omitempty"`
}
Content is one item of a tool's result, as MCP carries it: text, an image (Data base64 and its MimeType) or an embedded resource's text.
type Frame ¶
type Frame struct {
ID uint64 `json:"id,omitempty"`
Ready bool `json:"ready,omitempty"`
Bind *Bind `json:"bind,omitempty"`
Server string `json:"server,omitempty"`
Token string `json:"token,omitempty"`
Request *Call `json:"request,omitempty"`
Answer *Answer `json:"answer,omitempty"`
}
Frame is one line between the relay and the CLI: the CLI's binding (first, before the relay listens), the relay's ready line, a call it carries out (ID, Server, Token and Request), or the answer carried back (ID and Answer).
type RelayConfig ¶
type RelayConfig struct {
// Listen is the socket's path; the binding is written beside it.
Listen string
// Owner is the uid:gid the socket and the binding are given, the
// desktop link's user; empty leaves them the relay's.
Owner string
// In carries the binding and then the answers from the CLI, Out the
// ready line and the calls to it.
In io.Reader
Out io.Writer
// Log takes what goes wrong.
Log io.Writer
}
RelayConfig is what the relay serves.
type Request ¶
type Request struct {
Token string `json:"token"`
Server string `json:"server"`
Tool string `json:"tool"`
Arguments json.RawMessage `json:"arguments,omitempty"`
}
Request is one tool call as a desktop link entry writes it to the relay's socket: one JSON line on a connection of its own, carrying the run token.
type Tool ¶
type Tool struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
InputSchema json.RawMessage `json:"inputSchema,omitempty"`
// Class is the tool's class as Agentry Desktop gives it (read, act or
// exec), for the run's counts and call log; Agentry Desktop sends it
// only to a run that names the link protocol's revision.
Class string `json:"class,omitempty"`
}
Tool is one tool of a bound server, as Agentry Desktop listed it from the installed server and as the desktop link lists it to the gateway.