applink

package
v0.7.55-dev.2 Latest Latest
Warning

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

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

Documentation

Overview

Package applink is the app link: the MCP server through which a persistent agent reaches the application that runs it, and nothing else. The gateway launches it on the runner image with no network and one bind, a socket the agent's supervisor serves; each tool call is forwarded over that socket as one request, and the supervisor's answer is returned as the tool's result. It holds no credential, and the tools it lists are a fixed set per agent: none of them changes what an agent is given, so an agent cannot widen its own grants through it.

This package is part of the embedded runner-image build context and therefore MUST remain stdlib-only.

Index

Constants

View Source
const (
	SocketDir   = "/run/agentry"
	SocketMount = SocketDir + "/app.sock"
)

SocketMount is where the app link finds the supervisor's socket: the supervisor's own, bound by its exact path, or, where the engine's daemon runs in a VM, the relay's, in a volume mounted at SocketDir.

View Source
const (
	PartSelf     = "self"
	PartTasks    = "tasks"
	PartRecall   = "recall"
	PartHelper   = "helper"
	PartMeetings = "meetings"
)

The parts a tool set is composed of, each the tools of one capability the agent declares: its own name and persona (PartSelf), its tasks (PartTasks), the search of its earlier conversations (PartRecall), Agentry's helper tools (PartHelper), the meeting tools (PartMeetings), the publisher tools (PartPublisher, publisher.go) and the subagent tools (PartSubagents, subagents.go). A set is the parts it has, in this order, joined by commas (Compose).

View Source
const (
	TaskAdd    = "task_add"
	TaskList   = "task_list"
	TaskUpdate = "task_update"
	TaskRemove = "task_remove"
	// TellPerson is a task's message to the person: what the task was for
	// (a reminder, something they asked to be told), shown to them in the
	// chat apart from the work the task's turn did.
	TellPerson = "tell_person"
)

The Assistant's task tools: the tasks its heartbeat fires, which it registers itself. A task is a turn at a time; it grants nothing.

View Source
const (
	TellPersonMax     = 4096
	TellPersonPerTurn = 3
)

TellPersonMax bounds one tell_person message, in bytes, and TellPersonPerTurn the messages one task's turn may send.

View Source
const (
	MeetingArm    = "meeting_arm"
	MeetingList   = "meeting_list"
	MeetingCancel = "meeting_cancel"
)

The Assistant's meeting tools: it arms Agentry Desktop to record a call during a meeting the person asked it to record, lists what is armed and cancels a window. The application answers them; an armed window records only a call the application detects inside it, so a meeting nobody joins records nothing.

View Source
const (
	ArmLead  = 5 * time.Minute
	ArmTail  = 15 * time.Minute
	ArmAhead = time.Hour
)

An armed window opens ArmLead before the meeting starts and closes ArmTail after it ends. A window that would open more than ArmAhead from now is refused: arming is done close to the meeting, so a calendar read hours earlier never holds a recording open for a meeting that moved.

View Source
const (
	MaxMeetingLength    = 12 * time.Hour
	MaxMeetingTitle     = 200
	MaxMeetingAttendee  = 200
	MaxMeetingAttendees = 100
	MaxMeetingAppHint   = 64
	MaxMeetingWindowID  = 64
)

The bounds of meeting_arm's arguments.

View Source
const (
	QuickAgentMine     = "quickagent_mine"
	QuickAgentVersions = "quickagent_versions"
	QuickAgentFetch    = "quickagent_fetch"
	QuickAgentRevise   = "quickagent_revise"
	QuickAgentFork     = "quickagent_fork"
	QuickAgentSubmit   = "quickagent_submit"
	QuickAgentManage   = "quickagent_manage"
)

The publisher tools: the agent reads the QuickAgents the person publishes, fetches one's files into its share folder, has them revised, and asks the application to fork, submit and manage them. The application answers them with the person's own sign-in, which never reaches the agent, and asks the person before every fork, revision, submission and owner action, each time it is asked: no earlier answer stands for a later one. A submission is an ordinary one, which the registry's checks decide like any other, and what the agent creates is private. None of them changes what the agent is given.

View Source
const (
	ManageMakePrivate = "make_private"
	ManageRetire      = "retire"
	ManageRestore     = "restore"
	ManageYank        = "yank"
	ManageWithdraw    = "withdraw"
)

The owner actions quickagent_manage takes.

View Source
const (
	ReviseInAgentry  = "agentry"
	ReviseOnComputer = "computer"
)

The places quickagent_revise has the Drafter run.

View Source
const (
	SubagentList   = "subagent_list"
	SubagentRun    = "subagent_run"
	SubagentResult = "subagent_result"
)

The subagent tools: a persistent agent starts runs of the QuickAgents its roster names as subagents, each an ordinary autonomous run of the version its roster pins, in a sandbox of its own under its own contract. The agent names only a subagent its roster has on, and it can add none.

View Source
const MaxLine = 4 << 20

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

View Source
const MaxSubagentFiles = 20

MaxSubagentFiles bounds the files one subagent_run takes.

View Source
const PartPublisher = "publisher"

PartPublisher is the part of an agent that manages the person's QuickAgents: given by name to the one built-in granted it, never by a key a release can declare.

View Source
const PartSubagents = "subagents"

PartSubagents is the part of an agent with subagents: given by the subagents its release declares or the person adds, not by a key.

View Source
const PublisherFolder = "quickagents"

The folder of the share a QuickAgent's files are fetched into, as share/quickagents/<namespace>/<name>.

View Source
const Recall = "recall"

Recall is the Assistant's search of its own earlier conversations: it reads what was said, and changes nothing.

View Source
const RecallMaxLimit = 20

RecallMaxLimit bounds the turns one recall answers with.

View Source
const SelfConfigure = "self_configure"

SelfConfigure is the Assistant's tool for its own name and personality.

View Source
const ServerName = "agentry-applink"

ServerName is the app link's name in the gateway's catalog.

Variables

The built-ins' sets: Agentry Helper's is the helper tools, the Assistant's every part but the subagents'.

View Source
var CallTimeout = 30 * time.Minute

CallTimeout bounds one call: a QuickAgent's run is answered once it is started, and a consent waits for the person.

ManageActions are quickagent_manage's actions, in the order its schema lists them.

Functions

func Compose added in v0.6.1017

func Compose(names ...string) string

Compose is the set of the parts named, in the parts' own order whatever the order given; "" for none. A name that is not a part is left out, so a set never names one (Valid).

func Has added in v0.6.1017

func Has(set, part string) bool

Has says set is composed with part.

func IsMeetingTool added in v0.6.999

func IsMeetingTool(tool string) bool

IsMeetingTool says tool is one of the meeting tools.

func IsPublisherTool added in v0.7.41

func IsPublisherTool(tool string) bool

IsPublisherTool says tool is one of the publisher tools.

func IsSubagentTool added in v0.7.1

func IsSubagentTool(tool string) bool

IsSubagentTool says tool is one of the subagent tools.

func ParseMeetingCancel added in v0.6.999

func ParseMeetingCancel(raw json.RawMessage) (string, error)

ParseMeetingCancel reads meeting_cancel's argument, the window's id.

func Parts added in v0.6.1017

func Parts() []string

Parts are the parts there are, in the order a set lists them.

func Relay

func Relay(ctx context.Context, cfg RelayConfig) error

Relay serves the socket until In ends or ctx is done.

func Serve

func Serve(ctx context.Context, in io.Reader, out, logw io.Writer, set, socket string) error

Serve answers MCP on stdio for set, forwarding each call to socket.

func SetParts added in v0.6.1017

func SetParts(set string) []string

SetParts are the parts a set is composed of; nil for a set that is not one Compose makes.

func Tools

func Tools(set string) []string

Tools are a set's tool names, in a fixed order; none for a set Compose does not make.

Types

type Answer

type Answer struct {
	Text    string `json:"text"`
	IsError bool   `json:"isError,omitempty"`
}

Answer is the supervisor's answer, one JSON line.

func Call

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

Call sends one request over the socket and reads one answer.

type Frame

type Frame struct {
	ID      uint64   `json:"id,omitempty"`
	Ready   bool     `json:"ready,omitempty"`
	Request *Request `json:"request,omitempty"`
	Answer  *Answer  `json:"answer,omitempty"`
}

Frame is one line between the relay and the CLI: the relay's ready line, a call it carries out (ID 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.

type MeetingArmArgs added in v0.6.999

type MeetingArmArgs struct {
	Start     time.Time `json:"start"`
	End       time.Time `json:"end"`
	Title     string    `json:"title"`
	Attendees []string  `json:"attendees,omitempty"`
	App       string    `json:"app,omitempty"`
}

MeetingArmArgs are meeting_arm's arguments.

func ParseMeetingArm added in v0.6.999

func ParseMeetingArm(raw json.RawMessage, now time.Time) (MeetingArmArgs, error)

ParseMeetingArm reads meeting_arm's arguments and holds them to its rules at now: two times with their offsets, the end after the start and still to come, the window opening within ArmAhead, a title, and each text within its bound. An argument it does not know refuses the call.

func (MeetingArmArgs) Closes added in v0.6.999

func (a MeetingArmArgs) Closes() time.Time

Closes is when the armed window closes.

func (MeetingArmArgs) Opens added in v0.6.999

func (a MeetingArmArgs) Opens() time.Time

Opens is when the armed window opens.

type RelayConfig

type RelayConfig struct {
	// Listen is the socket's path.
	Listen string
	// Owner is the uid:gid the socket is given, the app link's user; empty
	// leaves it the relay's.
	Owner string
	// In carries the answers from the CLI, Out 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 {
	Tool      string          `json:"tool"`
	Arguments json.RawMessage `json:"arguments,omitempty"`
}

Request is one tool call as the app link sends it over the socket: one JSON line on a connection of its own.

func ReadRequest

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

ReadRequest reads one request from a connection, as the supervisor does.

type Tool

type Tool struct {
	Name        string
	Description string
	Schema      map[string]any
}

Tool is one tool of a set: its name, what it does, and its input schema.

Jump to

Keyboard shortcuts

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