Writing a plugin¶
A Horae plugin is an MCP server over stdio that the core starts for one run. It returns data
and proposes intents; it never writes anything itself
(ADR 0002,
ADR 0003). You can write one in any language that
speaks MCP; the Python SDK, horae-sdk, does the protocol work for you.
Provisional
The plugin contract (schemas decisions 35 and 36 and the manifest) is provisional, and the
SDK is 0.x: its API can still change between minor versions. The SDK's changelog notes
are in the SDK reference. Installing a plugin with horae plugin add
is not on main yet (concepts).
1. Start from the template¶
horae-dev/template-plugin is a GitHub
template repository: "Use this template" gives a repository whose CI passes unchanged. It
holds an example plugin (a source that proposes a task.create per message), a plugin.yaml
checked by the SDK's helpers, recorded-input tests, and CI. Rename the example with
scripts/rename.py, then write your own tools. What the template holds and how to use
it.
2. The roles¶
| Role | Declared in plugin.yaml |
SDK | Called by |
|---|---|---|---|
| source | provides.sources |
@plugin.source(ref) or a Source subclass |
a collect step |
| transform | provides.transforms |
@plugin.transform(ref) or a Transform subclass |
a transform step |
| sink | provides.sinks |
a Sink subclass |
the core, to apply intents |
| notifier | provides.notifiers |
a Notifier subclass |
the core, for notify |
A minimal source, from the SDK's examples/hello:
from horae_sdk import Call, Output, Permissions, Plugin, intents
plugin = Plugin("hello", version="0.1.0", permissions=Permissions(intents=["task.create"]))
@plugin.source("hello.greet")
def greet(call: Call, name: str = "world") -> Output:
task = intents.task_create(f"Greet {name} back", key=intents.fingerprint("hello", name))
return Output({"greeting": f"Hello, {name}!"}, intents=[task])
if __name__ == "__main__":
plugin.run()
Rules that matter, in the order they bite:
- Never
print: stdout is the protocol channel. Log to stderr. - A tool's parameters are the pipeline's trusted configuration.
call.input(a transform's input, the previous step's data) is untrusted: it may be a mail. Never take a path to read or write from it. - Build every note or task from untrusted text with the SDK's
intentsbuilders (task_createescapes titles for Obsidian Tasks). - Return data that is JSON. Raise
PluginError("message")for an error the user should see.
3. Declare the least you need¶
plugin.yaml is where a plugin states its permissions, which the user approves and the core
pins in horae.lock:
name: github
version: 0.1.0
provides:
sources: [github.review_requests]
permissions:
network: [api.github.com]
secrets: [GITHUB_TOKEN]
paths: {}
intents: []
runtime: { protocol: mcp-stdio, command: ["python", "-m", "horae_github"] }
Generate it from the code (plugin.manifest(...), dump_manifest) rather than by hand, and
let a test compare the two.
Third-party plugins: a module command, static metadata, no build
A plugin that is not first-party (any index but the Horae marketplace, or a direct install
from a git URL) runs only in a container, and Horae never builds its project: only the
dependencies of its uv.lock are installed, from hashed wheels, and its sources are
imported from its tree (src/<module> if it has a src/ directory, else the tree root).
So setup.py, build hooks and console scripts never run or exist. Such a plugin must:
- start with the venv's interpreter running a module:
command: ["python", "-m", "<module>"](a console-script command is refused at install); - declare its
[project]metadata statically (nodynamic = [...]: uv would run the build backend to compute it, so it is refused); - take every dependency from PyPI (
https://pypi.org/simple, uv's default index) as a hashed wheel: no other index, no uv workspace, notool.uv.sourcespath, git or url entry, noname @ ...direct reference.
See plugin containers.
4. SDK 0.6 APIs¶
| API | Use |
|---|---|
Plugin, Permissions |
register tools; declare intents, network, network_local, secrets, optional_secrets, read and write paths |
Call, Output, PluginError |
a tool's request and result; call.input, call.paths |
call.host_allowed(url) |
True, False or None (unknown core): is this https URL on a host approved in horae.lock? Check the URL you are about to connect to, after redirects |
network_local=["127.0.0.1:1143"] (0.6) |
a local-network service (Home Assistant, a self-hosted ntfy, a mail bridge), approved as host:port; call.host_allowed also accepts http there; call.address_allowed(host, port) for non-HTTP protocols |
intents.* |
note_create, note_append_section, note_replace_owned_block, task_create, task_update_status, notify_push, http_post; intents.fingerprint(...) for stable task identities |
Sink, Notifier, Applied |
identity, apply, and for note sinks read, restore, parent_exists; restore_status makes a status change undoable |
horae_sdk.testing |
replay_all, call, operation: recorded-input tests |
Details, with the edge cases (the exact host matching rules, Obsidian Tasks escaping, reminder order, upgrading a sink from 0.4): SDK reference.
5. Test with recorded inputs¶
A recording is one call as the core makes it, and what the plugin must answer. The harness
replays it through MCP, with the same arguments and _meta keys as the real host:
from pathlib import Path
from horae_sdk.testing import replay_all
def test_recordings() -> None:
replay_all(plugin, Path(__file__).parent / "recordings")
HORAE_SDK_RECORD=1 pytest rewrites the recordings from the current outputs (refused in CI;
review the diff). Recordings must be synthetic: no personal data, no secret. Include a
hostile input (a subject with markup or a newline) to see it neutralized.
6. Publishing to the marketplace¶
The index is horae-dev/marketplace: an entry
maps a plugin name and a semver to the full commit SHA that the tag v<version> points
to. Release a tagged version first, then open a pull request that adds the entry; the
marketplace's CI clones the repository, checks that the pinned commit exists and matches the
tag, and validates the plugin.yaml there against the core's validator.
The marketplace's contribution guide and review policy for third-party plugins is
CONTRIBUTING.md
(proposed in marketplace#10; it is a 404
until that pull request is merged). Read it before you open your first entry, and read the
security model for what a reviewer looks at: permissions, untrusted input
handling and supply chain (threat boundary B6).
You do not need the marketplace to try a plugin: the planned horae plugin add
https://github.com/you/plugin-x@<sha> installs from any git URL at a pinned commit.