Plugin protocol

The JSON-RPC wire format behind the SDKs, the WebAssembly module ABI, and every message, limit and error code.

The wire format, for writing a plugin without an SDK. The Node.js SDK and the Rust SDK wrap all of it; read the quick start first either way.

API version 1 is everything on this page except host/timer and pane/status, which are version 2, and the panel elements marked API 4 under UI tree, which are version 4, tools/call, which is version 5, and terminal/setProxy, which is version 6.

Transport#

Agentty starts the plugin with the plugin folder as the working directory:

runtimeCommand
nodenode <main> — Node.js from the login shell PATH, Homebrew, Volta or nvm
pythonpython3 <main>
executable<main>
wasmnone — <main> is a WebAssembly module Agentty runs itself, see WebAssembly plugins

Messages are JSON-RPC 2.0 objects, one per line, UTF-8, on stdin (Agentty → plugin) and stdout (plugin → Agentty). Lines longer than 16 MB are rejected. Anything on stdout that is not JSON is logged and ignored; stderr goes to the plugin log.

When stdin closes or shutdown arrives, exit. A plugin still running 1.5 seconds after shutdown gets SIGTERM, and SIGKILL 1.5 seconds after that. When Agentty quits, both follow immediately.

Agentty → plugin#

MessageKindparams
initializerequest — answer it{ apiVersion, agentty: { version }, plugin: { id, name, version, dir, dataDir }, language, context }
command/executenotification{ command, args, context }
panel/open · panel/closenotification{ context }
ui/eventnotification{ element, event, value?, item?, action?, context }
context/changednotification{ context }
url/opennotification{ path, query, url, context }
pane/statusnotification{ paneId, status, running, agent, title, cwd } — a pane this plugin started changed what it is doing (workspace.read, API 2)
tools/callrequest — answer it{ name, arguments, context } — an AI agent is calling a tool (mcp.tools, API 5)
plugin/uninstallrequest — answer it{ context } — the user is uninstalling the plugin; sent only when the manifest lists onUninstall in activationEvents, starting it first if needed. Remove what it put outside its data folder (a helper program it installed, say), then answer. Agentty waits up to 5 seconds, then removes it either way
shutdownnotification{}

initialize is sent first, followed immediately by whatever started the plugin — a command, the panel opening, or a link. Answer initialize with any result, for example {}.

Plugin → Agentty#

Send these as requests (with an id) to get a result or an error, or as notifications (no id) when you do not care.

MethodPermissionparamsResult
ui/setPanel{ tree }null
ui/showPanel{}null
ui/notify{ message, kind } — info, success, warning, errornull
ui/setBadge{ text }, max 8 charactersnull
context/get{}The context
host/info{}{ version, apiVersion, language, uiFeatures }
host/openUrl{ url } — http/httpsnull
host/copy{ text } — up to 100,000 charactersnull
host/timer{ ms } — API 2{ elapsedMs }, once the time has passed
host/revealPathworkspace.read{ path } — absolute, existingnull
prompt/injectprompt.inject{ text, title?, target?, paneId?, workspaceId?, agent?, cwd?, submit? }{ status: "asked" } or { status: "sent", paneId }
terminal/sendterminal.write{ paneId?, text, submit? } — focused pane without paneId{ paneId }
terminal/setProxyterminal.proxy{ port, token } (token: 16–128 letters, digits, -, _), or { port: null } to stop — terminals opened from then on go through the plugin's proxy on 127.0.0.1null
session/getsession.read{ paneId?, maxTurns? } — default 200, max 2000{ paneId, agent, sessionId, title, cwd, status, turnCount, turns }
workspace/listworkspace.read{}[{ id, name, cwd, active, panes }]
net/fetchnet.request{ url, method?, headers?, body?, timeoutMs?, proxy? }{ status, statusText, url, headers, body, truncated, binary, bytes, durationMs }
storage/get{ key }{ key, value } — value is null when unset
storage/set{ key, value } — null removes itnull
storage/keys{}[key]

Agentty drops ui/notify calls arriving faster than one per 700 ms, answering them normally, and stops a plugin that sends more than 240 messages a second. Context fields are limited by the plugin's permissions.

Reaching the network#

net/fetch is the only way a plugin reaches the network. Permissions has the bounds Agentty puts on it — methods, headers, sizes, timeouts, redirects — and the short version is that nothing of yours travels with the request: no cookie, no stored credential, only what the plugin put in it.

Answering tool calls from agents (API 4)#

When an AI agent calls one of your tools, Agentty sends tools/call with { name, arguments, context }. Answer with a result — a string, any JSON value, or MCP-shaped content { "content": [{ "type": "text", "text": "…" } | { "type": "image", "data": "<base64>", "mimeType": "image/png" }], "isError": false }. Other content types are dropped. Or answer with a JSON-RPC error; its message goes to the agent as an error.

The plugin must answer within 120 seconds. At most 8 calls may wait on one plugin. Arguments are at most 256 KB; text handed to the agent is cut at 100,000 characters.

Waiting, and hearing that an agent finished#

host/timer is how a plugin waits: a request answered once the time has passed. 100 ms at the shortest, an hour at the longest, eight at a time. A module runs only while it is handling a message, so this is the whole of how it comes back to something later — answering it is all the plugin gets, which is why it is not a way to run in the background.

pane/status is how a plugin hears that an agent it started has finished. A plugin learns a pane id from prompt/inject ({ status: "sent", paneId }); Agentty remembers which plugin started which pane and tells only that plugin, when that pane's status changes — working, idle, finished, permission, question, interrupted, exited, or closed once. At most 32 panes are followed at a time.

A prompt the user placed themselves is followed too: target: "ask" answers { status: "asked" } with no pane id, because there is none yet, and the session the user picks is watched all the same — its first pane/status is where the plugin learns which pane it became. A plugin with more than one question outstanding tells them apart by title, which is the one it gave the prompt.

Status arrives whether or not anything is being drawn: a window behind another, or one on a locked screen, is not drawn, and a plugin waiting for an agent must not be waiting for the user to come back. AgentOS plugins are built on these two.

Remembering things#

storage/* is what a plugin remembers between runs: one JSON document in its own folder (<data dir>/plugin-data/<plugin>/storage.json, created 0600), read and written by key. Keys are lower-case letters, digits, ., - and _; at most 64 of them, and a megabyte in total. A plugin that runs as a process can write its own files instead; a WebAssembly plugin has none, so this is how it keeps anything.

Error codes#

CodeMeaning
-32601Unknown method
-32602Invalid parameters — bad UI tree, no such pane, …
-32001Permission missing, or (for the browser only) refused because a link reached the plugin — until it restarts
-32002Unavailable — no window open, no session yet

An example exchange#

text
→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"apiVersion":1,"plugin":{"id":"hello"},"language":"en","context":{}}}
→ {"jsonrpc":"2.0","method":"panel/open","params":{"context":{}}}
← {"jsonrpc":"2.0","id":1,"result":{}}
← {"jsonrpc":"2.0","id":1,"method":"ui/setPanel","params":{"tree":{"type":"column","children":[{"type":"button","id":"go","label":"Go"}]}}}
→ {"jsonrpc":"2.0","id":1,"result":null}
→ {"jsonrpc":"2.0","method":"ui/event","params":{"element":"go","event":"click","context":{}}}
← {"jsonrpc":"2.0","id":2,"method":"prompt/inject","params":{"text":"Hello","target":"ask"}}
→ {"jsonrpc":"2.0","id":2,"result":{"status":"asked"}}

→ is Agentty to plugin, ← is plugin to Agentty. Request ids are counted per direction.

WebAssembly plugins#

"runtime": "wasm" makes main a .wasm module that Agentty runs inside itself, on an interpreter — one file that works on macOS, Windows and Linux.

A module can call the functions Agentty hands it and nothing else. There is no file, no socket, no environment variable, no process and no clock beyond a counter, so a WebAssembly plugin cannot read ~/.agentty, the user's projects or their credentials however it is written. What it wants from Agentty it asks for with the same messages a process plugin writes to stdout, and the permissions in the manifest are checked the same way.

The module exports:

ExportMeaning
memoryits linear memory — the standard export of a Rust or C module
agentty_alloc(len: i32) -> i32a buffer of len bytes for Agentty to write a message into
agentty_on_message(ptr: i32, len: i32)one UTF-8 JSON message from Agentty

and imports, from the module named agentty:

ImportMeaning
send(ptr: i32, len: i32)one UTF-8 JSON message to Agentty
log(ptr: i32, len: i32)one line for the plugin's log
now_ms() -> i64milliseconds since the Unix epoch

Messages are the same JSON-RPC objects as over stdio, one per call, without the newline. A module that imports anything else does not load. Agentty also refuses a module larger than 64 MB, caps its memory at 64 MB, and gives each message a budget of work: a plugin that does not return is stopped with "did not finish in time", and one that sends more than 256 messages while handling a single one is stopped as well — send and log count together, so a loop that only logs is not free.

The Rust SDK hides all of this.

UI tree#

Every node is an object with a type:

text
column   { children, gap? }                gap: none | small | medium | large
row      { children, gap?, wrap? }
section  { title, children }
text     { text, style? }                  style: body | title | muted | small | code | error | success
button   { id, label, icon?, variant?, disabled? }   variant: primary | secondary | ghost | danger
input    { id, placeholder?, value?, rows?, mono? }
         mono: monospace font (API 4)
         completions (API 4): [{ label, insert?, detail? }] suggested for the word being typed;
         a {{ before it and }} after it are replaced too
         rows > 1: a text area that many lines tall (max 24); Enter adds a
         line and a paste keeps its line breaks
list     { id, items, empty? }
         items: [{ id, title, subtitle?, detail?, icon?, tone?, actions?: [{ id, label?, icon?, tooltip? }] }]
         depth: tree indent 0–8, tag: label before the title (≤ 8 chars) in tagTone (API 4)
choice   { id, options: [{ value, label }], value? }
toggle   { id, label, value? }
badge    { text, tone? }                   tone: neutral | info | success | warning | error
spinner  { text? }
divider  {}
flow     { id, steps: [{ id, title, subtitle?, icon?, state?, selected?, side? }] }
         state: off | on | active | done | error — steps of an automation, top to bottom
popover  { id, title, children }            a card beside the panel; the first one in the tree is open

API 4:
card     { children, title?, subtitle?, icon?, tone? }   a raised box; tone colors the icon and edge
grid     { children, columns?, gap?, widths? }      equal columns (1–6, default 2), wrapping onto new rows
         widths: per column, "240px" fixed or "2" a share — replaces columns
         id?, resizable? (API 4): the first fixed column can be dragged; resize with the width
         fill: takes the height left, each column scrolling on its own (API 4)
tabs     { id, tabs: [{ id, label, icon?, badge?, closable? }], value, children }
         closable: a close button that sends close
         children: the picked tab's content only
table    { id, columns: [{ label, align?, grow? }], rows: [{ id, cells, tone? }], empty?, selected? }
         align: start | center | end; grow: share of the width (1–12); one cell per column
keyValue { items: [{ label, value, tone?, mono? }] }
stat     { label, value, detail?, icon?, tone? }
progress { value, label?, detail?, tone? }  value from 0 to 1; detail replaces the percentage
callout  { text, title?, icon?, tone? }     tone defaults to info
select   { id, options: [{ value, label }], value?, placeholder?, disabled? }
checkbox { id, label, value?, description?, disabled? }
code     { text, language?, title? }       colored by language (rust, json, ts, sh, …), with a copy button

API 5:
image    { src?, id?, alt?, width?, height?, fit?, caption?, placeholder?, drop?, into? }
                                           a picture from the plugin's own folder (files/*): PNG, JPEG, WebP or GIF,
                                           never an SVG; height 240 by default; fit: contain | cover; without src an
                                           empty slot; drop (with id, needs files) takes pictures dropped from the Finder
graph    { id, nodes, edges?, height?, movable?, fill? }
                                           node cards at x, y on a canvas joined by wires, like an image pipeline; fill takes
                                           the panel's height; the user scrolls and zooms inside it (− % + fit, ⌘/Ctrl + scroll)
         nodes: [{ id, title, subtitle?, icon?, tone?, x, y, width?, inputs?, outputs?, children?, state?, selected? }]
         edges: [{ from: { node, port }, to: { node, port }, tone?, idle? }]

Events: button sends click; input sends change and submit with value; list sends select with item, and row buttons send action with item and action; choice sends change with the option value; toggle sends change with the new boolean.

A list item's tone colors its icon, using the same values as badge.

flow sends select with the step's id as item; popover sends close from its close button. From API 4: tabs sends change with the tab's id; table sends select with the row's id as item; select sends change with the option's value; checkbox sends change with the new boolean. From API 5: image sends click, and drop with [{ path, name, size }] (copied into the plugin's folder, as files/pick answers); graph sends select with the node's id as item when its heading is clicked, and, when movable, move with the node as item and { x, y } as value once a heading is dragged — keep the place and send it back.

A plugin that uses the API 4 elements says "apiVersion": 4 in its manifest. host/info lists the elements the running Agentty draws in uiFeatures. Designing a panel says which one to use for what.

Testing without Agentty#

A node, python or executable plugin is an ordinary program reading stdin and writing stdout, so you can drive it from a test: write an initialize request, then the notifications you want to exercise, and assert on the JSON the plugin writes back.

A wasm module is driven the same way by any WebAssembly runtime that can supply the three imports above.