Writing Plugins
From nothing to an installed, running plugin. The manifest schema is in the Plugin API Reference; the architecture and security model are in Plugin System Internals; installing and managing plugins as a user is Plugins.
A plugin is a directory with an aoe-plugin.toml manifest and, optionally, a worker: an executable the host spawns that speaks JSON-RPC 2.0 over newline-delimited JSON on stdio, in any language. The host does not link your code; the manifest is the contract.
Scaffold from the template
cookiecutter gh:agent-of-empires/plugin-template
The starter generates a complete plugin (manifest, worker, tests, CI) in Python, Node, or Rust. It builds, passes its tests, and answers a status command out of the box; the rest of this guide explains what it generated.
The manifest
Every plugin declares identity, what it contributes, and, with a worker, how to build and launch it:
id = "dev.example.my-plugin"
name = "My Plugin"
version = "0.1.0"
api_version = 19
aoe_version = ">=1.11.0, <2.0.0"
description = "What the plugin does."
capabilities = ["runtime.worker"]
[[commands]]
id = "status"
title = "My Plugin: status"
[[settings]]
key = "enabled"
label = "Enable My Plugin"
type = "boolean"
default = true
[[ui]]
slot = "pane"
id = "my_plugin_pane"
Pick an id outside the reserved aoe.* and agent-of-empires.* namespaces, set api_version to the schema version you target, and set aoe_version to the host range you have tested.
A worker requests only the grants it uses. runtime.worker is required to run any code at all; add net, session.read, notifications, and so on as needed. Static contributions (commands, keybinds, themes, ui, status) need no capability. The user grants the exact declared set at install, pinned to the manifest hash, so an update that widens capabilities must be re-approved. Keep the list honest and minimal.
Agent integrations are optional contributions, not worker RPCs. They require api_version >= 19; launch, detection, and reply-fallback extensions require API 21 and a host that implements them. Provider-native status and replies also require session.integration. When declared, session.integration requires valid, nonempty provider_versions on every integration entry. See Agent integrations for the launch grammar, supported capture declarations, and communication contract.
An active provider owns terminal status: an unavailable or invalid report produces Unknown. A provider that keeps reporting while its provider_version is outside, or unparseable against, the declaration’s provider_versions is the one case that steps aside: its report is not consumed, the session keeps its pane rules, and the host logs the reported version and the declared ranges. When the provider is disabled or absent, normal pane detection remains available.
The install approval lists each declared tool, launch command, and agent declaration. Updates that add or change an integration require approval again; removals alone do not. The command runs as the host user only when a user launches that agent.
The worker
The host spawns the worker, sends one JSON-RPC request per line on stdin, and reads one response per line on stdout; the worker exits when stdin reaches EOF.
{"jsonrpc": "2.0", "id": 1, "method": "my-plugin.status", "params": {}}
{"jsonrpc": "2.0", "id": 1, "result": {"ok": true, "message": "running"}}
The host maps a command id to a fully namespaced method, plugin.<id>.<command-id>, so a worker for dev.example.my-plugin actually receives plugin.dev.example.my-plugin.status. Dispatch on the trailing segment so either form works, return a JSON-RPC error with code -32601 for an unknown method, and never respond to a message with no id.
The host also pushes notifications that carry no id, such as session.status.changed (api_version >= 14) and session.lifecycle.changed (api_version >= 19) for plugins that hold session.read. Ignore methods you do not handle and never reply. See Session status events in the Plugin API reference.
Build and launch
The entrypoint must be plugin-relative, never resolved on the daemon’s PATH. Build into .aoe-build/, which the host excludes from the plugin’s integrity hash, then point command at the artifact:
[runtime]
kind = "command"
command = [".aoe-build/venv/bin/my-plugin-worker"]
[[runtime.build]]
command = ["python3", "-m", "venv", ".aoe-build/venv"]
platforms = ["linux", "macos"]
[[runtime.build]]
command = [".aoe-build/venv/bin/pip", "install", "."]
platforms = ["linux", "macos"]
Build steps run once, at install and update, in the user’s interactive shell, where PATH is reliable. A compiled plugin can instead ship a release asset with kind = "release-binary".
Git and approved build commands share a fixed two-hour budget for each preparation/application. On exhaustion the host settles its owned process group before rollback; closing an observer does not cancel accepted work. Commands remain unsandboxed, and escaping processes or arbitrary filesystem stalls are not covered by a malicious-code containment guarantee.
Install and test locally
aoe plugin install ./my-plugin # runs the build steps, prompts for grants
aoe plugin update my-plugin # re-runs the build, re-approves changed grants
aoe plugin uninstall my-plugin
To work on a plugin whose id is in a reserved namespace (aoe.*, agent-of-empires.*), install the checkout with --dev. TypeScript plugins can run Node through AOE_NODE, which build steps and workers receive.
Drive the worker by hand before installing, to confirm the protocol:
echo '{"jsonrpc":"2.0","id":1,"method":"my-plugin.status","params":{}}' | <your-worker>
The starter ships a worker-contract test (spawn the worker, send a request, assert the response) plus its CI. Keep it green; it is the cheapest guard on the protocol.
Publish
Push a vX.Y.Z tag to cut a GitHub release, and users install it with aoe plugin install gh:your-org/my-plugin. To be listed in the featured index, which lets a plugin claim a verified namespace, open a PR adding your release’s source tree hash to that index in the main repository.