desktoplink

package
v0.7.55-dev.4 Latest Latest
Warning

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

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

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

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

View Source
const (
	MaxWaitSeconds    = 30
	MaxHoldKeySeconds = 10
)

The longest a wait or a held key may last, in seconds.

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

View Source
const ComputerID = "computer"

ComputerID is the id of the computer-use entry, agentry-desktop-computer, whose tools are ComputerTools.

View Source
const MaxLine = 4 << 20

MaxLine bounds a line either way, on the socket and on the relay's stdio.

View Source
const RelayRole = "desktoplink-relay"

RelayRole is the relay's command on the runner image.

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

View Source
var CallTimeout = 30 * time.Minute

CallTimeout bounds one call: an exec call waits for the person's answer in Agentry Desktop.

Functions

func Command

func Command(id string) []string

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

func ComputerToolClass(name string) (string, bool)

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

func ServerName(id string) string

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 Send

func Send(ctx context.Context, socket string, req Request) (Answer, error)

Send writes one request to the socket and reads one answer.

func TextAnswer

func TextAnswer(text string, isError bool) Answer

TextAnswer is an answer of one text item.

func (Answer) Text

func (a Answer) Text() string

Text is the answer's text items joined, for a log or a message.

type Bind

type Bind struct {
	Token   string            `json:"token"`
	Servers map[string][]Tool `json:"servers"`
}

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.

func ReadBind

func ReadBind(path string) (Bind, error)

ReadBind reads the binding the relay wrote.

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

type ComputerTool struct {
	Tool
	Class string
}

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

func ReadFrame

func ReadFrame(line []byte) (Frame, error)

ReadFrame decodes one frame strictly: a field it does not know refuses it.

func (Frame) IsCall

func (f Frame) IsCall() bool

IsCall says the frame is a call and nothing else: an id, a server, a token and a request naming a tool, with no answer and no ready mark.

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.

func ReadRequest

func ReadRequest(r io.Reader) (Request, error)

ReadRequest reads one request line.

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.

Jump to

Keyboard shortcuts

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