# Anna Developer Hub — full corpus > Developer documentation for the Anna platform: build Tools (Executa plugins), Skills, and Anna Apps; the full Host API, Realtime event, and manifest reference. Every page below is plain Markdown — append `.md` to any `/developers/**` URL, or send `Accept: text/markdown`, to get the raw source instead of the JS-rendered HTML shell. > Content bundle: c523104ad3c997d8c9d712f6b8367bd920655e9c (built 2026-09-04T08:48:53Z) # === Overview === --- title: Welcome to the Anna Developer Hub description: What you can build for Anna, and how to find your way around. section: overview slug: welcome updated: 2026-04-23 estimated_minutes: 3 --- Anna is a universal AI agent — and almost everything she does at runtime is something a third-party developer can extend, replace, or compose. This hub is the single source of truth for that work. It covers the two building blocks you can ship — **Executa** (the umbrella for both **Tools** and **Skills**) and **Anna Apps** — and walks you from "hello world" to a published listing in the App Store. > [!IMPORTANT] > **Executa = Tools + Skills.** They are two flavours of the same first-class object in Anna's catalogue, distribution pipeline, and developer Console. A *Tool* is an executable plugin process; a *Skill* is a declarative `SKILL.md` recipe. Both are stored as `Executa` records, both go through the same draft → version → visibility lifecycle, and both can be bundled into Anna Apps. ## Where to start - **New to Anna?** Read [Concepts: Executa and Apps](/developers/overview/concepts) first. It's a 4-minute primer that prevents 90% of confusion. - **Want to ship a Tool today?** Jump to a quickstart: [Python](/developers/tools/executa-python), [Node.js](/developers/tools/executa-nodejs), or [Go](/developers/tools/executa-go). - **Prefer a declarative recipe?** Start with [What is a Skill](/developers/skills/skill-intro). - **Building a curated experience?** Start with [What is an Anna App](/developers/apps/app-intro) and the [Manifest Reference](/developers/apps/app-manifest). ## What this hub is not - It is **not** the Developer Console. The Console (at `/developer`) is where verified developers manage their own Executas and Apps once published; this hub is the public learning resource. - It is **not** the API reference for end-user features. For Anna's user-facing docs see [docs.anna.partners](https://docs.anna.partners). ## Stay in the loop - **Examples**: [`anna-executa-examples`](https://github.com/whtcjdtc2007/anna-executa-examples) — runnable Tool plugins in Python, Node.js, and Go. - **Forum**: [forum.anna.partners](https://forum.anna.partners) — proposals, RFCs, show-and-tell. - **Changelog**: linked from the Reference section as we ship platform updates. --- --- title: Concepts: Executa (Tools + Skills) and Apps description: One umbrella, two flavours, and the App that bundles them. The 4-minute version. section: overview slug: concepts updated: 2026-04-23 estimated_minutes: 4 --- Anna exposes two extension surfaces: - **Executa** — a single first-class capability the agent can call. An Executa is either a **Tool** (an executable process speaking JSON-RPC) or a **Skill** (a declarative `SKILL.md` recipe). Both share the same registry, draft/version/visibility lifecycle, and developer Console. - **Anna App** — a curated bundle of one or more Executas (tools + skills) plus a prompt addendum, published to the App Store and `#mention`-able by the user. > [!IMPORTANT] > When this hub says "publish an Executa" or "Executa Hub", it means *either a Tool or a Skill*. The flavour is just an `executa_type` field on the record (`tool` or `skill`). ## At a glance | Aspect | **Executa: Tool** | **Executa: Skill** | **Anna App** | |---|---|---|---| | **Form** | A standalone process speaking JSON-RPC | A folder containing `SKILL.md` | A manifest bundling Executas + prompt | | **Language** | Any (Python, Node, Go, Rust, …) | Markdown (+ optional supporting files) | JSON manifest + linked Executa references | | **How the agent uses it** | Called directly as a callable capability with a typed schema | Listed as a recipe the agent can consult on demand; the recipe text guides the agent, which then uses its built-in capabilities to act | Activated when the user `#mentions` it; brings its bundled Executas + prompt addendum into the turn | | **Best for** | Side effects, network, file system, native APIs | Declarative recipes, prompts-as-code, reusable runbooks | Curated end-user experiences | | **Distribution** | Source or signed binary in the Executa Hub | Markdown payload in the Executa Hub | The Anna App Store | ## Tools (executable Executa) A **Tool** is the lowest-level Executa. You write a small program — in any language — that: 1. Reads JSON-RPC requests from stdin. 2. Implements at least two methods: `describe` (return your manifest) and `invoke` (run a tool). 3. Writes JSON-RPC responses to stdout. Logs go to stderr. That's it. There is no SDK to learn and no runtime to embed. The protocol is documented in [Protocol Spec](/developers/tools/executa-protocol). > [!TIP] > If you can write a CLI in your favourite language, you can ship a Tool. ## Skills (declarative Executa) A **Skill** is a folder containing a `SKILL.md` — a recipe written in Markdown. Skills are not callable capabilities of their own; instead, the agent is told *what skills exist* and *what each one is for*, and consults a skill's full body only when it decides the skill is relevant. The body then guides the agent, which carries out any actions using its built-in capabilities. This means a Skill is essentially **prompt-as-code**: declarative knowledge the agent can pull in on demand, not a process that runs on its own. Skills are the right choice when: - The capability is mostly prompt + light orchestration (no compiled code of your own). - You want to ship and version capabilities without building a binary. - You want non-engineers to author plugins. See [What is a Skill](/developers/skills/skill-intro) and [SKILL.md Format](/developers/skills/skill-format). ## Anna Apps An **Anna App** is a curated bundle published to the App Store. A user installs it once; thereafter they can `#mention` the App in chat and Anna will: - Activate **all** the App's required Executas (tools and/or skills) for that turn. - Inject the App's `system_prompt_addendum` into the system prompt. - Optionally wrap the user message with a prefix template. Apps are how a domain expert ships an end-user experience — "Weekly Review Coach", "GitHub Triage Buddy" — without forcing each user to install a dozen separate Executas by hand. ## How they relate ``` +---------------------------+ | Anna App | manifest + prompt addendum | (published in App Store) | +-------------+-------------+ │ bundles ▼ +---------------------------+ +---------------------------+ | Executa (type: tool) | …or… | Executa (type: skill) | | process + JSON-RPC | | SKILL.md + metadata | +---------------------------+ +---------------------------+ \\ / \\________ Executa Hub ___________/ (one catalogue, one wizard, one draft → version flow) ``` You can ship a single Tool and stop there. You can ship a single Skill without ever touching JSON-RPC. You only need an App when you want to package an end-user experience. ## Next - [Architecture & Lifecycle](/developers/overview/architecture) - [Choosing What to Build](/developers/overview/choosing) --- --- title: Architecture & Lifecycle description: How an Executa call flows through Anna, from chat input to response. section: overview slug: architecture updated: 2026-04-23 estimated_minutes: 5 --- This page is a map. If you've read [Concepts](/developers/overview/concepts) and you want to understand where your code runs, what it can see, and when it gets killed — start here. ## The runtime Anna is composed of: - A **frontend** (web/desktop/mobile) that drives chat. - A **gateway / API** (Nexus) that stores state, routes turns, and orchestrates tool calls. - A **runtime** that hosts the LLM session and the tool executor (`matrix`). - A **NATS** message bus for streaming, fan-out, and event delivery. - An **Executa Hub** registry that catalogues installable Executas (both Tools and Skills). Executas — both Tool and Skill flavours — are activated **inside the runtime**, on the same host. Apps don't run anywhere themselves; they're metadata + references that the runtime reads when the user `#mentions` them. ## Lifecycle of a Tool Executa call 1. **User turn arrives** — the runtime builds a system prompt, including any `@`-mentioned Executas and any `#`-mentioned Apps' contributions (system_prompt_addendum, required Executas). 2. **LLM emits a tool call** — for example `weather.lookup({ city: "Tokyo" })`. 3. **Runtime spawns the plugin process** if it isn't already warm. The binary lives wherever the user installed it; the platform passes credentials via environment variables (see [Credentials & OAuth](/developers/tools/executa-credentials)). 4. **Runtime sends `invoke`** as a single JSON-RPC line to the plugin's stdin. 5. **Plugin runs** — does its work, returns a JSON-RPC response on stdout. stderr is captured for debugging only. 6. **Runtime parses the response** and returns it to the LLM as a tool result. 7. **Process disposition**: short-lived plugins exit immediately; long-lived plugins (declared in the manifest) stay warm and serve the next call. > [!NOTE] > The runtime treats your stdout as a strict transport. Anything that isn't a valid JSON-RPC frame will fail the call. Always direct logs to stderr. ## Lifecycle of a Skill Executa call Skills don't spawn processes of their own. The runtime discovers `SKILL.md` files at agent start (or loads them from the Executa record in the database), parses the frontmatter, and registers each skill as a LangChain `@tool`. When the LLM picks the skill, the tool **returns the skill's markdown body to the LLM**, decorated with an execution-mode hint and any declared dependencies. The skill itself does *not* execute bash or Python directly. If the body contains a fenced bash/python block, the LLM reads it and — in a follow-up turn — calls the agent's built-in `exec` / `command` tools to run it inside the workspace sandbox. That keeps Skills fast and safe and lets the same skill be used from any execution backend. ## Lifecycle of an Anna App `#mention` 1. The user types `#weekly-review` in chat. The frontend resolves it against the user's installed apps and includes the `app_id` in the request. 2. The runtime loads the App's manifest, expands `required_executas` into active tools for the turn, and appends `system_prompt_addendum` (XML-fenced) to the system prompt. 3. From here, the lifecycle is identical to a normal turn — the LLM sees one or more new tools and may choose to call them. ## Concurrency & isolation - Each Executa call runs in its **own process**. There is no shared state with the runtime beyond stdin/stdout and environment variables. - Multiple plugins can be invoked **in parallel** within a single turn if the LLM emits parallel tool calls. - The runtime applies a per-call timeout (default 30s; long-running plugins can declare a different limit in their manifest — see [Manifest Reference](/developers/apps/app-manifest)). ## What you can rely on - Stdin / stdout / stderr. - A working temp directory (`$TMPDIR`). - Environment variables for credentials, declared in your manifest. - Outbound network (subject to user/admin policy). ## What you can't rely on - Persistent disk between calls (use the user's data directory only when explicitly granted). - A specific operating system. Ship a single binary per platform if you depend on native code. - Inter-tool messaging. Tools shouldn't call each other directly — let the LLM coordinate. --- --- title: Choosing What to Build description: Tool, Skill, or App? A short decision guide. section: overview slug: choosing updated: 2026-04-23 estimated_minutes: 3 --- You usually know what you want Anna to do. The question is which surface to ship. > [!NOTE] > Tools and Skills are the two flavours of **Executa**. Picking between them is choosing the *shape* of an Executa, not picking a different system. See [Concepts](/developers/overview/concepts). ## Decision shortcut > [!TIP] > **Need to call a network API, run a binary, hold credentials, or stream results?** → Build a **Tool** Executa. > > **Want to encode a recipe, runbook, or prompts-as-code that the agent reads and acts on?** → Build a **Skill** Executa. > > **Want to package an end-user experience and have it appear in the App Store?** → Build an **Anna App** that bundles one or more Executas. ## Worked examples | You want to… | Ship a… | Why | |---|---|---| | Query the GitHub API for issues | **Tool** Executa | Auth + network = process-level concern | | Convert a CSV to a tidy chart | **Skill** Executa (e.g. `chart-generator`) | Mostly matplotlib glue the agent runs via `exec` | | Bundle five Executas into a "Marketing Researcher" experience | **App** that bundles those Executas | Discovery + installability is the whole product | | Add a `pdf.summarize` capability for everyone in the org | **Tool** Executa (or wrap in an App for a listing) | New capability, may need binary deps | | Teach Anna a new "code review" workflow with prompts only | **Skill** Executa | Pure declarative; no native code | ## Cost / friction tradeoff | | Tool Executa | Skill Executa | Anna App | |---|---|---|---| | Time to first run | medium (write + spawn a process) | low (one markdown file) | adds a few minutes on top of underlying Executas | | Distribution effort | medium (binary builds, registry submission) | low (markdown payload) | high (review, listing assets) | | Audience | technical | technical & non-engineer | end users | Note that Tools *and* Skills go through the same Executa Hub publish flow (drafts, versions, visibility) — the cost difference above is in *authoring*, not in distribution mechanics. ## When in doubt Build the smallest unit that solves your problem first, then promote upward: 1. Start with a **Skill** Executa to validate the workflow. 2. If you need real I/O, credentials, or streaming, extract that part into a **Tool** Executa. 3. When you're ready to publish to end users, wrap everything in an **App**. --- # === Build a Tool === --- title: What is Executa description: Anna's plugin extension system: standalone processes speaking JSON-RPC 2.0 over stdio. section: tools slug: executa-intro updated: 2026-04-24 estimated_minutes: 5 --- **Executa** is Anna's plugin extension system. You write a small program in any language; it speaks **JSON-RPC 2.0** over **stdio**; the Anna Agent spawns it, asks what tools it provides, and exposes them to the LLM via NATS RPC. There is **no SDK** and no embedded runtime. Anything that can read a line and print a line can be an Executa plugin. ## What you'll implement Three JSON-RPC methods (the third is optional): | Method | Purpose | Default timeout | |---|---|---| | `describe` | Return the manifest (name, version, tools, parameters, credentials) | 5 s | | `invoke` | Execute one tool with a dict of arguments | 60 s (per-tool overridable) | | `health` | Optional liveness probe | 3 s | The Agent runtime handles transport, request IDs, error wrapping, restart, and credential injection. > [!IMPORTANT] > **Your plugin must be a long-running stdio server.** It has to keep reading stdin in a loop and only exit on stdin EOF (or when the Agent kills it). A process that exits after answering one `describe` or `invoke` is the single most common bug — the Agent UI will show your plugin as **Stopped** even though `describe` succeeded, and every call pays a fresh cold-start. See [Common pitfalls](#common-pitfalls) below. ## The smallest working plugin ```python import json, sys MANIFEST = { "name": "hello", "display_name": "Hello", "version": "0.1.0", "description": "Echo text back.", "tools": [{ "name": "echo", "description": "Echo input back", "parameters": [ {"name": "text", "type": "string", "description": "Input", "required": True} ], }], } def handle(req): method = req["method"] if method == "describe": return {"result": MANIFEST} if method == "invoke": params = req.get("params") or {} tool = params.get("tool") args = params.get("arguments") or {} if tool == "echo": return {"result": {"success": True, "data": {"text": args.get("text", "")}}} return {"error": {"code": -32601, "message": f"Unknown tool: {tool}"}} return {"error": {"code": -32601, "message": f"Unknown method: {method}"}} for line in sys.stdin: line = line.strip() if not line: continue req = json.loads(line) payload = handle(req) sys.stdout.write(json.dumps({"jsonrpc": "2.0", "id": req.get("id"), **payload}) + "\n") sys.stdout.flush() ``` Key conventions visible above: - **`for line in sys.stdin:`** — the loop is mandatory. Never exit after a single request. - `sys.stdout.flush()` after every response — without it, line-buffered Python may withhold the response until the buffer fills. - The `invoke` request carries `params.tool` (the tool name) and `params.arguments` (the LLM-supplied dict). - A successful invoke returns `{"success": true, "data": {...}}` inside `result`. The Agent decodes this into an `InvokeResult` and forwards `data` to the LLM. - Errors use the JSON-RPC 2.0 `error` frame with standard codes. - All log lines go to **stderr** — anything on stdout that is not a JSON-RPC frame breaks the protocol. ## Common pitfalls | Symptom | Root cause | Fix | |---|---|---| | UI shows **Stopped** even though `describe` returned a manifest | Process exits after one request instead of looping | Wrap request handling in `for line in sys.stdin:` (or equivalent) and only exit on EOF | | Plugin shows up under **Extra Agent Plugins** instead of the user-installed card | The Agent installed the plugin under a `tool_id` that differs from the one the user minted on `/executa` (e.g. a dev-registered plugin with no `expected_tool_id`) | Install / register the plugin under the **minted** `tool_id` so the UI can join them — see [Publishing → Stabilise the manifest](/developers/tools/executa-publish#1-stabilise-the-manifest) | | `describe timeout` on first run for big PyInstaller bundles | Cold start exceeds the default 5 s timeout | Slim the bundle, or rely on the Agent's binary-cold-start timeout (60 s) which kicks in on first scan | | Garbled responses / `JSON parse error` in Agent logs | Plugin printed a banner / progress text on **stdout** | Move all human-readable logs to **stderr** | Quick smoke test that catches the long-running bug locally: ```bash echo '{"jsonrpc":"2.0","id":1,"method":"describe"}' | ./my-plugin & PID=$! sleep 2 if kill -0 $PID 2>/dev/null; then echo OK; else echo BUG: exited after one request; fi kill $PID 2>/dev/null ``` ## Where to go next - **Pick a language**: [Python](/developers/tools/executa-python), [Node.js](/developers/tools/executa-nodejs), [Go](/developers/tools/executa-go). - **Read the spec**: [Protocol Spec](/developers/tools/executa-protocol). - **Add credentials**: [Credentials](/developers/tools/executa-credentials). - **Ship a binary**: [Binary Distribution](/developers/tools/executa-binary). - **Publish**: [Publishing](/developers/tools/executa-publish). > [!NOTE] > Runnable samples — including credential and OAuth examples — live in [`whtcjdtc2007/anna-executa-examples`](https://github.com/whtcjdtc2007/anna-executa-examples). Snippets in this hub are extracted from that repo so you can cross-check against working code. --- --- title: Quickstart — Python description: Build, smoke-test, and run a Python Executa plugin in under five minutes. section: tools slug: executa-python updated: 2026-04-22 estimated_minutes: 5 --- This quickstart walks you through writing a Python plugin from scratch. You'll end with a working `text-tools` plugin that exposes two tools and passes a smoke test. ## Prerequisites - Python 3.10+ - A terminal ## 1. Create the plugin ```bash mkdir text-tools && cd text-tools touch plugin.py chmod +x plugin.py ``` ```python #!/usr/bin/env python3 """text-tools — a tiny Anna Executa plugin.""" import json, sys, hashlib MANIFEST = { "name": "text-tools", "display_name": "Text Tools", "version": "0.1.0", "description": "Reverse strings and hash text.", "author": "you@example.com", "tools": [ { "name": "reverse", "description": "Reverse a string.", "parameters": [ {"name": "text", "type": "string", "description": "Input text", "required": True} ], }, { "name": "sha256", "description": "Compute SHA-256 of input text.", "parameters": [ {"name": "text", "type": "string", "description": "Input text", "required": True} ], }, ], } def invoke(tool: str, args: dict) -> dict: if tool == "reverse": return {"success": True, "data": {"output": args["text"][::-1]}} if tool == "sha256": return {"success": True, "data": {"output": hashlib.sha256(args["text"].encode()).hexdigest()}} raise ValueError(f"unknown tool: {tool}") def handle(req: dict) -> dict: method = req.get("method") if method == "describe": return {"result": MANIFEST} if method == "invoke": params = req.get("params") or {} try: return {"result": invoke(params.get("tool", ""), params.get("arguments") or {})} except ValueError as exc: return {"error": {"code": -32601, "message": str(exc)}} except Exception as exc: # noqa: BLE001 return {"error": {"code": -32603, "message": str(exc)}} if method == "health": return {"result": {"status": "ready"}} return {"error": {"code": -32601, "message": f"unknown method: {method}"}} def main() -> None: for line in sys.stdin: line = line.strip() if not line: continue try: req = json.loads(line) except json.JSONDecodeError as exc: payload = {"error": {"code": -32700, "message": str(exc)}} req_id = None else: payload = handle(req) req_id = req.get("id") sys.stdout.write(json.dumps({"jsonrpc": "2.0", "id": req_id, **payload}) + "\n") sys.stdout.flush() if __name__ == "__main__": main() ``` ## 2. Smoke-test the protocol ```bash echo '{"jsonrpc":"2.0","method":"describe","id":1}' | python plugin.py ``` You should see the manifest. Now invoke a tool — note `params.tool` (not `params.name`): ```bash echo '{"jsonrpc":"2.0","method":"invoke","id":2,"params":{"tool":"reverse","arguments":{"text":"anna"}}}' | python plugin.py ``` Expected response: ```json {"jsonrpc": "2.0", "id": 2, "result": {"success": true, "data": {"output": "anna"}}} ``` > [!TIP] > Always send protocol traffic through stdin and route logs to stderr (`print("debug", file=sys.stderr)`). Anything you `print()` to stdout that isn't a valid JSON-RPC message will be ignored — making it the #1 cause of "the plugin loaded but never replies". ## 3. Install on the Agent Your Agent admin can register the plugin in one of three ways: - **`uv tool install .`** — publishes a CLI entry point; the Agent picks it up via `uv` distribution. - **`pipx install .`** — alternative for Python plugins. - **Local archive** — build a `.tar.gz` (PyInstaller `--onedir` is the recommended path for plugins with native deps), copy it to the Agent, and paste the absolute archive path into the Executa admin form (`distribution_type: local`). The Agent runs the [full v2 install pipeline](/developers/tools/executa-binary#local-archive-distribution-no-urls-no-upload) (extract → versioned dir → atomic symlink), so multi-file binaries with `lib/`, `_internal/`, etc. all work. See [Publishing](/developers/tools/executa-publish) for the public Hub flow. ## 4. Where to next - **Add credentials** — [Credentials](/developers/tools/executa-credentials). - **Ship a single-file binary** — [Binary Distribution](/developers/tools/executa-binary). - **Read the full spec** — [Protocol Spec](/developers/tools/executa-protocol). - **See it in context** — [`examples/python/example_plugin.py`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/examples/python/example_plugin.py). --- --- title: Quickstart — Node.js description: Ship an Anna Executa plugin in JavaScript in under five minutes. section: tools slug: executa-nodejs updated: 2026-04-22 estimated_minutes: 5 --- A Node.js Executa plugin is just a CLI that reads JSON lines and writes JSON lines. ## Prerequisites - Node.js 18+ - A terminal ## 1. Scaffold the plugin ```bash mkdir json-tools && cd json-tools npm init -y touch plugin.js && chmod +x plugin.js ``` ```javascript #!/usr/bin/env node "use strict"; const readline = require("readline"); const MANIFEST = { name: "json-tools", display_name: "JSON Tools", version: "0.1.0", description: "Format JSON and base64-encode strings.", author: "you@example.com", tools: [ { name: "format_json", description: "Pretty-print a JSON string.", parameters: [ { name: "input", type: "string", description: "Raw JSON", required: true }, { name: "indent", type: "integer", description: "Indent spaces", required: false, default: 2 }, ], }, { name: "b64", description: "Base64-encode a string.", parameters: [ { name: "text", type: "string", description: "Input", required: true }, ], }, ], }; function invoke(tool, args) { if (tool === "format_json") { return { success: true, data: { output: JSON.stringify(JSON.parse(args.input), null, args.indent ?? 2) } }; } if (tool === "b64") { return { success: true, data: { output: Buffer.from(args.text, "utf8").toString("base64") } }; } throw Object.assign(new Error(`unknown tool: ${tool}`), { code: -32601 }); } function send(id, payload) { process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, ...payload }) + "\n"); } const rl = readline.createInterface({ input: process.stdin }); rl.on("line", (line) => { const trimmed = line.trim(); if (!trimmed) return; let req; try { req = JSON.parse(trimmed); } catch (e) { return send(null, { error: { code: -32700, message: "parse error" } }); } try { if (req.method === "describe") return send(req.id, { result: MANIFEST }); if (req.method === "health") return send(req.id, { result: { status: "ready" } }); if (req.method === "invoke") { const params = req.params || {}; return send(req.id, { result: invoke(params.tool, params.arguments || {}) }); } return send(req.id, { error: { code: -32601, message: `unknown method: ${req.method}` } }); } catch (e) { send(req.id, { error: { code: e.code ?? -32603, message: e.message } }); } }); ``` ## 2. Smoke-test ```bash echo '{"jsonrpc":"2.0","method":"describe","id":1}' | node plugin.js echo '{"jsonrpc":"2.0","method":"invoke","id":2,"params":{"tool":"b64","arguments":{"text":"anna"}}}' | node plugin.js ``` > [!WARNING] > `console.log` writes to stdout. Anything you `console.log` mixes into protocol output and breaks the plugin. Use `console.error` (stderr) for logs. ## 3. Install on the Agent Publish the binary entry point with `npm` (`bin` field in `package.json`) and register the plugin with `distribution_type: npm`. For local iteration, build a `.tar.gz` (e.g. `tar czf my-tool.tgz dist/`) and point the Agent at the archive path with `distribution_type: local` — the Agent runs the [full v2 install pipeline](/developers/tools/executa-binary#local-archive-distribution-no-urls-no-upload) and supports multi-file binaries (native addons in `node_modules/`, etc.). ## 4. Build a binary (optional) Node 20+ ships [single-executable applications](https://nodejs.org/api/single-executable-applications.html) via `--experimental-sea-config`. For multi-platform CI the easiest route remains [`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg): ```bash npm install -g @yao-pkg/pkg pkg plugin.js --targets node20-macos-arm64,node20-linux-x64,node20-win-x64 --out-path dist ``` See [Binary Distribution](/developers/tools/executa-binary) for the full matrix and signing guidance. ## 5. Where to next - **Add credentials** — [Credentials](/developers/tools/executa-credentials). - **Read the spec** — [Protocol Spec](/developers/tools/executa-protocol). - **See it in context** — [`examples/nodejs/example_plugin.js`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/examples/nodejs/example_plugin.js). --- --- title: Quickstart — Go description: Ship a single-binary Anna Executa plugin in Go. section: tools slug: executa-go updated: 2026-04-22 estimated_minutes: 6 --- Go is the language of choice when you want **one statically linked binary per platform**. No interpreter, no runtime — just `chmod +x` and run. ## Prerequisites - Go 1.21+ - A terminal ## 1. Scaffold ```bash mkdir sysinfo-tool && cd sysinfo-tool go mod init sysinfo-tool touch main.go ``` ```go package main import ( "bufio" "crypto/sha256" "encoding/hex" "encoding/json" "fmt" "os" "runtime" ) type Request struct { Jsonrpc string `json:"jsonrpc"` Method string `json:"method"` ID any `json:"id"` Params map[string]any `json:"params,omitempty"` } type Response struct { Jsonrpc string `json:"jsonrpc"` ID any `json:"id"` Result any `json:"result,omitempty"` Error *Err `json:"error,omitempty"` } type Err struct { Code int `json:"code"` Message string `json:"message"` } var manifest = map[string]any{ "name": "sysinfo", "display_name": "System Info", "version": "0.1.0", "description": "Report OS info or hash a string.", "tools": []map[string]any{ {"name": "os_info", "description": "Return host OS and arch.", "parameters": []map[string]any{}}, {"name": "sha256", "description": "Hash a string with SHA-256.", "parameters": []map[string]any{ {"name": "text", "type": "string", "description": "Input", "required": true}, }}, }, } func invoke(tool string, args map[string]any) (any, *Err) { switch tool { case "os_info": return map[string]any{ "success": true, "data": map[string]string{"os": runtime.GOOS, "arch": runtime.GOARCH}, }, nil case "sha256": text, _ := args["text"].(string) sum := sha256.Sum256([]byte(text)) return map[string]any{ "success": true, "data": map[string]string{"output": hex.EncodeToString(sum[:])}, }, nil } return nil, &Err{Code: -32601, Message: fmt.Sprintf("unknown tool: %s", tool)} } func main() { enc := json.NewEncoder(os.Stdout) s := bufio.NewScanner(os.Stdin) s.Buffer(make([]byte, 0, 1<<20), 1<<22) for s.Scan() { line := s.Bytes() if len(line) == 0 { continue } var req Request if err := json.Unmarshal(line, &req); err != nil { _ = enc.Encode(Response{Jsonrpc: "2.0", Error: &Err{Code: -32700, Message: err.Error()}}) continue } resp := Response{Jsonrpc: "2.0", ID: req.ID} switch req.Method { case "describe": resp.Result = manifest case "health": resp.Result = map[string]string{"status": "ready"} case "invoke": tool, _ := req.Params["tool"].(string) args, _ := req.Params["arguments"].(map[string]any) result, errOut := invoke(tool, args) if errOut != nil { resp.Error = errOut } else { resp.Result = result } default: resp.Error = &Err{Code: -32601, Message: "unknown method: " + req.Method} } _ = enc.Encode(resp) } } ``` ## 2. Smoke-test ```bash echo '{"jsonrpc":"2.0","method":"describe","id":1}' | go run main.go echo '{"jsonrpc":"2.0","method":"invoke","id":2,"params":{"tool":"os_info","arguments":{}}}' | go run main.go ``` A successful invoke returns `{"result": {"success": true, "data": {...}}}` — the wrapper the Agent decodes into `InvokeResult`. ## 3. Build native binaries ```bash GOOS=darwin GOARCH=arm64 go build -ldflags "-s -w" -o dist/sysinfo-darwin-arm64 main.go GOOS=darwin GOARCH=amd64 go build -ldflags "-s -w" -o dist/sysinfo-darwin-x86_64 main.go GOOS=linux GOARCH=amd64 go build -ldflags "-s -w" -o dist/sysinfo-linux-x86_64 main.go GOOS=linux GOARCH=arm64 go build -ldflags "-s -w" -o dist/sysinfo-linux-aarch64 main.go GOOS=windows GOARCH=amd64 go build -ldflags "-s -w" -o dist/sysinfo-windows-x86_64.exe main.go ``` File names follow the [platform key convention](/developers/tools/executa-binary#platform-keys) so the Agent's binary distribution can pick the right asset automatically. Full multi-platform Makefile in [`examples/go/Makefile`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/examples/go/Makefile). > [!TIP] > `-ldflags "-s -w"` strips the symbol table and DWARF debug info; expect ~30 % smaller binaries. ## 4. Where to next - **Add credentials** — [Credentials](/developers/tools/executa-credentials). - **Cross-platform binaries** — [Binary Distribution](/developers/tools/executa-binary). - **See it in context** — [`examples/go/main.go`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/examples/go/main.go). --- --- title: Protocol Specification description: JSON-RPC 2.0 over stdio — the wire format an Executa plugin must speak. section: tools slug: executa-protocol updated: 2026-04-24 estimated_minutes: 9 --- Anna's plugin protocol is **JSON-RPC 2.0 over stdio**, line-delimited (LF). It is intentionally minimal so that any language with stdin/stdout can implement it. Protocol version: **1.1**. ## Transport ``` +----------+ stdin (request) +----------+ | | ------------------->| | | Anna | | Plugin | | Agent | stdout (response) | Process | | | <-------------------| | | | | | | | stderr (logs) | | | | <- - - - - - - - - -| | +----------+ +----------+ ``` ### Constraints 1. **stdout is for protocol responses only.** Each line must be one JSON object. Non-JSON lines on stdout are tolerated (debug-logged) but are *never* interpreted as results. 2. **stderr is for logs.** The Agent captures it and surfaces it in the trace view. 3. **One message per line**, terminated by `\n`. No `Content-Length` headers. 4. **UTF-8** encoding. 5. **Single-line per response ≤ 2 MiB.** Beyond ~512 KiB use the [file transport](#file-transport-large-responses) escape hatch. 6. **The plugin process is long-running.** It MUST keep reading stdin in a loop and only exit on stdin EOF (the Agent closes stdin to request shutdown) or on an explicit signal. A process that exits after sending a single response is a protocol violation — the Agent will mark it as **Stopped** and pay a fresh cold-start on every subsequent invocation. After writing each response, **flush stdout** before looping back to read the next request. ## Methods ### `describe` Called once after the runtime spawns the plugin. **Request:** ```json { "jsonrpc": "2.0", "method": "describe", "id": 1 } ``` **Response (Manifest):** ```json { "jsonrpc": "2.0", "id": 1, "result": { "name": "my-tool", "display_name": "My Tool", "version": "1.0.0", "description": "What this plugin does.", "author": "Your Name", "homepage": "https://example.com/my-tool", "icon": "🔧", "category": "productivity", "license": "MIT", "tools": [ { "name": "do_something", "description": "Description shown to the LLM.", "timeout": 60, "streaming": false, "parameters": [ { "name": "input_text", "type": "string", "description": "Input.", "required": true }, { "name": "count", "type": "integer", "description": "Repeat count.", "required": false, "default": 1 }, { "name": "tags", "type": "array", "items": {"type": "string"}, "description": "Tag list.", "required": false } ] } ], "credentials": [ { "name": "MY_API_KEY", "display_name": "My API Key", "description": "Get one at https://example.com/keys", "required": true, "sensitive": true } ], "runtime": { "type": "uv", "min_version": "0.1.0" } } } ``` #### Manifest fields | Field | Type | Required | Notes | |---|---|---|---| | `name` | string | yes | Lowercase kebab/snake label. **Not** the canonical identity — the registry mints a stable `tool_id` at publish time and the Agent joins installs to running plugins by that `tool_id`, so a mismatch between this `name` and the minted `tool_id` no longer matters. | | `display_name` | string | no | Defaults to `name` | | `version` | string | yes | SemVer (`MAJOR.MINOR.PATCH`) | | `description` | string | yes | One-paragraph description | | `author` | string | no | Free text | | `homepage` | string | no | Documentation / source URL | | `icon` | string | no | Emoji or URL (defaults to `🔧`) | | `category` | string | no | Free-form grouping (`general` by default) | | `license` | string | no | SPDX identifier | | `tools` | list | yes | At least one tool definition | | `credentials` | list | no | Declared secrets the Agent will inject — see [Credentials](/developers/tools/executa-credentials) | | `runtime` | object | no | Free-form runtime hints (e.g. `{"type": "uv", "min_version": "0.1.0"}`) | #### Tool definition | Field | Type | Required | Notes | |---|---|---|---| | `name` | string | yes | Unique within the plugin | | `description` | string | yes | Prompt the LLM uses to choose this tool | | `parameters` | list | no | Empty list = no arguments | | `timeout` | integer | no | Per-tool execute timeout in seconds (default 60) | | `streaming` | boolean | no | Reserved for future use | #### Parameter schema Fields per parameter: `name`, `type`, `description`, `required` (default `true`), `default`, `enum`, plus `items` / `items_type` for arrays. Supported `type` values: `string`, `integer`, `number`, `boolean`, `array`, `object`. For `array`, declare element type either as the standard JSON Schema `"items": {"type": "string"}` or as the protocol shorthand `"items_type": "string"`. The Agent accepts both. If neither is provided, `array` defaults to a list of strings (so the LLM does not pass JSON-encoded strings). ### `invoke` Invoke a tool. **Note the param shape uses `tool`, not `name`.** **Request:** ```json { "jsonrpc": "2.0", "method": "invoke", "id": 2, "params": { "tool": "do_something", "arguments": { "input_text": "hello", "count": 3 }, "context": { "credentials": { "MY_API_KEY": "sk_..." } } } } ``` `params.context.credentials` is injected by the Agent only when the user has configured the plugin's credentials. The LLM never sees this object. **Successful response (`InvokeResult` shape):** ```json { "jsonrpc": "2.0", "id": 2, "result": { "success": true, "data": { "output": "hellohellohello" }, "duration_ms": 12 } } ``` The Agent decodes `result` as `{success, data, error, duration_ms}`. Whatever you put under `data` is what the LLM will see. `duration_ms` is optional; the Agent measures wall-clock time on its end as well. **Tool-level failure** (a recoverable error — the LLM should be told about it): ```json { "jsonrpc": "2.0", "id": 2, "result": { "success": false, "error": "city not found" } } ``` ### `health` *(optional)* ```json { "jsonrpc": "2.0", "method": "health", "id": 3 } ``` ```json { "jsonrpc": "2.0", "id": 3, "result": { "status": "ready", "message": "", "details": {} } } ``` `status` must be one of `ready`, `error`, `initializing`. The runtime polls this when an admin triggers a health check; you may omit the method (the call returns method-not-found and is treated as healthy). ## JSON-RPC errors For unrecoverable errors (parse failure, unknown method, runtime exception) return the standard JSON-RPC error frame: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": -32601, "message": "Unknown tool: do_something" } } ``` | Code | Meaning | |---|---| | `-32700` | Parse error | | `-32600` | Invalid request | | `-32601` | Method / tool not found | | `-32602` | Invalid params | | `-32603` | Internal error | | `-32000` to `-32099` | Implementation-defined server error | > [!TIP] > Use `result.success = false` for *expected* failures ("city not found", "rate limited"). Use the JSON-RPC `error` frame for *programmer* errors ("unknown tool", "missing argument"). The Agent treats them differently in the trace view. ## Default timeouts | Method | Default | Override | |---|---|---| | `describe` | 5 s | not configurable | | `health` | 3 s | not configurable | | `invoke` | 60 s | per-tool via `tools[].timeout` | If your plugin needs longer for a specific tool, declare `"timeout": 600` on that tool entry. Plugins exceeding their declared timeout receive `SIGTERM` and the request resolves with a JSON-RPC timeout error. ## Lifecycle 1. The Agent spawns the plugin executable with the user's environment. 2. It immediately sends `describe` and waits up to 5 s. 3. Each tool invocation sends `invoke`; per-tool timeouts apply. 4. On idle / shutdown the runtime sends `SIGTERM` and waits up to 5 s before `SIGKILL`. 5. If the process exits unexpectedly, the runtime restarts it with exponential backoff (up to 3 attempts). > [!IMPORTANT] > Handle `SIGTERM` cleanly. Flush buffers, close file handles. Exit non-zero only if you actually crashed. ## Protocol v2 — `initialize` & reverse RPC Executa **2.0** adds an `initialize` capability handshake and a reverse-RPC channel that lets a plugin ask the host for LLM completions or persistent storage. v1 plugins keep working: if a plugin returns `method-not-found` on `initialize`, the host falls back to v1 transparently. The wire details, error codes, and worked examples live in dedicated pages: - [Lifecycle & Capability Negotiation](/developers/tools/executa-lifecycle) — `initialize` handshake, per-invoke context injection. - [Sampling](/developers/tools/executa-sampling) — `sampling/createMessage` reverse RPC. - [Persistent Storage](/developers/tools/executa-storage) — `storage/*` and `files/*` reverse RPCs (scope-parameterised: `user` / `app` / `tool`). ### Reverse-RPC ↔ parent-invoke correlation Every reverse RPC runs on behalf of exactly one in-flight `invoke`. The host injects `params.context.invoke_id` into each forward `invoke`; the plugin **must echo it back** in the reverse-RPC `params`: ```json { "jsonrpc": "2.0", "id": "req-7", "method": "host/uploadFile", "params": { "mode": "confirm", "r2_key": "exec-uploads/…", "context": { "invoke_id": "" } } } ``` The official SDKs stamp this automatically once the tool handler is wrapped (Python `with bind_invoke(params): …`, Node `bindInvoke(params, () => …)`, Go `InlineRequest.InvokeID` / `Client.SetInvokeID`). Host routing rules: | Situation | Host behavior | | --- | --- | | `context.invoke_id` matches an active invoke | Route to that invoke's context (token, deadline, quota). | | `context.invoke_id` unknown / already finished | Error `-32602` with `errorCode: UNKNOWN_INVOKE_CONTEXT`. | | Field omitted, exactly **one** invoke active | Fall back to it (legacy-SDK compatible). | | Field omitted, **multiple** invokes active | Error `-32602` with `errorCode: MISSING_INVOKE_CONTEXT` — the host never guesses. | > [!IMPORTANT] > Plugins that serve concurrent `tools.invoke` calls **must** propagate `context.invoke_id`, otherwise reverse RPCs fail deterministically with `MISSING_INVOKE_CONTEXT` instead of being silently attributed to the wrong invoke (e.g. `host/uploadFile confirm` rejecting with `r2_key does not belong to this invoke`). ## File transport (large responses) For results larger than ~512 KiB you can write the full JSON-RPC response to a temporary file and send a pointer instead: ```json { "jsonrpc": "2.0", "id": 4, "__file_transport": "/tmp/executa-resp-XXXXXX.json" } ``` The Agent reads the file, decodes the response inside it, then deletes the file. Use this when you would otherwise blow past the 2 MiB readline ceiling. See the Python sample's `send_response()` for a reference implementation: [`examples/python/example_plugin.py`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/examples/python/example_plugin.py). ## Reference The normative protocol definition is the [protocol spec in `anna-executa-examples`](https://github.com/whtcjdtc2007/anna-executa-examples) together with the Anna Agent runtime that implements it. All field names, defaults, and error codes above match the runtime exactly. --- --- title: Lifecycle & Capability Negotiation description: How the Agent spawns, initializes, calls, and shuts down an Executa plugin — including v2 reverse-RPC capability negotiation. section: tools slug: executa-lifecycle updated: 2026-08-25 estimated_minutes: 7 --- Every Executa plugin runs as a **single, long-running process** that the Matrix Agent owns end-to-end. Understanding the five lifecycle phases — and the v2 capability handshake that gates [Sampling](/developers/tools/executa-sampling) and [Persistent Storage](/developers/tools/executa-storage) — is the prerequisite for everything beyond `invoke`. ![Executa plugin lifecycle](/static/images/developers/executa-lifecycle.svg) ## Five phases | # | Phase | Direction | Default timeout | Notes | |---|---|---|---|---| | 1 | **spawn** | Agent → OS | — | Process started with the user's environment; stdin / stdout / stderr piped. | | 2 | **initialize** | Agent → Plugin | `5 s` | v2 handshake. Plugin replying with `Method not found` (or timing out) silently downgrades the session to v1. | | 3 | **describe** | Agent → Plugin | `5 s` (`60 s` on first launch of a binary onefile) | Returns the manifest. The Agent caches it for the rest of the process's life. | | 4 | **invoke** | Agent → Plugin (loop) | `60 s` per tool, overridable | Hot path. Each request also unlocks **reverse RPC** if v2 was negotiated. | | 5 | **shutdown** | Agent closes stdin → `SIGTERM` → `SIGKILL` | `5 s` grace | The plugin must keep reading stdin until EOF. Never `exit()` after a single response. | > [!IMPORTANT] > If your plugin terminates after one response, the Agent UI marks it **Stopped** even though `describe` returned a valid manifest, and every subsequent call pays a fresh cold-start. See [Common Pitfalls #1](/developers/tools/executa-pitfalls#1-plugin-process-exits-after-one-request). The Agent also restarts the plugin with exponential backoff on unexpected exit (max **3 attempts**, base delay **1 s**). ## v2 capability handshake The Agent always tries v2 first. The handshake exchanges two pieces of information: - **what the host can do for the plugin** — sampling caps, file-transport support, etc. - **what the plugin will use** — the subset of host capabilities it actually depends on. ### Request (Agent → Plugin) ```json { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": { "protocolVersion": "2.0", "clientInfo": { "name": "matrix-agent", "version": "1.0" }, "capabilities": { "sampling": { "modalities": ["text"], "maxTokensPerCall": 8192, "maxCallsPerInvoke": 8, "responseFormat": ["json_object", "json_schema"] }, "fileTransport": true } } } ``` ### Response (Plugin → Agent) ```json { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": "2.0", "server_info": { "name": "my-tool", "version": "0.1.0" }, "capabilities": { "sampling": {} } } } ``` The plugin echoes the negotiated `protocolVersion` and lists the **subset** of host capabilities it intends to invoke. An empty object (`{}`) is fine — it means "I'm aware of this capability, no extra options." ### Fallback to v1 The Agent transparently falls back to protocol **1.1** when: - the plugin times out on `initialize`, - the response is a JSON-RPC error with code `-32601` (method not found), - any other error frame is returned. v1 plugins keep working, but **lose access to all reverse-RPC features** (sampling, storage, future logging/progress). ## Manifest declarations vs. runtime capabilities The negotiation in `initialize` is necessary but not sufficient. To actually use a host capability the plugin must **also** declare it in the `describe` manifest: ```json { "name": "my-tool", "version": "0.1.0", "host_capabilities": ["llm.sample", "aps.kv"], "tools": [ /* ... */ ] } ``` | Capability string | Unlocks | Reverse RPC methods | |---|---|---| | `llm.sample` | [Sampling](/developers/tools/executa-sampling) | `sampling/createMessage` | | `aps.kv` | [APS](/developers/tools/executa-storage) — KV store | `storage/*` | | `aps.files` | APS — object/file store | `files/*` | Which APS *scopes* a plugin may touch (`user` / `tool`) is pinned by the user's storage grant (`allowedScopes`), not by extra capability strings — `storage.user` / `storage.app` / `storage.tool` are **not** valid `host_capabilities` values. See [Persistent Storage](/developers/tools/executa-storage#three-pre-conditions) for the full accepted allow-list. Without the manifest declaration, Nexus refuses the corresponding reverse RPC at the gate (`-32008 not_negotiated` for sampling, `-32021 not_granted` for storage). ## Per-invoke context injection Once v2 is live, every `invoke` request also carries a `context` block beside `tool` and `arguments`: ```json { "method": "invoke", "params": { "tool": "summarize", "arguments": { "text": "…" }, "context": { "credentials": { "OPENAI_API_KEY": "sk-…" }, "invoke_id": "8f1c…", "sampling_token": "eyJ…", "storage_token": "eyJ…" } } } ``` | Field | Source | Used for | |---|---|---| | `credentials` | [Platform Authorization](/developers/tools/executa-authorization) + per-plugin overrides | Talking to third-party APIs | | `invoke_id` | Auto-minted by the Agent (UUID hex) | Audit correlation; reverse-RPC budget keying | | `sampling_token` | Nexus, JWT `aud=executa-sampling`, TTL 600 s | `sampling/createMessage` authorization | | `storage_token` | Nexus, JWT `aud=aps-storage`, TTL 600 s | `storage/*` & `files/*` authorization | Tokens are bound to (`user_id`, `executa_tool_id`, `tool_invoke_id`) and expire shortly after the invoke completes — **never** persist them across invocations. ## Health probe (optional) ```json { "jsonrpc": "2.0", "method": "health", "id": 99 } ``` ```json { "jsonrpc": "2.0", "id": 99, "result": { "status": "ready", "message": "", "details": {} } } ``` `status` is one of `ready`, `error`, `initializing`. Plugins that omit `health` are treated as healthy (the Agent receives `-32601` and ignores it). ## Shutdown contract When the Agent wants the plugin gone, it: 1. closes stdin — your loop's `for line in sys.stdin:` should exit cleanly, 2. waits up to 5 s, 3. sends `SIGTERM`, waits another 5 s, 4. sends `SIGKILL`. > [!TIP] > Flush buffers and close file handles when stdin closes. Exit non-zero **only** if you actually crashed — the Agent treats non-zero as a fault and counts it against the restart budget. ## See also - [Protocol Specification](/developers/tools/executa-protocol) — line-delimited JSON-RPC 2.0 wire format. - [Sampling](/developers/tools/executa-sampling) — `sampling/createMessage` reverse RPC. - [Persistent Storage](/developers/tools/executa-storage) — `storage/*` & `files/*` reverse RPC. - [Common Pitfalls](/developers/tools/executa-pitfalls) — including the long-running-process bug. --- --- title: Credentials description: How plugins declare and consume API keys / tokens injected by the platform. section: tools slug: executa-credentials updated: 2026-05-11 estimated_minutes: 6 --- Most useful tools need secrets — an API key, a bearer token. Anna stores those for the user (encrypted at rest), then injects them into every `invoke` call as part of the request payload. ## Declare credentials in the manifest List every secret your plugin needs in the `credentials` field of `describe`: ```json { "credentials": [ { "name": "WEATHER_API_KEY", "display_name": "OpenWeatherMap API Key", "description": "Get one at https://openweathermap.org/api", "required": true, "sensitive": true }, { "name": "WEATHER_UNITS", "display_name": "Temperature Units", "description": "metric / imperial / standard", "required": false, "sensitive": false, "default": "metric" } ] } ``` | Field | Type | Required | Notes | |---|---|---|---| | `name` | string | yes | Identifier the Agent uses as the dict key when injecting (use `UPPER_SNAKE_CASE`) | | `display_name` | string | no | Shown in the credential settings UI; defaults to `name` | | `description` | string | no | Help text shown to users | | `required` | boolean | no | Defaults to `true`; the plugin won't be enabled until required keys are set | | `sensitive` | boolean | no | Defaults to `true`; sensitive values are encrypted at rest and rendered as password fields | | `default` | string | no | Pre-filled value (only useful for non-sensitive options) | > [!NOTE] > The protocol does **not** model OAuth providers/scopes. If you need OAuth (Google, GitHub, Notion…), perform the flow inside your plugin's setup helper or via the platform's centralized authorization (see [Platform authorization](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/docs/authorization.md)) and surface the resulting access token as a single sensitive credential. ## How credentials reach the plugin When the user has configured the credentials, the Agent passes them inside every `invoke` request: ```json { "jsonrpc": "2.0", "method": "invoke", "id": 7, "params": { "tool": "get_weather", "arguments": { "city": "Tokyo" }, "context": { "credentials": { "WEATHER_API_KEY": "sk_live_…", "WEATHER_UNITS": "metric" } } } } ``` `params.context.credentials` is **never** visible to the LLM. Read it inside your `invoke` handler. ### Python pattern ```python def tool_get_weather(city: str, *, credentials: dict | None = None) -> dict: creds = credentials or {} # 1) Prefer Agent-injected credentials api_key = creds.get("WEATHER_API_KEY") or os.environ.get("WEATHER_API_KEY") units = creds.get("WEATHER_UNITS") or os.environ.get("WEATHER_UNITS", "metric") if not api_key: return {"success": False, "error": "WEATHER_API_KEY not configured"} # ... call the upstream API ... return {"success": True, "data": {"city": city, "units": units, "…": "…"}} def handle_invoke(req_id, params): tool = params.get("tool") args = params.get("arguments") or {} creds = (params.get("context") or {}).get("credentials") or {} if tool == "get_weather": return {"id": req_id, "result": tool_get_weather(**args, credentials=creds)} … ``` ### Node.js pattern ```javascript function invoke(tool, args, context = {}) { const creds = context.credentials || {}; if (tool === "list_messages") { const token = creds.GMAIL_ACCESS_TOKEN || process.env.GMAIL_ACCESS_TOKEN; if (!token) return { success: false, error: "GMAIL_ACCESS_TOKEN not configured" }; // … fetch with `Authorization: Bearer ${token}` return { success: true, data: { messages: [/* … */] } }; } } ``` ## Three-tier resolution The Agent merges credentials from three sources before sending them in `context.credentials`: 1. **Platform authorization** — secrets the user configured once at `/settings/authorizations`. 2. **Plugin-level credentials** — secrets entered specifically for this plugin (REST: `PUT /api/v1/executas/my/{user_executa_id}/credentials`). 3. **Environment variables** — fallback that *your plugin* implements for local development (the Agent does not export envs from credentials). ## Local development For local iteration there is no Agent running, so use environment variables and your plugin's fallback path: ```bash WEATHER_API_KEY=your_key python plugin.py GMAIL_ACCESS_TOKEN=ya29… node plugin.js ``` ## Security guidelines > [!WARNING] > - **Never log secrets** — stderr is captured into traces. > - **Never persist credentials to disk** from the plugin. The platform owns persistence. > - **Treat credentials as request-scoped.** A long-running plugin may serve multiple users; do not cache credentials in module-level globals. > - **Echo only redacted previews** in responses (e.g. `sk_…last4`) — anything you put in `result.data` is visible to the LLM. ## Reference - Full sample with multi-credential support: [`docs/authorization.md`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/docs/authorization.md). - Per-language credential plugins: [`credential_plugin.py`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/examples/python/credential_plugin.py), [`credential_plugin.js`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/examples/nodejs/credential_plugin.js), [`credential_plugin.go`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/examples/go/credential_plugin.go). - Google OAuth flow: `google_oauth_plugin.*` in each language directory. --- --- title: Platform Authorization description: Connect Google / X / GitHub / Notion / Slack once in Anna — every plugin that asks for the credential name receives it automatically. section: tools slug: executa-authorization updated: 2026-05-11 estimated_minutes: 7 --- **Platform Authorization** is Anna's central credential broker. Users connect a third-party service **once** in `/settings/authorizations`; every Executa plugin that declares the same credential name is automatically wired up at invoke time — no per-plugin OAuth flow, no API key juggling. This page explains how the broker works, which providers are first-class, and the conventions a plugin should follow to plug in for free. ![Platform Authorization: providers, resolution priority, plugin invoke](/static/images/developers/executa-authorization.svg) ## How a plugin gets credentials Every plugin lists the secrets it needs in its `describe` manifest: ```json { "credentials": [ { "name": "GMAIL_ACCESS_TOKEN", "display_name": "Gmail Access Token", "description": "Auto-injected when the user has connected Google in /settings/authorizations.", "required": true, "sensitive": true } ] } ``` When the Agent invokes a tool, it injects resolved values into `params.context.credentials` — the LLM never sees them: ```json { "method": "invoke", "params": { "tool": "send_mail", "arguments": { "to": "…", "body": "…" }, "context": { "credentials": { "GMAIL_ACCESS_TOKEN": "ya29.…" } } } } ``` See the [Credentials](/developers/tools/executa-credentials) page for the full manifest schema. ## Resolution priority For each name in `credentials[].name`, the resolver searches in this order: | # | Source | When to use | |---|---|---| | 1 | **Platform credentials** | The user has connected this provider in `/settings/authorizations`. Highest priority. | | 2 | **Plugin-level credentials** | The user pasted a value into the per-plugin settings dialog. | | 3 | **Process environment** | Local-development fallback only — present when running the binary directly outside the Agent. | The first hit wins. There is **no** tool-id allowlist: any plugin asking for `GMAIL_ACCESS_TOKEN` receives it, as long as the user has granted Google access. ## How a credential name maps to a provider Each provider in the registry declares a `credential_mapping` from **plugin-facing names** to either a placeholder (`$access_token`) or a literal field key. Examples below are taken verbatim from the platform's provider registry. ### Google (OAuth2) ```python credential_mapping = { "GOOGLE_ACCESS_TOKEN": "$access_token", "GMAIL_ACCESS_TOKEN": "$access_token", "GOOGLE_WORKSPACE_CLI_TOKEN": "$access_token", "GOOGLE_DOCS_ACCESS_TOKEN": "$access_token", "GOOGLE_SHEETS_ACCESS_TOKEN": "$access_token", } ``` `$access_token` resolves to the live OAuth access_token, refreshed transparently if expired. > [!NOTE] > YouTube scopes are **not available**: Google's authorization server rejects requests that combine YouTube scopes with other API scopes such as `drive.file` (`Error 400: invalid_request — scopes cannot be requested together`), so they were removed from the Google provider. ### X / Twitter (OAuth2 + PKCE) ```python credential_mapping = { "TWITTER_ACCESS_TOKEN": "$access_token", "X_ACCESS_TOKEN": "$access_token", } ``` ### GitHub / Notion / Slack (API key) ```python # GitHub { "GITHUB_TOKEN": "GITHUB_TOKEN", "GITHUB_ACCESS_TOKEN": "GITHUB_TOKEN" } # Notion { "NOTION_TOKEN": "NOTION_TOKEN", "NOTION_API_KEY": "NOTION_TOKEN" } # Slack { "SLACK_BOT_TOKEN": "SLACK_BOT_TOKEN", "SLACK_TOKEN": "SLACK_BOT_TOKEN" } ``` The literal-key form maps the plugin's requested name to the underlying field stored in `user_platform_credentials.credentials_encrypted`. ## Supported providers (current registry) | Provider | Auth | Recommended credential names | |---|---|---| | **Google** | OAuth2 (Gmail / Calendar / Drive / Docs scopes) | `GOOGLE_ACCESS_TOKEN`, `GMAIL_ACCESS_TOKEN`, `GOOGLE_DOCS_ACCESS_TOKEN`, `GOOGLE_SHEETS_ACCESS_TOKEN`, `GOOGLE_WORKSPACE_CLI_TOKEN` | | **X (Twitter)** | OAuth2 + PKCE (20 scopes) | `TWITTER_ACCESS_TOKEN`, `X_ACCESS_TOKEN` | | **GitHub** | API key (Personal Access Token) | `GITHUB_TOKEN`, `GITHUB_ACCESS_TOKEN` | | **Notion** | API key (Integration Token) | `NOTION_TOKEN`, `NOTION_API_KEY` | | **Slack** | API key (Bot User OAuth Token) | `SLACK_BOT_TOKEN`, `SLACK_TOKEN` | | **OpenAI** | API key (BYO) | `OPENAI_API_KEY` | | **Anthropic** | API key (BYO) | `ANTHROPIC_API_KEY` | > [!TIP] > Need to call an LLM as part of your tool? Don't ask for `OPENAI_API_KEY` — use [Sampling](/developers/tools/executa-sampling) instead. Sampling lets you call the user's preferred provider on their quota, with no API key shipped at all. ## API surface Standard endpoints under `/api/v1/platform-credentials`: | Method | Path | Purpose | |---|---|---| | `GET` | `/providers` | List all supported providers | | `GET` | `/my` | Current user's authorization status across all providers | | `GET` | `/my/{provider_id}` | Detail for one provider (scopes, email, last refresh) | | `GET` | `/oauth/{provider_id}/authorize` | Begin OAuth flow (redirect) | | `GET` | `/oauth/{provider_id}/callback` | OAuth callback handler | | `PUT` | `/api-key/{provider_id}` | Set / update an API key | | `GET` | `/api-key/{provider_id}/status` | Whether an API key is configured | | `DELETE` | `/my/{provider_id}` | Disconnect (revokes upstream where supported) | | `POST` | `/my/{provider_id}/refresh` | Force-refresh an OAuth token | Plugins should not call these directly — they are for the Anna UI. Plugins receive the resolved value via `context.credentials` as shown above. ## Security model - **Encrypted at rest.** All stored credentials are encrypted with **AES-256-GCM** using a server-side key; plaintext never reaches the database. - **LLM-isolated.** Credentials live in `params.context.credentials`, **never** in tool parameters. The LLM cannot see them and cannot leak them in conversation. - **Least privilege.** OAuth flows ask only for scopes the user explicitly approves — e.g. Gmail read-only without send. - **Auto-refresh.** OAuth `access_token`s are refreshed transparently using the stored `refresh_token` when expired. - **Revocable.** Disconnecting a provider revokes the token upstream where the provider supports it (Google, Twitter, …). ## Author best practices ### 1 · Align names with `credential_mapping` ```jsonc // ✅ Matches the registry — auto-injected for any user who has connected Google { "name": "GMAIL_ACCESS_TOKEN" } // ❌ Custom name — the platform cannot map this; user must enter it manually { "name": "MY_GMAIL_KEY" } ``` ### 2 · Read from `context` first, env as fallback ```python def send_mail(args, *, credentials: dict | None = None): creds = credentials or {} token = creds.get("GMAIL_ACCESS_TOKEN") or os.environ.get("GMAIL_ACCESS_TOKEN") if not token: return {"success": False, "error": "GMAIL_ACCESS_TOKEN not configured"} # … use token … ``` ### 3 · Never expose credentials as tool parameters ```jsonc // ✅ Hidden from the LLM { "credentials": [{ "name": "GITHUB_TOKEN" }], "tools": [{ "name": "create_issue", "parameters": [{ "name": "title", "type": "string" }] }] } // ❌ The LLM sees and can leak this { "tools": [{ "name": "create_issue", "parameters": [{ "name": "github_token", "type": "string" }, { "name": "title", "type": "string" }] }] } ``` ### 4 · Mark sensitive values ```json { "name": "API_SECRET", "sensitive": true } ``` `sensitive: true` switches the settings UI to a password input and keeps the value out of UI echoes. ### 5 · Provide clear acquisition instructions ```json { "name": "GITHUB_TOKEN", "display_name": "Personal Access Token", "description": "GitHub → Settings → Developer settings → Personal access tokens (fine-grained recommended)" } ``` ## Adding a new provider Adding a provider is a single server-side registration in the platform's provider registry — no DB schema change: ```python _register( CredentialProviderDef( provider_id="my-service", name="My Service", icon="my-service", description="My Service API", website="https://my-service.com", auth_type="api_key", api_key_fields=[ CredentialFieldDef( name="MY_SERVICE_TOKEN", display_name="API Token", description="Get one at https://my-service.com/settings/api", ), ], credential_mapping={ "MY_SERVICE_TOKEN": "MY_SERVICE_TOKEN" }, ) ) ``` Open a PR; the new tile shows up at `/settings/authorizations` automatically. ## See also - [Credentials](/developers/tools/executa-credentials) — manifest schema for `credentials[]` - [Sampling](/developers/tools/executa-sampling) — for LLM access without an API key - [Common Pitfalls](/developers/tools/executa-pitfalls) --- --- title: Sampling — LLM Calls Without an API Key description: Let your plugin ask the host to perform an LLM completion on the user's behalf, with billing and model selection handled by Anna. section: tools slug: executa-sampling updated: 2026-06-10 estimated_minutes: 11 --- Sampling lets your plugin invoke an LLM **on the user's behalf** without shipping your own API key, picking a model, or metering quota. The plugin describes the completion in protocol-neutral terms; Anna routes it through the user's preferred provider, charges the user's plan, and returns the result. It's the Executa equivalent of MCP's [`sampling/createMessage`][mcp]. Available from protocol **v2** onward. > **Need multi-turn agent runs with tool calls?** Sampling is one request → one response. For stateful, tool-using sessions (and parity with iframe anna-apps), see [Agent Sessions](/developers/tools/executa-agent). [mcp]: https://modelcontextprotocol.io/ ![Sampling reverse RPC flow](/static/images/developers/executa-sampling.svg) ## Why sampling exists Without sampling, every plugin that wants to summarize / classify / plan would need to: - ship its own API key (security & compliance liability), - pick a model and chase deprecations, - meter usage it cannot see (the user's plan, quotas, billing). Sampling collapses all three into one capability advertised by the host. ## Three pre-conditions End-to-end sampling needs **all** of the following: 1. **v2 negotiation.** The host sends `initialize`; the plugin replies with the same `protocolVersion: "2.0"` and lists `capabilities.sampling = {}`. See [Lifecycle](/developers/tools/executa-lifecycle#v2-capability-handshake). 2. **Manifest declaration.** The plugin's `describe` manifest includes `host_capabilities: ["llm.sample"]`. The Anna App publish validator rejects unknown capability strings. 3. **User grant.** The end user enabled sampling for this Executa in their Anna Admin panel. The grant carries `maxCalls` and `maxTokensTotal` per-invoke caps. If any condition is missing, the host returns `-32008 SAMPLING_NOT_NEGOTIATED` and your reverse RPC is rejected before reaching a model. ## Wire protocol After v2 is live, every `invoke` request also carries `invoke_id` and `sampling_token` inside `params.context` — see [Lifecycle](/developers/tools/executa-lifecycle#per-invoke-context-injection). While processing the invoke, your plugin **emits a reverse JSON-RPC request on stdout**: ```json { "jsonrpc": "2.0", "id": "550e8400-e29b-41d4-a716-446655440000", "method": "sampling/createMessage", "params": { "messages": [ { "role": "user", "content": { "type": "text", "text": "Summarize:\n…" } } ], "maxTokens": 400, "systemPrompt": "You are a concise assistant.", "temperature": 0.3, "stopSequences": ["\n\n###"], "modelPreferences": { "hints": [{ "name": "claude-sonnet" }], "costPriority": 0.4, "speedPriority": 0.4, "intelligencePriority": 0.2 }, "includeContext": "none", "metadata": { "executa_invoke_id": "" } } } ``` | Field | Required | Notes | |---|---|---| | `messages` | yes | Non-empty array, max **64** entries. Each entry is `{role, content:{type:"text", text}}`. Roles: `user`, `assistant`, `system`. | | `maxTokens` | yes | Positive integer, capped at host's `maxTokensPerCall` (currently **8 192**). | | `systemPrompt` | no | Plain text. | | `temperature` | no | Number. | | `stopSequences` | no | Array of strings. | | `modelPreferences` | no | See [Model selection](#model-selection-precedence). Omit to use the user's saved preference. | | `includeContext` | no | **Phase 1 only accepts `"none"`.** Plugins cannot read the conversation context. | | `metadata` | no | Free dict. Convention: include `executa_invoke_id` for trace stitching. | | `responseFormat` | no | Structured-output constraint — `{"type":"json_object"}` or `{"type":"json_schema", "json_schema":{…}}`. See [Structured output](#structured-output-responseformat). | | `onUnsupported` | no | What to do when the selected model can't honour `json_schema`: `"error"` (default), `"json_object"`, or `"text"`. | The host replies on stdin (the same channel) with the result: ```json { "jsonrpc": "2.0", "id": "550e8400-e29b-41d4-a716-446655440000", "result": { "role": "assistant", "content": { "type": "text", "text": "…" }, "model": "claude-3-5-sonnet-20241022", "stopReason": "endTurn", "usage": { "inputTokens": 312, "outputTokens": 187, "totalTokens": 499 }, "_meta": { "provider": "anthropic", "latencyMs": 1432 } } } ``` > [!IMPORTANT] > The same stdin reader receives **both** Agent-initiated requests and host responses to your reverse RPCs. Distinguish them by the presence of a `method` field — responses have only `id` + `result|error`. The official SDKs do this for you. ## Model selection precedence When the plugin sends `modelPreferences`, Nexus resolves the model in this order: ``` 1. hints[*].name → first active model whose model_name CONTAINS the hint (case-insensitive substring). With costPriority > 0, ties break to cheapest. 2. (no hints / no match) → user.settings.preferred_model 3. (preferred_model unset) → default provider's cheapest active model ``` > [!TIP] > Plugins should normally **omit `modelPreferences` entirely** so the user's saved preference applies. Hints are for tools whose quality strictly requires a particular model family. ## Structured output (`responseFormat`) When your tool needs machine-readable output (extraction, classification, anything you'll `JSON.parse`), prompt engineering alone is fragile. `responseFormat` pushes the constraint down to the provider's decoding layer. Two levels: **L1 — JSON mode** (`json_object`). Guarantees syntactically valid JSON, no particular shape. Broadly compatible — works with any OpenAI-compatible model and is **not** capability-gated: ```json { "responseFormat": { "type": "json_object" } } ``` > [!NOTE] > With `json_object` the provider requires the word "JSON" to appear in your prompt — keep an instruction like *"Reply with a JSON object containing …"* in the message or system prompt. **L2 — strict JSON Schema** (`json_schema`). The model output conforms to your schema (provider-enforced constrained decoding): ```json { "responseFormat": { "type": "json_schema", "json_schema": { "name": "summary_analysis", "strict": true, "schema": { "type": "object", "properties": { "summary": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative"] } }, "required": ["summary", "keywords", "sentiment"], "additionalProperties": false } } }, "onUnsupported": "json_object" } ``` ### Capability gating & downgrade Not every model supports strict schemas. `json_schema` is gated on the selected model's `supports_structured_output` flag (set by the Anna admin per model; missing = unsupported). `json_object` is never gated. When the model can't honour `json_schema`, `onUnsupported` decides: | `onUnsupported` | Behaviour | |---|---| | `"error"` *(default)* | Request fails with `-32010 SAMPLING_UNSUPPORTED_RESPONSE_FORMAT`; `error.data` carries `{requested, modelName}`. | | `"json_object"` | Downgrade to L1 JSON mode. | | `"text"` | Drop the constraint entirely — plain text generation. | The host advertises support in its `initialize` request: `capabilities.sampling.responseFormat: ["json_object", "json_schema"]`. Hosts older than this feature simply ignore the params — design accordingly (or check the capability list). ### Schema hard limits Validated twice (locally by the Matrix agent for fast failure, then authoritatively by Nexus). Violations are `-32004 SAMPLING_INVALID_REQUEST`: | Limit | Value | |---|---| | Serialized schema size | ≤ **32 KB** | | Nesting depth | ≤ **8** | | Total nodes (objects + arrays + leaves) | ≤ **512** | | `json_schema.name` | must match `^[a-zA-Z0-9_-]{1,64}$` | ### Reading the result `content.text` **stays a string** — parse it yourself. When the request carried `responseFormat`, the response `_meta` gains an informational block: ```json "_meta": { "responseFormat": { "requested": "json_schema", "applied": "json_object", "structuredValid": true, "downgraded": true } } ``` - `applied` — what was actually sent to the provider (`null` if dropped via `"text"`). - `structuredValid` — whether `content.text` parsed as JSON (informational only; **always run your own `json.loads` with a fallback**). - `downgraded` — `true` when `applied != requested`. ```python result = await sampling.create_message( messages=[...], max_tokens=512, response_format={ "type": "json_schema", "json_schema": {"name": "summary_analysis", "strict": True, "schema": SCHEMA}, }, on_unsupported="json_object", # degrade gracefully instead of -32010 ) try: data = json.loads(result["content"]["text"]) except json.JSONDecodeError: data = None # even with responseFormat, the final parse is yours ``` See the runnable [`summarize_structured` tool in sampling-summarizer](https://github.com/whtcjdtc2007/anna-executa-examples/tree/main/examples/python/sampling-summarizer) for the full pattern. ### Testing locally The dev harness validates `responseFormat` with the same rules as production and synthesises `_meta.responseFormat` in mock mode. To exercise your `onUnsupported` branches without a real model, drive the harness from a mock fixture whose responses omit `json_schema` support: ```bash anna-app executa dev --dir ./my-plugin --mock-sampling ./sampling-fixture.jsonl ``` ## Per-invoke caps | Cap | Default | Where enforced | |---|---|---| | `maxTokens` per call | **8 192** | `DEFAULT_SAMPLING_MAX_TOKENS_PER_CALL` (host) | | Calls per `invoke_id` | **8** | `sampling_grant.maxCalls`, host-capped at 8 | | Total tokens per `invoke_id` | **32 000** | `sampling_grant.maxTokensTotal`, host-capped at 32 000 | | `sampling_token` TTL | **600 s** | JWT `aud=executa-sampling` | | `includeContext` values | only `"none"` | host rejects others as `-32004 SAMPLING_INVALID_REQUEST` | Both call-count and total-token caps are **terminal** within the same `invoke_id` — your plugin cannot retry past them; it must shrink the workload or exit gracefully. ## Error codes All sampling errors come back as JSON-RPC errors with stable codes: | Code | Name | Meaning | |---|---|---| | `-32001` | `SAMPLING_NOT_GRANTED` | User has not enabled sampling for this Executa. | | `-32002` | `SAMPLING_QUOTA_EXCEEDED` | User account quota exhausted. | | `-32003` | `SAMPLING_PROVIDER_ERROR` | Upstream LLM provider failed. | | `-32004` | `SAMPLING_INVALID_REQUEST` | Malformed params (e.g. `includeContext != "none"`, `messages` empty, `responseFormat` schema over limits). | | `-32005` | `SAMPLING_TIMEOUT` | The completion did not finish in time. | | `-32006` | `SAMPLING_MAX_CALLS_EXCEEDED` | Per-invoke call-count cap reached. | | `-32007` | `SAMPLING_MAX_TOKENS_EXCEEDED` | Per-invoke cumulative token cap reached. | | `-32008` | `SAMPLING_NOT_NEGOTIATED` | Host didn't negotiate v2, or manifest missing `host_capabilities: ["llm.sample"]`. | | `-32009` | `SAMPLING_USER_DENIED` | User explicitly rejected this sampling request. | | `-32010` | `SAMPLING_UNSUPPORTED_RESPONSE_FORMAT` | Model can't honour the requested `responseFormat` and `onUnsupported` is `"error"`. `data` = `{requested, modelName}`. | The structured `error.data.errorCode` carries the symbolic name above for easy switch / match. ## Minimal Python example ```python import json, sys, uuid, threading, queue # Two queues — one for Agent requests, one for our own reverse-RPC responses. agent_requests: queue.Queue = queue.Queue() host_responses: dict[str, queue.Queue] = {} def reader(): for line in sys.stdin: msg = json.loads(line) if "method" in msg: # Agent → us agent_requests.put(msg) else: # response to a reverse RPC q = host_responses.pop(msg["id"], None) if q is not None: q.put(msg) threading.Thread(target=reader, daemon=True).start() def send(obj): sys.stdout.write(json.dumps(obj) + "\n"); sys.stdout.flush() def sample(invoke_id: str, prompt: str, *, max_tokens: int = 400) -> str: rid = str(uuid.uuid4()) q: queue.Queue = queue.Queue() host_responses[rid] = q send({ "jsonrpc": "2.0", "id": rid, "method": "sampling/createMessage", "params": { "messages": [{ "role": "user", "content": { "type": "text", "text": prompt } }], "maxTokens": max_tokens, "includeContext": "none", "metadata": { "executa_invoke_id": invoke_id }, }, }) resp = q.get(timeout=90) if "error" in resp: raise RuntimeError(resp["error"]) return resp["result"]["content"]["text"] while True: req = agent_requests.get() if req["method"] == "describe": send({"jsonrpc": "2.0", "id": req["id"], "result": { "name": "summarizer", "version": "0.1.0", "host_capabilities": ["llm.sample"], "tools": [{"name": "summarize", "description": "Summarize text", "parameters": [{"name": "text", "type": "string", "required": True}]}], }}) elif req["method"] == "initialize": send({"jsonrpc": "2.0", "id": req["id"], "result": { "protocolVersion": "2.0", "serverInfo": {"name": "summarizer", "version": "0.1.0"}, "capabilities": {"sampling": {}}, }}) elif req["method"] == "invoke": ctx = (req["params"].get("context") or {}) text = req["params"]["arguments"]["text"] try: summary = sample(ctx["invoke_id"], f"Summarize:\n{text}") send({"jsonrpc": "2.0", "id": req["id"], "result": {"success": True, "data": {"summary": summary}}}) except Exception as e: send({"jsonrpc": "2.0", "id": req["id"], "result": {"success": False, "error": str(e)}}) ``` For a polished version with retries, see the upstream [`examples/python/sampling-summarizer/`](https://github.com/whtcjdtc2007/anna-executa-examples/tree/main/examples/python/sampling-summarizer). ## SDK summary | Language | Entry point | |---|---| | Python | [`executa_sdk.SamplingClient.create_message`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/sdk/python/executa_sdk/sampling.py) | | Node.js | [`new SamplingClient().createMessage()`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/sdk/nodejs/sampling.js) | | Go | [`sampling.New(nil).CreateMessage()`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/sdk/go/sampling/sampling.go) | All three SDKs ship a single-reader / multi-writer dispatcher so you don't have to wire it yourself, and all three expose `responseFormat` / `onUnsupported` (Python: `response_format=` / `on_unsupported=` kwargs; Node: request options; Go: `ResponseFormat` / `OnUnsupported` struct fields). ## Common pitfalls - **Don't `process.exit()` after writing the invoke result.** Sampling responses arrive asynchronously; exiting early drops in-flight reverse RPCs. Keep the long-running stdin loop. ([Pitfall #1](/developers/tools/executa-pitfalls#1-plugin-process-exits-after-one-request)) - **Always echo `invoke_id` in `metadata`.** Nexus uses it to attribute usage and enforce per-invoke caps. - **Don't ship API keys.** If you reach for `OPENAI_API_KEY` from env, you almost certainly want sampling instead. - **Treat `SAMPLING_MAX_TOKENS_EXCEEDED` and `SAMPLING_USER_DENIED` as terminal** — not retryable inside the same invoke. - **Don't trust `structuredValid` as a parse.** It's informational; always `json.loads` with a fallback — and prefer `onUnsupported: "json_object"` over the default `"error"` unless your tool is useless without strict schemas. ## See also - [Agent Sessions](/developers/tools/executa-agent) — multi-turn / tool-using extension of this same wire pattern - [Lifecycle & Capability Negotiation](/developers/tools/executa-lifecycle) - [Protocol Specification](/developers/tools/executa-protocol) - [Persistent Storage](/developers/tools/executa-storage) — sister reverse-RPC capability - [Common Pitfalls](/developers/tools/executa-pitfalls#8-sampling-host_capabilities-not-declared) --- --- title: Agent Sessions — Multi-turn Tool-using Runs description: Drive stateful, tool-using Anna Agent sessions from a stdio plugin via reverse JSON-RPC, with the same surface area as in-iframe anna-apps. section: tools slug: executa-agent updated: 2026-05-15 estimated_minutes: 8 --- Sampling ([previous chapter](/developers/tools/executa-sampling)) is **one request → one response**. Agent sessions extend that pattern to **persistent threads, host-executed tools, streaming frames, and cancellation** — the same things an iframe `anna-app` can already do today. The goal is **plugin/app parity**: a Python plugin and a TypeScript anna-app should be drop-in interchangeable for the same agentic workload. Available from protocol **v2.1** onward. ## Two API levels | Level | Method | Stateful? | Tool calls? | Use case | |------:|-----------------------|:---------:|:-----------:|----------------------------------------| | L1 | `agent/complete` | no | no | one-shot completion (sugar over sampling) | | L2 | `agent/session.*` | yes | yes | multi-turn agent runs | L1 is a convenience wrapper — if you only need single-turn text, prefer plain [sampling](/developers/tools/executa-sampling). L2 is what unlocks parity with anna-apps. ## Pre-conditions End-to-end agent sessions need **all** of: 1. **v2 negotiation.** Same handshake as sampling — see [Lifecycle](/developers/tools/executa-lifecycle#v2-capability-handshake). 2. **Manifest declares both grants:** ```json { "host_capabilities": ["llm.sample", "llm.agent.auto"] } ``` `llm.sample` unlocks L1 (`agent/complete`); `llm.agent.auto` unlocks L2 (`agent/session.*`). Without `llm.agent.auto` the host returns `-32041 AGENT_NOT_GRANTED`. 3. **User grant.** The end user enabled the agent capability for this Executa in Anna Admin. The grant carries the same per-invoke token caps as sampling, plus a `granted_tools` whitelist. ## Auth chain (no bearer token in the plugin) Just like sampling, every `invoke` carries a `sampling_token` in `params.context`. The host uses **that token** to mint an `app_session_token` against nexus's `POST /copilot/app/sessions/from_sampling` endpoint, then **caches the token in-process** keyed by `(user_id, plugin_name)`. The plugin only ever sees opaque `app_session_uuid`s. ``` plugin matrix host nexus │ │ │ │── agent/session.create ────►│ │ │ (sampling_token in ctx) │── POST /sessions/ │ │ │ from_sampling │ │ │ Bearer = sampling_token │ │ │◄── {app_session_uuid, token, │ │ │ thread_id, ...} │ │ │ (host caches token) │ │◄── {app_session_uuid, ...} ─│ (token stripped from result)│ ``` This is **symmetric to sampling** — the plugin is never trusted with a long-TTL credential. The cache is bounded (LRU, ~4096 entries) and an `agent/session.delete` immediately evicts the entry. ## Reverse RPC methods | Method | Purpose | |-------------------------|------------------------------------------------------| | `agent/session.create` | Mint an app session, return `{app_session_uuid, thread_id, agent_submode, granted_tools}` | | `agent/session.run` | Send a user message, receive an array of frames | | `agent/session.cancel` | Abort an in-flight `run_id` | | `agent/session.history` | (deferred — returns `[]` until v2.2) | | `agent/session.delete` | Idempotent teardown; evicts the cached token | | `agent/complete` | Single-turn completion (L1) | ### `agent/session.create` params | Field | Required | Notes | |-------------------|:--------:|-----------------------------------------------------------------------| | `kind` | yes | `"agent"` (multi-turn agent) or `"fixed"` (single-tool agent) | | `agent_submode` | for `kind=agent` | `"auto"` (LLM picks tools) only in v2.1 | | `fixed_client_id` | for `kind=fixed` | Tool's `client_id` to single-call against | | `label` | no | Free-text trace label | ### Frame shapes (from `agent/session.run`) ```json { "event": "delta", "text": "..." } { "event": "tool_call", "name": "search_web", "args": {...}, "call_id": "..." } { "event": "tool_result", "call_id": "...", "ok": true, "data": {...} } { "event": "final", "text": "...", "usage": {...} } ``` ## Streaming choice — buffered v2 `agent/session.run` is **buffered** in v2.1: the host accumulates SSE frames until `done=true`, then returns the whole array in a single JSON-RPC response. The SDK exposes them as `async for frame in session.run(...)` so business code does not change when the host switches to true real-time streaming in v2.2. Hard cap: **4096 frames per run**. Exceeding returns `-32047 AGENT_RUN_TOO_LARGE`. ## Error codes | Code | Name | Meaning | |----------|-----------------------------------|------------------------------------------------| | `-32041` | `AGENT_NOT_GRANTED` | Manifest missing `llm.agent.auto` | | `-32042` | `AGENT_INVALID_SUBMODE` | `kind=agent` without a valid submode | | `-32043` | `AGENT_FIXED_REQUIRES_CLIENT_ID` | `kind=fixed` without `fixed_client_id` | | `-32044` | `AGENT_UNKNOWN_SESSION` | `app_session_uuid` not in the host cache | | `-32045` | `AGENT_INVALID_UUID` | uuid not owned by `(this user, this plugin)` | | `-32046` | `AGENT_NEXUS_ERROR` | Upstream nexus failure | | `-32047` | `AGENT_RUN_TOO_LARGE` | Run exceeded the 4096-frame buffer cap | | `-32048` | `AGENT_TOOL_NOT_GRANTED` | Requested a tool not in `granted_tools` | `AgentError` shares its base class with `SamplingError` in the Python / Node SDKs, so a single `except SamplingError` covers both surfaces. ## Minimal Python example ```python import sys from executa_sdk import ( SamplingClient, AgentSessionClient, AgentError, ) agent = AgentSessionClient() sampling = SamplingClient() # share the stdout writer agent.attach_writer(_write_frame) sampling.attach_writer(_write_frame) # multi-turn (L2) session = await agent.create(kind="agent", agent_submode="auto") async for frame in session.run("Plan my week."): if frame["event"] == "delta": sys.stderr.write(frame["text"]) elif frame["event"] == "tool_call": ... await session.delete() # single-turn (L1) — sugar over sampling text = await agent.complete(prompt="Summarize: ...", max_tokens=200) ``` In your stdin dispatch loop, route responses by trying both clients in order: ```python if not agent.dispatch_response(msg): sampling.dispatch_response(msg) ``` For a polished version (manifest, grant flags, both tools `ask_agent` and `ask_complete`), see the upstream [`examples/python/executa-agent-demo/`](https://github.com/whtcjdtc2007/anna-executa-examples/tree/main/examples/python/executa-agent-demo). ## Symmetry with anna-app Same lifecycle, same frame shapes, same grant gating — only the transport differs (postMessage in iframe, stdio JSON-RPC in plugin): ```ts // inside an anna-app iframe const session = await anna.agent.session({ submode: "auto" }); for await (const frame of session.run("Plan my week.")) { if (frame.event === "delta") process.stdout.write(frame.text); } await session.delete(); ``` ## SDK summary | Language | Entry point | |----------|---------------------------------------------------------------------------------------------------------------------------------------------------| | Python | [`executa_sdk.AgentSessionClient`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/sdk/python/executa_sdk/agent.py) | | Node.js | _(planned for v2.2)_ | | Go | _(planned for v2.2)_ | ## Common pitfalls - **Always declare both `llm.sample` and `llm.agent.auto`.** L1 (`agent/complete`) is gated by `llm.sample`; L2 by `llm.agent.auto`. Missing either gives `-32041` with no further hint. - **Never persist the `app_session_uuid` across plugin process restarts.** The host's token cache is in-process; a restart invalidates every uuid → next call returns `-32044 AGENT_UNKNOWN_SESSION`. Re-create on demand. - **Don't `process.exit()` between `create` and `delete`.** Same rule as sampling — the dispatch loop must stay alive. - **Treat `AGENT_RUN_TOO_LARGE` as terminal.** Shrink the workload (lower `max_tokens`, narrower toolset) rather than retrying. ## See also - [Sampling — LLM Calls Without an API Key](/developers/tools/executa-sampling) — the L1 wire pattern this builds on - [Lifecycle & Capability Negotiation](/developers/tools/executa-lifecycle) - [Persistent Storage](/developers/tools/executa-storage) — sister reverse-RPC capability - [App-Side LLM & Agent API](/developers/apps/llm-and-agent) — the same surface from the iframe-app side (parity reference) --- --- title: Persistent Storage (APS) description: Per-user durable KV + object store hosted by Anna — no cloud account, no DB, quota and access control enforced by the host. section: tools slug: executa-storage updated: 2026-08-25 estimated_minutes: 9 --- **Anna Persistent Storage (APS)** gives an Executa plugin a small, durable, per-user **key/value + object** store hosted by Anna. There is no cloud account to provision, no credentials to ship, and no DB to run — quota and access control are enforced by Nexus. Available from protocol **v2** onward. ![APS architecture: scopes, methods, REST mapping](/static/images/developers/executa-storage.svg) ## When to use APS | Want to… | Use | |---|---| | Remember "where did the last run leave off" between invokes | KV (`storage/*`) | | Cache an expensive computation (OCR, embeddings, derived JSON) | KV with `ttl_seconds` | | Save a generated PDF / image / CSV the assistant can hand back to the user | Objects (`files/*`) | | Drop a file into the **end user's drive** so other plugins can find it | Objects (`files/*` with `scope: "user"`) | If your data is bigger than a few KB or is binary, prefer object storage — KV values are JSON and capped per-write. ## Three pre-conditions End-to-end APS access requires **all** of: 1. **v2 negotiation.** Plugin echoes `protocolVersion: "2.0"` and exposes the storage capability in its `initialize` response (`capabilities.storage = {}` is sufficient). 2. **Manifest declaration.** `host_capabilities` declares the APS surface the plugin uses: `aps.kv` for the KV API (`storage/*`), `aps.files` for the object/file API (`files/*`). These are the strings that make the host mint a plugin-side `storage_token`. 3. **User grant.** The end user enabled storage for this Executa in their Anna Admin panel. The grant pins `allowed_scopes`, `quotaBytes`, and `objectMaxBytes`. If anything is missing, Nexus rejects the reverse RPC with `-32021 STORAGE_NOT_GRANTED`. > [!WARNING] > `storage.user`, `storage.app`, and `storage.tool` are **not** valid `host_capabilities` values — the runtime never accepts them. The full accepted allow-list (shared with the [App Manifest](/developers/apps/app-manifest)) is: > > | Capability | Grants | > |---|---| > | `aps.kv` | Plugin: KV reverse RPCs (`storage/*`). App Host API: legacy alias for self-owned `scope=app` read + write (not deprecated) | > | `aps.files` | Plugin: object/file reverse RPCs (`files/*`) | > | `aps.scope.user.read` / `aps.scope.user.write` | App Host API: read / write APS keys in `scope=user` | > | `aps.scope.tool.read` / `aps.scope.tool.write` | App Host API: read / write `scope=tool` (per-executa cache) | > | `aps.scope.app.read` / `aps.scope.app.write` | App Host API: read / write **another** app's `scope=app` (requires `owner`) | > | `aps.scope.admin` | Full (scope, owner) matrix — system apps only | > [!NOTE] > When the Executa ships inside an Anna App, declare `host_capabilities` in **both** places: the top-level entry in `manifest.json` drives app-side validation and packaging; the entry in the Executa's `describe` manifest drives server-side `storage_token` issuance. For a standalone Executa published outside an App, only the describe manifest applies. (Capabilities placed under `ui.host_api` fail schema validation — `additionalProperties: false`.) ## Scopes | Scope | Owner | Visibility | |---|---|---| | `user` | The end user | Their own dashboards & every plugin they grant. | | `app` | The Anna App bundle | Shared across the same app for one user. **App-side Host API only** — not reachable from plugin reverse RPCs. | | `tool` | The Executa plugin | Strictly local to (user × executa). | > [!WARNING] > Plugin-side `storage_token`s are issued for `scope='user'` and `scope='tool'` **only** — the platform grant pins `allowedScopes: ["user", "tool"]`. Calling any `storage/*` / `files/*` method with `scope: "app"` from a plugin fails with `storage_token does not permit scope='app'; allowed=['tool', 'user']`. The `app` scope belongs to the App-side iframe [Host API](/developers/apps/app-ui-host-api) (where `aps.kv` grants self-owned `scope=app` access). For per-user app data from a plugin, use `scope: "user"` with the user grant in place. Always pass `scope` explicitly on every call — client and host defaults differ. To write into the end user's drive, pass `scope: "user"` on the same `files/*` methods — the per-scope grant is enforced by the `storage_token`'s `allowed_scopes` claim, not by the method name. > [!TIP] > Prefer `tool` for transient state. Ask for `user` only when the user obviously benefits from cross-tool reuse — e.g. saving a generated PDF into their **My Files**. ## Wire protocol After v2 is live, every `invoke` request also carries a short-lived `storage_token` inside `params.context` (see [Lifecycle](/developers/tools/executa-lifecycle#per-invoke-context-injection)). Reverse RPCs go out on the same stdin/stdout channel as sampling: ```json { "jsonrpc": "2.0", "id": 12, "method": "storage/set", "params": { "scope": "tool", "key": "lastRun/cursor", "value": { "page": 7, "ts": "2026-05-01T11:22:33Z" }, "ttl_seconds": 86400 } } ``` The Agent forwards every storage RPC over HTTP to Nexus's `/api/v1/storage/*` endpoints, attaching the `storage_token` as `Authorization: Bearer …`. ### Methods | Method | Purpose | Body / query | |---|---|---| | `storage/get` | Read one JSON value by key | `key`, `scope` | | `storage/set` | Write one JSON value | `key`, `value`, `ttl_seconds?`, `if_match?` | | `storage/delete` | Soft-delete a key | `key`, `scope` | | `storage/list` | List keys by prefix (paged) | `prefix`, `cursor?`, `limit?` | | `files/upload_begin` | Mint a presigned PUT URL | `path`, `content_type`, `size_bytes` | | `files/upload_complete` | Commit after PUT succeeds | `path`, `etag` | | `files/download_url` | Mint a time-limited GET URL | `path` | | `files/list` | List objects by prefix | `prefix`, `cursor?` | | `files/delete` | Soft-delete an object | `path` | Pass `scope: "user"` on any `files/*` method to target the user drive; the request is authorised iff the `storage_token`'s `allowed_scopes` claim includes `user`. ### Result shapes | Method | Success result | |---|---| | `storage/get` (hit) | `{"value": …, "exists": true, "etag": "…"}` | | `storage/get` (miss) | `{"value": null, "exists": false, "etag": null}` | | `storage/set` | `{"etag": "…", "size_bytes": …}` | | `storage/delete` | `{"deleted": true}` | | `storage/list` | `{"items": [...], "next_cursor": …}` | | `files/upload_begin` | `{"presigned_url": "https://…", "fields": {…}, "expires_at": …}` | | `files/upload_complete` | `{"path": "…", "etag": "…", "size_bytes": …}` | | `files/download_url` | `{"url": "https://…", "expires_at": …}` | > [!IMPORTANT] > The Agent normalises 404s on `storage/get` into `{"value": null, "exists": false}` so you can use the documented `cur["exists"]` pattern. **Do not** assume the value is missing just because `cur["value"]` is falsy — it may be a legitimate `0`, `""`, `false`, or `[]`. ## Optimistic concurrency Always pass `if_match` (the previous `etag`) on overwrite to avoid lost updates: ```python cur = await rpc("storage/get", { "scope": "tool", "key": "notes/123" }) notes = cur["value"] if cur["exists"] else [] notes.append({ "ts": now(), "text": new_text }) await rpc("storage/set", { "scope": "tool", "key": "notes/123", "value": notes, "if_match": cur.get("etag"), # missing on first write — that's fine }) ``` A failed precondition surfaces as `-32023 PRECONDITION_FAILED`; re-read and retry. ## Worked example — caching an OCR result ```python import hashlib, json, sys, uuid, queue, threading # (single-reader / dispatch boilerplate omitted — see Sampling page) def cache_ocr(invoke_id: str, image_bytes: bytes) -> str: sha = hashlib.sha256(image_bytes).hexdigest() cur = rpc("storage/get", {"scope": "tool", "key": f"ocr/{sha}"}) if cur["exists"]: return cur["value"]["text"] text = run_ocr(image_bytes) # expensive rpc("storage/set", { "scope": "tool", "key": f"ocr/{sha}", "value": { "text": text, "ranAt": now_iso() }, "ttl_seconds": 30 * 24 * 3600, # 30 days }) return text ``` For a runnable plugin, see the upstream [`examples/python/storage-notebook/`](https://github.com/whtcjdtc2007/anna-executa-examples/tree/main/examples/python/storage-notebook). ## Object uploads — two-step Direct PUT to R2 is the recommended path for any binary or anything bigger than a few KB: ```text ① files/upload_begin ──▶ { presigned_url, fields, expires_at } ② HTTP PUT to presigned_url with the bytes ③ files/upload_complete ──▶ { path, etag, size_bytes } ``` The two-step shape lets the bytes go directly to R2 without round-tripping through the Agent's stdio. Skip step ③ and the object is silently garbage-collected after a few minutes. ## Quota & limits | Limit | Default | Where set | |---|---|---| | Per-user total bytes | **5 GB** | `PlanMetric.storage_quota_bytes`, plan-overridable | | Single KV value | **64 KB** (advisory; hard cap configured per env) | `STORAGE_ERR_VALUE_TOO_LARGE` if exceeded | | Single object | per-grant `objectMaxBytes` | host returns `-32024 QUOTA_EXCEEDED` | | Per-invoke storage RPCs | **200** (default `max_calls` in `storage_token`) | `STORAGE_ERR_RATE_LIMITED` if exceeded | | `storage_token` TTL | **600 s** | JWT `aud=aps-storage` | Treat `RATE_LIMITED` and `QUOTA_EXCEEDED` as **non-retryable** within the same invocation; treat `UPSTREAM_ERROR` as retryable with backoff. ## Error codes | Code | Name | Meaning | |---|---|---| | `-32021` | `STORAGE_NOT_GRANTED` | Missing token, missing capability, or scope not allowed. | | `-32022` | `NOT_FOUND` | Key / path does not exist (only surfaced where it's not normalised away). | | `-32023` | `PRECONDITION_FAILED` | `if_match` etag mismatch. | | `-32024` | `QUOTA_EXCEEDED` | Plan storage quota exhausted. | | `-32025` | `VALUE_TOO_LARGE` | KV value above per-call ceiling. | | `-32026` | `RATE_LIMITED` | Per-invoke RPC budget exhausted. | | `-32027` | `INVALID_PATH` | Reserved / out-of-bucket path. | | `-32028` | `INVALID_REQUEST` | Missing required field, wrong type. | | `-32029` | `UPSTREAM_ERROR` | Network / 5xx from Nexus REST. Also surfaces Nexus 403s — e.g. `storage_token does not permit scope='app'; allowed=['tool', 'user']` when a plugin requests the App-side `app` scope. | ## Built-in user-storage tools For LangChain agents, Nexus auto-registers six high-level wrappers under the `user_storage_*` namespace: ``` user_storage_get / set / delete / list / user_storage_files_save_text / user_storage_files_get_url ``` The agent never sees the raw RPC; the tool wraps each call in a soft **5-write / 20-read per-invocation** budget and returns the same JSON envelope as above. Users can disable these per-account via `UserSettings.disable_user_storage_tools`. ## Best practices 1. **Default to `tool` scope.** Use `user` only when the data is genuinely user-owned. (`app` scope is not available to plugins — it belongs to the App-side Host API.) 2. **Encode metadata in the key, not the value.** `notes/{noteId}` is searchable via `storage/list`; embedded JSON fields are not. 3. **Keep individual KV values small** — anything bigger than a few KB belongs in objects. 4. **Always pass `if_match` on overwrite.** Lost updates are silent and miserable to debug. 5. **Set TTLs on cache-shaped data.** Quota is a finite resource shared with the user's other plugins. 6. **Treat the response as authoritative.** Always read back the `etag` after a write — never assume your client already knows it. ## See also - [Lifecycle & Capability Negotiation](/developers/tools/executa-lifecycle) - [Sampling](/developers/tools/executa-sampling) — sister reverse-RPC capability - [Protocol Specification](/developers/tools/executa-protocol) - [Common Pitfalls](/developers/tools/executa-pitfalls) --- --- title: Binary Distribution description: Ship one binary per platform — single-file or full multi-file bundle. section: tools slug: executa-binary updated: 2026-07-07 estimated_minutes: 10 --- For end users, "install Python first" is a deal-breaker. Ship **one binary per platform** and the install becomes a single download. The Anna Agent has built-in `binary` distribution support that fetches the right asset for the current host — for both *single-file* binaries and *multi-file* bundles (binary + bundled `.so`/`.dylib` + data dirs). ## Single-file vs multi-file at a glance | Scenario | Use | Archive shape | |---|---|---| | One self-contained binary (Go, Rust, PyInstaller `--onefile`, Node `pkg`) | Single-file | Raw binary, **or** `.tar.gz` / `.zip` containing the executable + `manifest.json` (recommended) | | Binary + bundled libs / data / sub-tools | Multi-file | `.tar.gz` / `.zip` with `bin/` + `lib/` + `data/` + `manifest.json` declaring the entrypoint | Multi-file is required whenever your binary needs to find its own bundled friends at runtime — PyInstaller `--onedir`, Electron-style apps, anything with native side-by-side `.so` / `.dylib` / DLLs. > [!TIP] > Even for single-file binaries we recommend the `.tar.gz` + `manifest.json` form rather than uploading a raw binary. The manifest pins your `name`, declares `permissions`, and travels with the binary so future re-publishes can't drift. ## Build matrix | Language | Tool | Default output | |---|---|---| | Python | [PyInstaller](https://pyinstaller.org) `--onefile` or `--onedir` | Single executable, or directory of executable + libs | | Node.js | [`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg) (or Node 20+ SEA) | Single executable per platform | | Go | `go build` | Native binary, no extras | | Rust | `cargo build --release` | Native binary, no extras | ## Platform keys The Agent auto-detects the host as `"{os}-{arch}"` (lowercase, normalized). Use these keys for your asset names and `binary_urls` map: | Host | Platform key | |---|---| | macOS Apple Silicon | `darwin-arm64` | | macOS Intel | `darwin-x86_64` | | Linux x86_64 | `linux-x86_64` | | Linux ARM64 | `linux-aarch64` | | Linux ARMv7 | `linux-armv7l` | | Windows x86_64 | `windows-x86_64` | | Windows ARM64 | `windows-arm64` | The Agent applies aliases so `amd64`/`x64` are folded into `x86_64` automatically. Resolution falls back from exact match → OS prefix (`darwin-*`) → wildcard (`*` / `any` / `universal`) → single-entry maps. ## `binary_urls` — value can be a string OR an asset dict The simplest form is one URL per platform: ```json { "binary_urls": { "darwin-arm64": "https://example.com/v1/my-tool-darwin-arm64.tar.gz", "linux-x86_64": "https://example.com/v1/my-tool-linux-x86_64.tar.gz", "windows-x86_64":"https://example.com/v1/my-tool-windows-x86_64.zip" } } ``` For multi-file bundles or when you want sha256 verification, swap any value to an **asset dict**: ```json { "binary_urls": { "darwin-arm64": { "url": "https://example.com/v1/my-tool-darwin-arm64.tar.gz", "sha256": "9b1f...c2", "size": 18_345_678, "entrypoint": "bin/my-tool", "format": "tar.gz" }, "linux-x86_64": "https://example.com/v1/my-tool-linux-x86_64.tar.gz" } } ``` | Field | Required | What it does | |---|---|---| | `url` | yes | Where the Agent downloads from | | `sha256` | optional but recommended | Agent rejects the install on mismatch | | `size` | optional | Belt-and-braces size check | | `entrypoint` | optional | Path inside the archive that becomes the launcher (multi-file only) | | `format` | optional | `tar.gz` / `tgz` / `zip` / `raw`. Auto-inferred from URL suffix when omitted | The Nexus UI exposes these fields under each platform row's **▾ Advanced** toggle. ## Getting the bytes to your users — two tracks | Track | You declare | Where the bytes come from | Best for | |---|---|---|---| | **Direct upload (recommended)** | `distribution.binary_artifacts` — LOCAL archive paths | `anna-app executa upload-binaries` (or `apps cut`, automatically) pushes them straight to Anna storage | Private repos, CI without public releases, local build machines | | Pull-mirror | `distribution.binary_urls` — public GET-able URLs | The platform downloads from your URL at `apps cut` / release and mirrors it | Existing public GitHub Releases | Declare **exactly one** of the two for `type: "binary"`. Either way the end state is identical: the bytes live content-addressed in Anna storage, `binary_sha256` is pinned, and the Agent installs from the platform CDN with hash verification. ### `binary_artifacts` — direct upload (push model) ```json { "distribution": { "type": "binary", "binary_artifacts": { "darwin-arm64": { "path": "dist/my-tool-{version}-darwin-arm64.tar.gz", "entrypoint": "my-tool" }, "linux-x86_64": { "path": "dist/my-tool-{version}-linux-x86_64.tar.gz", "entrypoint": "my-tool" }, "windows-x86_64": { "path": "dist/my-tool-{version}-windows-x86_64.zip", "entrypoint": "my-tool", "format": "zip" } } } } ``` | Field | Required | What it does | |---|---|---| | `path` | yes | Archive path relative to the executa project root. Placeholders `{version}` / `{platform}` / `{tool_id}` expand at upload time | | `entrypoint` | recommended | Launcher inside the archive (same semantics as the asset-dict field) | | `format` | optional | `tar.gz` / `tgz` / `zip`; inferred from the path suffix when omitted. Bare executables are rejected — always archive | Then: ```bash anna-app executa upload-binaries # standalone: hash → upload → pin anna-app executa upload-binaries --dry-run # plan only (what would upload / what's cached) ``` Or just publish — the upload is built into the lifecycle: - `anna-app executa publish` uploads the artifacts **before** freezing the version, so the snapshot pins CDN URLs + sha256. - `anna-app apps cut` auto-uploads every bundled executa that declares `binary_artifacts` before the freeze. `apps push` never uploads (push stays light). Uploads are **content-addressed**: re-running with unchanged artifacts transfers zero bytes (`exists (skip)`), and interrupted uploads resume from the parts already received. The server independently re-hashes every uploaded archive and rejects a sha256 mismatch, and your source repo never needs a public URL — private repos and laptops publish the same way. Authentication uses your regular `anna-app login` PAT (scope `executas:publish`), exchanged internally for a 15-minute single-tool upload token. ### Zero-secret CI: OIDC Trusted Publishing Publishing binaries from GitHub Actions does not need a PAT at all. Register the workflow once (this mirrors PyPI's Trusted Publishers): ```bash anna-app executa trusted-publisher add \ --repository your-org/your-repo \ --workflow publish.yml \ --environment production # optional GitHub Environment gate ``` Then in the workflow the runner's own OIDC id-token is exchanged for the upload token: ```yaml permissions: id-token: write # lets the job mint a GitHub OIDC id-token contents: read steps: - uses: actions/checkout@v4 # ...build dist/ artifacts matching binary_artifacts paths... - run: | pnpm exec anna-app executa upload-binaries \ --oidc --host "$ANNA_APP_HOST" --tool-id "$TOOL_ID" ``` No `ANNA_APP_PAT` secret is involved: the platform verifies the id-token against GitHub's public keys (issuer + pinned audience + expiry) and matches the token's `repository` / `workflow_ref` / `environment` claims against your registration. Any branch or tag of the registered workflow file may publish (PyPI semantics); pin an `--environment` to also require the run to pass that GitHub Environment's protection rules. Manage registrations with `trusted-publisher list` / `trusted-publisher remove ` — or in the hub: the tool edit dialog's Binary section shows an **OIDC Trusted Publishers** panel (owners only) where you can add/remove registrations and see when each one was last used by CI. > [!NOTE] > OIDC covers the **binary upload** only. Lifecycle verbs (`apps push` / `cut` / `release`) still authenticate with a PAT. ### `binary_urls` — pull-mirror (public sources) Keep using `binary_urls` when your binaries are already on a public GitHub Release (or any public HTTPS URL): the platform pulls and mirrors them at `apps cut` / release. **Private source URLs are deprecated** and will be rejected in a future release — the platform cannot reliably fetch them; switch those projects to `binary_artifacts`. ## Multi-file binary layout When the Agent installs a multi-file archive it lays it out like this: ``` ~/.anna/executa/ bin/my-tool → tools/{tool_id}/current/bin/my-tool tools/{tool_id}/ v1.0.0/ bin/my-tool ← entrypoint lib/ ← .so / .dylib live here data/ ← bundled data manifest.json INSTALL.json ← install metadata (auto-written) current → v1.0.0 ← atomic blue-green upgrade pointer ``` `bin/my-tool` in the user's PATH-style shim is a stable entry point that survives upgrades — `current` is rewritten atomically, so an in-flight invocation keeps reading the old version. Older versions are GC'd according to `EXECUTA_KEEP_VERSIONS` (default 2). ## Manifest `runtime.binary` > [!IMPORTANT] > **Always ship a `manifest.json` at the archive root** — even for single-file binaries. It pins the install identity and prevents three classes of silent breakage: > > 1. **`name` collisions in `bin/`.** The Agent creates `~/.anna/executa/bin/{name}` as the launcher shim, where `{name}` is the `executable_name` (or, when omitted, a slug derived from the package / URL — e.g. `https://.../my-tool-darwin-arm64.tar.gz` becomes `my`, which collides with every other tool whose URL stem starts the same way). Pass an explicit `executable_name` / `tool_id` to avoid the URL-derived fallback. > 2. **Wrong entrypoint chosen.** Without an explicit entrypoint the Agent picks the only-or-first executable it finds in the archive, which is unpredictable for PyInstaller `--onedir`, Electron-style apps, and anything shipping helper binaries. > 3. **Missing executable bit.** ZIP archives don't carry Unix permissions; without `permissions` the Agent only chmods the entrypoint to `0o755`, leaving auxiliary scripts (post-install hooks, sub-CLIs) at `0o644` and Permission-denied at runtime. > [!IMPORTANT] > **Identity is the server-minted `tool_id`.** The Agent UI joins user-installed tools to running plugins via the `tool_id` the platform passes at install time — it no longer reads a self-reported manifest `name` (neither the one your binary returns from `describe` nor the `name` in this `manifest.json`). Mismatches between those self-reported names and the `tool_id` no longer matter. See [Publishing → Stabilise the manifest](/developers/tools/executa-publish#1-stabilise-the-manifest). Drop a `manifest.json` at the archive root: ```json { "name": "tool-acme-my-tool-abcd1234", "version": "1.0.0", "runtime": { "binary": { "entrypoint": { "default": "bin/my-tool", "windows-x86_64": "bin/my-tool.exe", "windows-arm64": "bin/my-tool.exe" }, "lib_dirs": ["lib"], "data_dirs": ["data"], "permissions": { "bin/my-tool": "0o755", "bin/post-install.sh": "0o755" } } } } ``` | Field | What it does | |---|---| | `name` | Human-facing label; conventionally the `tool_id` you minted on `/executa`. **Not** an identity check — the Agent joins installs to running plugins by the server-minted `tool_id` (see the note above), so a mismatch with the `name` your binary returns from `describe` is harmless. Still used as the `~/.anna/executa/bin/{name}` shim stem unless you pass `executable_name`. | | `version` | Optional but recommended; written into `INSTALL.json` and used as the version-dir name when caller omits it | | `runtime.binary.entrypoint` | Required for multi-file. String, or a `{ "default": "…", "darwin-arm64": "…", "windows-x86_64": "…" }` per-platform map (lookup order: full key → OS prefix → `default`) | | `runtime.binary.lib_dirs` | Documentation only; the Agent already prepends `lib/` and `lib64/` automatically | | `runtime.binary.data_dirs` | Documentation only; the Agent already exposes `EXECUTA_DATA` for the `data/` dir | | `runtime.binary.permissions` | Map of relative path → octal mode. The entrypoint is `0o755` by default | ### Resolution fallback (when `manifest.json` is absent) If you skip `manifest.json` (not recommended), the Agent walks five fallback levels in order: 1. `runtime.binary.entrypoint` from the archive `manifest.json` — *skipped, no manifest* 2. `entrypoint` from the asset dict in `binary_urls` 3. Standard locations in this order: `bin/{name}` → `bin/{name}.exe` → `{name}` → `{name}.exe` (where `{name}` is derived from the package or URL) 4. The **only** executable file in the archive 5. The **first** executable file (alphabetical), with a `WARN` log Levels 4–5 are deliberately fuzzy because they're a last-resort. If your archive has more than one executable (very common for `--onedir`), level 5 is almost certainly going to pick the wrong one. **Provide a manifest.** ## Runtime environment your binary will see Before launching the entrypoint the Agent injects: | Variable | Value | |---|---| | `EXECUTA_HOME` | absolute path to `tools/{tool_id}/current/` | | `EXECUTA_DATA` | `${EXECUTA_HOME}/data` (when it exists) | | `LD_LIBRARY_PATH` | prepended `${EXECUTA_HOME}/lib` and `lib64` (Linux) | | `DYLD_LIBRARY_PATH` | prepended `${EXECUTA_HOME}/lib` and `lib64` (macOS) | | `PATH` | prepended `${EXECUTA_HOME}/share/bin` (when it exists; on Windows `lib/` is added too) | | working directory | `EXECUTA_HOME` | This means your binary can `dlopen("libfoo.so", ...)`, your Python launcher can `Path(os.environ["EXECUTA_DATA"]) / "config.toml"`, etc. ## Language guides ### Python — single file ```bash pip install pyinstaller pyinstaller --onefile --name my-tool plugin.py # → dist/my-tool (or my-tool.exe on Windows) ``` Smoke-test: ```bash echo '{"jsonrpc":"2.0","method":"describe","id":1}' | ./dist/my-tool ``` > [!WARNING] > PyInstaller bundles imports it can detect statically. If you use dynamic imports (`importlib`), declare them with `--hidden-import` or PyInstaller will silently skip them. ### Python — with native dependencies When your plugin imports something with C extensions (`numpy`, `playwright`, `cryptography` with hardware backends, etc.), PyInstaller `--onefile` may fail to bundle them or bloat to hundreds of MBs. Use `--onedir` and ship as a multi-file archive — see the [multi-file Python example](https://github.com/whtcjdtc2007/anna-executa-examples/tree/main/examples/multifile-binary/python-pyinstaller-onedir). ### Node.js ```bash npm install -g @yao-pkg/pkg pkg plugin.js \ --targets node20-macos-arm64,node20-macos-x64,node20-linux-x64,node20-win-x64 \ --out-path dist ``` Native addons (`better-sqlite3`, `sharp`…) need extra prebuild config or a multi-file archive — see the `pkg` docs. ### Go ```bash GOOS=darwin GOARCH=arm64 go build -ldflags "-s -w" -o dist/my-tool-darwin-arm64 . GOOS=darwin GOARCH=amd64 go build -ldflags "-s -w" -o dist/my-tool-darwin-x86_64 . GOOS=linux GOARCH=amd64 go build -ldflags "-s -w" -o dist/my-tool-linux-x86_64 . GOOS=linux GOARCH=arm64 go build -ldflags "-s -w" -o dist/my-tool-linux-aarch64 . GOOS=windows GOARCH=amd64 go build -ldflags "-s -w" -o dist/my-tool-windows-x86_64.exe . ``` `-s -w` strips the symbol table and DWARF debug info; expect ~30 % smaller binaries. ## CI: build-release.yml The examples repo ships a [`build-release.yml`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/.github/workflows/build-release.yml) GitHub Actions workflow that builds all targets in a matrix and attaches them to the release. Copy it as a starting point and update the asset names to match the platform keys above. ## Code-signing (recommended) | Platform | Recommendation | |---|---| | macOS | Apple Developer ID + `codesign` + `notarytool` for notarisation | | Windows | Authenticode signing certificate (Sectigo, DigiCert, Azure Trusted Signing) | | Linux | GPG-sign release archives; users verify with the published public key | Unsigned binaries still run but trigger Gatekeeper / SmartScreen warnings on first launch. The Agent automatically clears `com.apple.quarantine` on macOS after extraction, so notarisation is the right long-term fix. ## Compatibility & rollback - The new layout is on by default. Set the env var `EXECUTA_INSTALL_V2=0` on the Agent to fall back to the legacy "single executable in `bin/`" install path — the same archive will be re-extracted into the old shape. - Existing legacy installs keep working: when a v2 install needs to write `bin/{name}` and finds a non-symlink there, it backs the old binary up to `~/.anna/executa/legacy-backup/` first. - Keep the same `tool_id` across releases so `tools/{tool_id}/current` updates atomically; changing `tool_id` triggers a fresh install dir. ## Local archive distribution (no URLs, no upload) `distribution_type: local` runs the **same v2 install pipeline** described above — extract → `tools/{tool_id}/v{version}/` → atomic `current` symlink → `bin/{name}` shim — but reads the archive from a **path on the Agent machine** instead of downloading from a URL. This is the recommended way to: - Iterate locally on a multi-file binary (`build.sh` → `dist/plugin.tar.gz` → install) without first pushing to GitHub Releases. - Distribute internally via NFS / shared filesystem when you can't (or won't) host an HTTPS URL. - Install in air-gapped environments. Form fields (Create Tool modal): | Field | Local value | |---|---| | Distribution Type | `local` | | Local Archive Path | Absolute path on the Agent host, e.g. `/Users/me/build/dist/my-tool.tar.gz` | | Executable Name | Optional; defaults to the archive base name | | Version | Optional; defaults to `dev` | Same archive layout & entrypoint resolution rules as binary (see [Multi-file binary layout](#multi-file-binary-layout) and [Manifest `runtime.binary`](#manifest-runtimebinary)). All security checks (zip-slip, 5GB extract limit, `..` traversal) apply identically. > [!NOTE] > Sha-256 / size verification is **skipped** for local installs (the archive is on your own machine). If you need integrity checks for shared-filesystem distribution, host the file over HTTPS and use `binary` instead. ## Reference - [Multi-file binary example (Python --onedir)](https://github.com/whtcjdtc2007/anna-executa-examples/tree/main/examples/multifile-binary/python-pyinstaller-onedir) - [`docs/binary-distribution.md`](https://github.com/whtcjdtc2007/anna-executa-examples/blob/main/docs/binary-distribution.md) in the examples repo has per-language `build_binary.sh` scripts that emit the platform-key asset layout. --- --- title: Image Generation — LLM Images Without an API Key description: Ask the host to generate or edit images on the user's behalf, with provider selection, billing, and storage handled by Anna. section: tools slug: executa-image updated: 2026-05-26 estimated_minutes: 8 --- Image generation lets your plugin produce — or restyle — images **on the user's behalf** without shipping a provider API key, without holding S3 credentials, and without metering quota. The plugin describes the image in protocol-neutral terms; Anna routes the call through the user's preferred image provider (DALL·E 3, Stable Diffusion XL, FLUX, …), charges the user's plan, uploads the result to host storage, and returns the URL. Available from Executa protocol **v2** onward; companion to [Sampling](/developers/tools/executa-sampling) and [Storage](/developers/tools/executa-storage). > [!TIP] > If your tool only needs to **embed** an existing image (e.g. a brand logo the user uploaded), use [Host Upload](/developers/tools/executa-host-upload) instead — generation is for when the pixels do not exist yet. ## Three pre-conditions End-to-end image generation requires **all** of: 1. **v2 negotiation.** The host sends `initialize`; the plugin replies with `protocolVersion: "2.0"` and lists `client_capabilities.image` (and `image.edit` if you use `image/edit`). 2. **Manifest declaration.** Your published manifest declares the capabilities it intends to use: ```json { "host_capabilities": ["llm.image", "llm.image.edit"] } ``` The publish validator rejects unknown capability strings. 3. **User grant.** The end user enabled `image_grant.generate = true` (and `image_grant.edit = true`) for this Executa in their Anna Admin panel. The grant carries `max_images_per_day` and `max_per_call` caps. If any pre-condition is missing, the host returns `IMAGE_NOT_NEGOTIATED (-32107)` or `IMAGE_NOT_GRANTED (-32101)` and the reverse-RPC never reaches a provider. ## Wire protocol While processing an `invoke`, emit a reverse JSON-RPC request on stdout: ### `image/generate` ```json { "jsonrpc": "2.0", "id": "img-1", "method": "image/generate", "params": { "prompt": "A bold art-deco poster of the planet Mars.", "n": 1, "size": "1024x1024", "reference_image_urls": [], "modelPreferences": { "hints": [{ "name": "dalle-3" }] }, "metadata": { "executa_invoke_id": "" } } } ``` The host responds with the bare result (no wrapper): ```json { "jsonrpc": "2.0", "id": "img-1", "result": { "images": [ { "url": "https://r2.anna.partners/exec/.../poster.png", "mimeType": "image/png", "width": 1024, "height": 1024 } ], "model": "dall-e-3", "quota_used": { "images_today": 3, "images_quota": 50 } } } ``` ### `image/edit` ```json { "jsonrpc": "2.0", "id": "img-2", "method": "image/edit", "params": { "image_url": "https://r2.anna.partners/exec/.../poster.png", "prompt": "Restyle in a cyberpunk aesthetic. Preserve composition.", "n": 1, "mask_url": null } } ``` `mask_url` is optional. Not every provider supports masks — if the user's preferred provider does not, the host returns `MASK_UNSUPPORTED (-32312)`. ## SDK examples ### Python ```python from executa_sdk import ImageClient, ImageError image = ImageClient(write_frame=_write_frame) try: result = await image.generate( prompt="A bold art-deco poster of the planet Mars.", n=1, size="1024x1024", metadata={"executa_invoke_id": invoke_id}, timeout=120.0, ) except ImageError as e: # e.code in {-32101, -32102, -32107, …} return _make_response(req_id, error={"code": e.code, "message": e.message}) ``` ### Node.js ```js import { ImageClient } from "executa-sdk"; const image = new ImageClient({ writeFrame }); const result = await image.generate({ prompt: "A bold art-deco poster of the planet Mars.", n: 1, size: "1024x1024", timeoutMs: 120000, }); ``` ### Go ```go import imageclient "github.com/openclaw/anna-executa-examples/sdk/go/image" c := imageclient.New(writeFrame) res, err := c.Generate(imageclient.GenerateRequest{ Prompt: "A bold art-deco poster of the planet Mars.", N: 1, Size: "1024x1024", }, 120*time.Second) ``` ## Error reference | Code | Constant | Meaning | | -------- | ------------------------ | ------- | | `-32101` | `IMAGE_NOT_GRANTED` | User has not enabled `image_grant.generate` for this Executa. | | `-32102` | `IMAGE_QUOTA_EXCEEDED` | User exhausted `max_images_per_day`. | | `-32103` | `IMAGE_PROVIDER_ERROR` | Upstream provider 5xx / model error. | | `-32104` | `IMAGE_INVALID_REQUEST` | Bad `size`, empty `prompt`, etc. | | `-32105` | `IMAGE_TIMEOUT` | Provider exceeded host wall-clock. | | `-32106` | `IMAGE_MAX_IMAGES_EXCEEDED` | `n` > `image_grant.max_per_call`. | | `-32107` | `IMAGE_NOT_NEGOTIATED` | Manifest did not list `llm.image`, or v2 not negotiated. | | `-32108` | `IMAGE_USER_DENIED` | User declined an in-the-moment confirm prompt. | | `-32109` | `IMAGE_NO_MODEL_AVAILABLE` | User has no image provider configured. | | `-32110` | `IMAGE_STORAGE_ERROR` | Host failed to persist generated image to R2. | | `-32311` | `EDIT_NOT_SUPPORTED` | Selected provider does not support `image/edit`. | | `-32312` | `MASK_UNSUPPORTED` | Provider supports edit but not masks. | | `-32313` | `N_UNSUPPORTED` | Provider supports edit but not `n > 1`. | | `-32314` | `REFERENCE_FETCH_FAILED` | `reference_image_urls[i]` was unreachable. | ## Pitfalls > [!WARNING] > **`n` is capped per-call AND per-day.** `image_grant.max_per_call` caps any single call; `max_images_per_day` is a rolling 24-hour counter shared across every Executa+app combo the user has granted image to. Surface the canonical error code and let the user adjust the grant — never silently retry with smaller `n`. > [!IMPORTANT] > **Returned URLs expire.** R2 presigned URLs default to 1 hour. If you store the URL in APS / app state, plan to refresh via `image/generate` regen, or persist via [`host/uploadFile`](/developers/tools/executa-host-upload) into a longer-lived key. Treat the URL as ephemeral artifact, not durable storage. > [!TIP] > **Reference images count against the `reference_image_urls[]` quota.** Each URL the host fetches is one inbound network hop billed against the user's monthly bandwidth. Keep the count small (≤ 3). ## See also - App-side companion (anna-app bundle, Host API): [`image.*` reference](/developers/reference/host-api-image) - Plugin sample: [`anna-executa-examples/examples/python/image-poster/`](https://github.com/openclaw/anna-executa-examples/tree/main/examples/python/image-poster) - Persist generated bytes back to host: [Host Upload](/developers/tools/executa-host-upload) - Lifecycle & v2 handshake: [Lifecycle](/developers/tools/executa-lifecycle) --- --- title: Host Upload — Persist Files Without S3 Credentials description: Hand a file (or its bytes) to Anna; the host stores it in shared R2 and returns a presigned download URL — your plugin never sees an S3 key. section: tools slug: executa-host-upload updated: 2026-05-27 estimated_minutes: 7 --- `host/uploadFile` lets your plugin persist a file — text, image bytes, an LLM transcript, anything under the user's MIME allow-list — to Anna's shared R2 bucket **without holding S3 credentials**. The host writes the object under a stable per-user / per-tool / per-invoke key and returns a presigned download URL. The plugin never touches an AWS SDK and the file inherits the user's plan-level retention. Available from Executa protocol **v2** onward; pairs naturally with [Image Generation](/developers/tools/executa-image) (persist a generated PNG outside its 30-minute window) and [Sampling](/developers/tools/executa-sampling) (persist an LLM summary). > [!TIP] > Use Host Upload for **ephemeral / shareable** artefacts (≤ 80 MiB total per invoke, short presigned URLs). For durable per-user data that survives across invokes — caches, notes, files in the user's drive — use [Persistent Storage (APS)](/developers/tools/executa-storage) instead. ## Three pre-conditions End-to-end `host/uploadFile` access requires **all** of: 1. **v2 negotiation.** Reply to `initialize` with `protocolVersion: "2.0"` and a non-empty `capabilities.upload` claim (an empty object is fine). 2. **Manifest declaration.** Your published manifest declares the host capability: ```json { "host_capabilities": ["host.upload"] } ``` The publish validator rejects unknown capability strings. 3. **User grant.** The end user enabled `upload_grant` for this Executa in Anna Admin. The grant carries: ```json { "enabled": true, "maxFiles": 16, "maxFileBytes": 26214400, "allowedPurposes": ["image_input", "image_reference", "user_artifact"] } ``` `maxFiles` and `maxFileBytes` (single-file cap) feed the per-invoke counters. There is **no MIME allowlist**: any type that is not on the host's hard denylist (executables, `image/svg+xml`) is accepted — Office formats included. Inline-rendering risk is controlled at serve time instead: every `download_url` carries a signed `Content-Disposition` (`inline` only for `image/*` / `audio/*` / `video/*` / `application/pdf`, `attachment` for everything else). Missing any pre-condition surfaces as `UPLOAD_NOT_GRANTED (-32201)` (capability / manifest / grant) or `UPLOAD_NOT_NEGOTIATED (-32210)` (no `upload_token` in the invoke context — usually means the host did not authorize this Executa at invoke time). ## Wire protocol `host/uploadFile` is a single reverse-RPC method with three payload modes selected by `params.mode`: ``` inline → base64 bytes (≤ 8 MiB) ── 1 hop negotiate → presigned PUT URL ── 2 hops (negotiate + plugin PUT) confirm → finalise presigned upload ── 1 hop (HEAD on R2 + GET url) ``` All three return a single envelope (see [Result shape](#result-shape)). ### `mode: "inline"` (recommended for ≤ 8 MiB) ```json { "jsonrpc": "2.0", "id": "u-1", "method": "host/uploadFile", "params": { "mode": "inline", "filename": "summary.txt", "mime_type": "text/plain", "purpose": "user_artifact", "content_b64": "" } } ``` > [!IMPORTANT] > **Hard 8 MiB cap on inline (decoded bytes).** This is a server constant (`INLINE_MAX_BYTES`), independent of `maxFileBytes`. Anything larger MUST use negotiate → PUT → confirm. The host returns `UPLOAD_TOO_LARGE (-32204)` after base64 decoding if exceeded. ### `mode: "negotiate"` (any size up to `maxFileBytes`) ```json { "mode": "negotiate", "filename": "video.mp4", "mime_type": "video/mp4", "purpose": "user_artifact", "expected_bytes": 52428800 } ``` `expected_bytes` is optional but recommended — it lets the host reject oversized uploads before signing the URL. The response carries a short-lived (default **5 min**) presigned PUT URL: ```json { "r2_key": "exec-uploads/prod////user_artifact/...", "put_url": "https://.r2.cloudflarestorage.com/...?X-Amz-Signature=...", "headers": { "Content-Type": "video/mp4" }, "expires_in": 300, "expires_at": "2026-07-13T12:05:00Z", "_meta": { "mode": "presigned-put" } } ``` The plugin then `PUT`s the bytes directly to `put_url` with `Content-Type: ` (no `Authorization` header — the URL is pre-signed) and finally: ### `mode: "confirm"` ```json { "mode": "confirm", "r2_key": "" } ``` `confirm` HEADs the R2 object, validates the upload landed, settles the byte counter against the per-invoke quota, and returns the canonical envelope (with `download_url`). ## Result shape All three modes return the same envelope (only `_meta.mode` differs): ```json { "r2_key": "exec-uploads//////__", "download_url": "https://r2.anna.partners/...?X-Amz-Signature=...", "url": "https://r2.anna.partners/...?X-Amz-Signature=...", "mime_type": "image/png", "size_bytes": 204800, "bytes": 204800, "expires_at": "2026-07-13T12:30:00Z", "expires_in": 1800, "_meta": { "mode": "inline" } } ``` | Field | Type | Notes | |---|---|---| | `r2_key` | string | Opaque storage key. Treat as a handle, not a navigable path. | | `download_url` | string | Presigned **GET** URL, valid until `expires_at`. **Canonical** — matches the SDKs and examples. | | `url` | string | Legacy alias of `download_url`, kept for Executas published before the field alignment. | | `mime_type` | string | Echoes the request (lower-cased). | | `size_bytes` | integer | Decoded / actual size after upload. **Canonical.** | | `bytes` | integer | Legacy alias of `size_bytes`. | | `expires_at` | string | Absolute UTC expiry of `download_url` (ISO 8601). **Canonical.** | | `expires_in` | integer | Legacy alias: seconds until expiry (default 30 min). Re-call `mode: "confirm"` with the same `r2_key` to mint a fresh URL at zero quota cost. | > [!NOTE] > Both field sets are always returned. New code should read `download_url` / `size_bytes` / `expires_at`; the `url` / `bytes` / `expires_in` aliases remain for backward compatibility. > [!IMPORTANT] > The returned `url` is **transient** — typically 30 minutes. If the artefact needs to survive longer, either persist the `r2_key` and re-sign on demand via `confirm`, or copy the bytes into [APS files](/developers/tools/executa-storage#object-uploads-two-step). ## SDK examples ### Python ```python from executa_sdk import HostUploadClient upload = HostUploadClient(write_frame=_write_frame) result = await upload.upload_inline( filename="poster.png", mime_type="image/png", content=png_bytes, # raw bytes; SDK base64-encodes purpose="user_artifact", timeout=60.0, ) print(result["download_url"], result["size_bytes"], "expires_at", result["expires_at"]) ``` ### Node.js ```js import { HostUploadClient } from "executa-sdk"; const upload = new HostUploadClient({ writeFrame }); const out = await upload.uploadInline({ filename: "poster.png", mimeType: "image/png", content: pngUint8, // Uint8Array; SDK base64-encodes purpose: "user_artifact", }); ``` ### Go ```go import upload "github.com/openclaw/anna-executa-examples/sdk/go/host_upload" c := upload.New(writeFrame) res, err := c.UploadInline(upload.InlineRequest{ Filename: "poster.png", MimeType: "image/png", Content: pngBytes, Purpose: "user_artifact", }, 60*time.Second) ``` ## Error reference The plugin sees these JSON-RPC errors (wire codes & names are normative in the Anna Agent runtime): | Code | Constant | Meaning | | -------- | --------------------------- | ------- | | `-32201` | `UPLOAD_NOT_GRANTED` | Capability missing, manifest didn't declare `host.upload`, or `upload_grant.enabled = false`. | | `-32202` | `QUOTA_EXCEEDED` | Plan upload quota exhausted. | | `-32203` | `INVALID_REQUEST` | Bad `mode`, missing `filename` / `mime_type`, malformed `content_b64`, etc. | | `-32204` | `TOO_LARGE` | Decoded bytes exceed `maxFileBytes` or the 8 MiB inline cap. | | `-32205` | `MIME_REJECTED` | `mime_type` malformed or on the host hard denylist (executables, `image/svg+xml`). The per-token MIME allowlist was removed — any other type is accepted. | | `-32206` | `PURPOSE_REJECTED` | `purpose` not in the protocol whitelist (`image_input` / `image_reference` / `user_artifact`) or not in `allowedPurposes`. | | `-32207` | `STORAGE_ERROR` | R2 5xx / network. Also wraps subcall timeouts (`errorName: "subcall_timeout"`). | | `-32208` | `TIMEOUT` | Provider call exceeded the host wall-clock. | | `-32209` | `USER_DENIED` | User declined an in-the-moment confirm prompt. | | `-32210` | `UPLOAD_NOT_NEGOTIATED` | v2 not negotiated, or reverse-RPC invoked outside an invoke context. | | `-32211` | `MAX_FILES_EXCEEDED` | Per-invoke `maxFiles` hit. | | `-32212` | `NOT_FOUND` | `confirm` on an unknown `r2_key` (object not uploaded yet, or wrong tool / invoke). | | `-32213` | `PRESIGN_FAILED` | Host could not sign the PUT URL. | | `-32602` | `MISSING_INVOKE_CONTEXT` / `UNKNOWN_INVOKE_CONTEXT` | Reverse RPC could not be correlated with a parent invoke — see below. | ### Concurrent invokes: propagate `context.invoke_id` `negotiate` r2_keys are scoped to the **parent invoke**; `confirm` validates ownership. When your Executa serves multiple `tools.invoke` calls concurrently, each `host/uploadFile` reverse RPC **must** carry `params.context.invoke_id` of its own parent invoke, or the host cannot associate the calls and rejects with `MISSING_INVOKE_CONTEXT` (it never guesses — guessing is how `r2_key does not belong to this invoke` used to happen intermittently). The SDKs stamp the field automatically once you wrap the tool handler: ```python from executa_sdk import bind_invoke def handle_invoke(req_id, params): with bind_invoke(params): # binds params.context.invoke_id ... # negotiate / PUT / confirm here ``` ```js const { bindInvoke } = require("@anna/executa-sdk"); await bindInvoke(params, async () => { /* negotiate / PUT / confirm */ }); ``` Single-invoke-at-a-time plugins keep working without the field (the host falls back to the sole active invoke). ## Quota & limits | Limit | Default | Source | |---|---|---| | Inline payload (decoded) | **8 MiB** | `INLINE_MAX_BYTES` | | Single-file size cap | **20 MiB** (token default); grants typically widen to **25 MiB** | `upload_token.max_file_bytes`, `upload_grant.maxFileBytes` | | Per-invoke total bytes | **80 MiB** | `upload_token.max_total_bytes` | | Per-invoke file count | **16** | `upload_token.max_files`, `upload_grant.maxFiles` | | Presigned PUT URL TTL | **300 s** | `DEFAULT_PRESIGN_PUT_EXPIRY` | | Returned GET URL TTL | **~30 min** | `R2_TRANSIENT_PRESIGN_EXPIRY` | | `upload_token` TTL | **600 s** (10 min) | JWT `aud=executa-upload` | | Default `allowedPurposes` | `image_input`, `image_reference`, `user_artifact` | `DEFAULT_UPLOAD_ALLOWED_PURPOSES` | Treat `QUOTA_EXCEEDED`, `MAX_FILES_EXCEEDED`, and `TOO_LARGE` as **non-retryable** within the same invocation; treat `STORAGE_ERROR` / `TIMEOUT` as retryable with backoff (≤ 2 attempts). ## Pitfalls > [!WARNING] > **Inline payload is base64.** Wire size is ≈ 1.33 × the decoded bytes. A 7 MiB file becomes ~9.3 MiB on the wire — if your stdio frame writer caps at 8 MiB you'll truncate before the host even sees the request. SDKs encode for you, but if you hand-build frames, size-check the **encoded** length. > [!IMPORTANT] > **`r2_key` is opaque, not navigable.** Do not parse or construct it. The host owns the layout (`exec-uploads//////__`); future migrations may change it. Use `url` to share, `r2_key` only as an opaque handle for `confirm`. > [!TIP] > **`purpose` drives lifecycle policy.** Pick the most accurate value: > - `image_input` — bytes the user uploaded into the plugin (model input). > - `image_reference` — reference images passed to `image/generate`. > - `user_artifact` — anything the plugin produced and wants to hand back to the user (default). > > Anything else returns `PURPOSE_REJECTED (-32206)`. > [!CAUTION] > **SVG is blocked.** `image/svg+xml` can carry executable JS → XSS risk. Use PNG / JPEG / WebP instead. Other blocked MIME types: `application/x-msdownload`, `application/x-msdos-program`, `application/x-executable`, `application/x-sharedlib`. ## See also - App-side companion (anna-app bundle, Host API): [`upload.*` reference](/developers/reference/host-api-upload) - Plugin sample: [`anna-executa-examples/examples/python/image-poster/`](https://github.com/openclaw/anna-executa-examples/tree/main/examples/python/image-poster) — uses `host/uploadFile` to persist a generated poster. - Image generation: [Image (Tool)](/developers/tools/executa-image) - Durable per-user storage: [Persistent Storage (APS)](/developers/tools/executa-storage) - Lifecycle & v2 handshake: [Lifecycle](/developers/tools/executa-lifecycle) --- --- title: Publishing a Tool description: From local prototype to a discoverable, installable Executa tool. section: tools slug: executa-publish updated: 2026-05-11 estimated_minutes: 6 --- The `/executa` page hosts the Tool / Skill lifecycle: create a draft, fill in the manifest, then choose how widely to publish it. Pro / Max users may publish their own tools. ## 1. Stabilise the manifest Before publishing, do a self-review: - [ ] Tool `name`s are stable. Renaming after publish breaks every saved conversation that referenced them. - [ ] Each `description` reads well to an LLM — it's the prompt the model uses to decide whether to call your tool. - [ ] Parameters are typed; arrays declare `items` so the LLM passes a real list, not a JSON-encoded string. - [ ] Failure paths return `{ "success": false, "error": "…actionable message…" }` (or a JSON-RPC `error` for programmer errors). - [ ] Credentials are declared with stable `name`s. - [ ] `version` follows SemVer. - [ ] Plugin process is **long-running** (loops on stdin until EOF). A one-shot process passes `describe` once and then shows up as **Stopped** in the UI forever — see [Common pitfalls](/developers/tools/executa-intro#common-pitfalls). > [!IMPORTANT] > **Identity is the server-minted `tool_id` — nothing else.** You **cannot** pick this string yourself; it is always `tool-{author_handle}-{slug}-{uniq}`, reserved by the **🪣 Mint** button, and the platform passes it to the Agent when the tool is installed. > > The Agent no longer reads a self-reported manifest `name` (neither the one your binary returns from `describe` nor the one in the archive `manifest.json`). You do **not** need to bake the `tool_id` into either of them. The Agent UI joins user-installed tools to running plugins via the minted `tool_id`. ## 2. Mint a stable `tool_id` first Open the `/executa` page, switch to the **My Tools** tab, and click **Create Tool**. In the form: 1. Fill in **Name** and **Type** (`tool` / `skill`). 2. Click the **🪪 Mint** button next to the Tool ID field. **This step is mandatory** — the Tool ID input is read-only and the **Create** button is disabled until you mint. Mint reserves a stable `tool_id` (`tool-{author_handle}-{slug}-{uniq}`) and locks it for your account. Copy this ID — you'll bake it into the binary in the next step. The button then shows **🔒 Minted**, and the ID is yours for the next 24 h even if you walk away (drafts expire after 24 h if never committed). > [!IMPORTANT] > **Mint-only policy.** Tool IDs are entirely server-controlled; clients cannot supply or override `tool_id` via the REST API or UI. Any `tool_id` field on a `POST /executas/my/tools` payload is silently dropped. The only way to obtain an ID is via the **🪪 Mint** flow (`POST /executas/my/drafts` → `POST /executas/my/drafts/{id}/commit`). > [!IMPORTANT] > Mint **before** building. The `tool_id` is the canonical identity the Agent uses to install, route, and pin versions of your tool. If you publish a binary first, you'll have to rebuild and re-upload everything to align them. ## 3. Build & host artifacts (binary distribution) Now that you have the `tool_id`, build your tool and host the assets on GitHub Releases or any HTTPS CDN — follow [Binary Distribution](/developers/tools/executa-binary) for platform-key naming. You no longer need to embed the `tool_id` into the manifest your binary returns from `describe` or the `manifest.json` at the archive root; the platform tracks identity via the minted `tool_id` and passes it to the Agent at install time. If you ship via `uv` / `npm` / `pipx` / `homebrew` instead, publish to that registry now; the Agent installs from there. (Local-only tools can skip this section.) ## 4. Fill in the rest of the form and publish Back on the `/executa` Create Tool form (the draft you minted in step 2 is still open), fill in the remaining fields and click **Create**: 1. **Manifest** — paste the JSON your binary returns from `describe`. The form auto-extracts tools, credentials, and version. 2. **Distribution** — pick `distribution_type` (`uv` / `npm` / `homebrew` / `binary` / `pipx` / `local`), set `package_name`, `executable_name`, and: - For `binary`: the per-platform URLs you hosted in step 3. - For `local`: the absolute path to a local archive on the Agent machine (`.tar.gz` / `.tgz` / `.zip` / raw single executable). The Agent runs the **same install pipeline as `binary`** — extracts the archive into `tools/{tool_id}/v{version}/`, resolves the entrypoint, creates the `current` symlink, and registers the bin shim. This means Local **fully supports multi-file binaries** (PyInstaller `--onedir`, native `.so`, etc.); see [Local archive distribution](/developers/tools/executa-binary#local-archive-distribution-no-urls-no-upload). 3. **Capabilities & docs** — logo URL, README, sample prompts, capability tags. 4. **Visibility** — `private`, `app_bundled`, or `public` (see below). Clicking **Create** promotes the draft into a real Executa under your account. The `tool_id` you minted in step 2 stays the same. > [!NOTE] > The whole flow is UI-driven on `/executa`; you don't need to call any HTTP endpoints by hand. The page handles draft reservation, manifest patching, and commit for you. ## 5. Choose a visibility | Visibility | Where it appears | Who can install | |---|---|---| | `private` | Only your `/executa` workspace | Only you | | `app_bundled` | Hidden from the Explore Hub, but installable as part of any Anna App that bundles it | Anyone who installs the host App | | `public` | Listed in the Explore Hub | Anyone | Use `app_bundled` when your tool is meant to ship alongside a specific Anna App rather than as a standalone offering. Switch between the three states using the visibility segmented control on each tool card in **My Tools** — no API call required. ## 5a. Iterate before publishing — the dev loop You do **not** need to flip visibility to `public` (i.e. **Publish**) to test that your tool installs on an Agent. Doing so prematurely is the common cause of "every failed install leaves a useless tool behind". The intended dev loop is: 1. **Create** the Executa with `visibility=private`, and **Mint** a `tool_id` (sections 2 & 4 above). Don't click Publish yet. 2. From **/executa → My Tools**, click the install/enable toggle so a `UserExecuta` row is created for your account. 3. Go to **/agents → Install Essentials**. Your unpublished private Executa is picked up by the same batch installer the published ones use — `is_published` is **not** a filter on this path. 4. If the install fails, edit the Executa (description, `distribution_url`, `binary_urls`, manifest, …) and click Install Essentials again. **The same `tool_id` is reused on every retry — no new tool created, no cleanup needed.** 5. Only once the install succeeds end-to-end do you promote `visibility` to `app_bundled` (for a host Anna App) or `public` (Hub listing). The first promotion is the point at which an immutable `ExecutaVersion` snapshot is frozen. > [!TIP] > Editing an already-bundled tool is allowed and safe: the live row is mutable, but every published Anna App version pins to the **frozen `ExecutaVersion` snapshot** taken at its release, so existing users are not affected. The edit modal shows a banner reminding you of this. ## 6. Publish a new version When you ship a manifest or binary update, click **New Version** on the tool card. Each publish freezes an immutable `ExecutaVersion` snapshot so apps that pin to a version see stable content. The version number auto-bumps SemVer patch unless you set a specific value in the manifest first. If the manifest hasn't changed since the last published version, the action is rejected with "No content changes since the last published version" — update the manifest before re-publishing. ## 7. Promote inside an Anna App The most common discovery path for a tool isn't the Hub — it's an Anna App that bundles it. Once your tool exists (any visibility), an Anna App can list its `tool_id` in the App manifest. See [What is an Anna App](/developers/apps/app-intro). > [!TIP] > Tools that don't appear in any App typically see a small fraction of the installs of those that do. Bundle your tool into a complementary App to maximise distribution. --- --- title: Common Pitfalls description: The bugs that show up most often when authors build Executa plugins, and how to spot them fast. section: tools slug: executa-pitfalls updated: 2026-08-31 estimated_minutes: 8 --- If your plugin "installs" but the Anna UI shows it as **Stopped** (or it doesn't appear at all), this is the first page to read. Each pitfall lists the symptom you'll observe, the root cause, and the fix. --- ## 1 · Plugin process exits after one request **Symptom** - Manual test works: `echo '{"jsonrpc":"2.0","method":"describe","id":1}' | ./my-plugin` returns a manifest. - The Agent UI shows the plugin card as **Stopped** immediately after install. - Each tool call pays a noticeable cold-start delay. **Cause** Executa is a **long-running** protocol. The Agent spawns one process per plugin and reuses it for every `describe` / `invoke` / `health`. A plugin that returns from `main()` (or calls `sys.exit()` / `process.exit()` / `os.Exit()`) after handling a single request is broken — every subsequent request triggers a restart, and the UI never observes a live process. **Fix** Loop on stdin until EOF. The Agent closes stdin to request shutdown. ```python # Python import json, sys for line in sys.stdin: # ← loop until EOF line = line.strip() if not line: continue req = json.loads(line) resp = handle(req) sys.stdout.write(json.dumps(resp) + "\n") sys.stdout.flush() # ← required ``` ```javascript // Node.js const readline = require("readline"); const rl = readline.createInterface({ input: process.stdin }); rl.on("line", (line) => { const req = JSON.parse(line); process.stdout.write(JSON.stringify(handle(req)) + "\n"); }); // Don't call process.exit(); let the runtime exit naturally on stdin close. ``` ```go // Go scanner := bufio.NewScanner(os.Stdin) scanner.Buffer(make([]byte, 0, 1024*1024), 1024*1024) for scanner.Scan() { // ← loop until EOF line := strings.TrimSpace(scanner.Text()) if line == "" { continue } // ... handle and Fprintln(os.Stdout, ...) ... } ``` **Quick local check** ```bash ./my-plugin <<< '{"jsonrpc":"2.0","method":"describe","id":1}' & PID=$! sleep 2 if kill -0 $PID 2>/dev/null; then echo "OK — still running" kill $PID else echo "BUG — plugin exited after one request" fi ``` --- ## 2 · Three names don't match (`tool_id` vs `describe.name` vs archive `manifest.json` `name`) **Symptom** - The plugin appears under **Extra Agent Plugins** in the UI instead of next to the tool you installed. - Or: the user-installed card shows **Stopped** while a duplicate appears as **Running** elsewhere. - Or: `~/.anna/executa/bin/` contains a file with a generic name like `tool` instead of your tool ID. **Cause** Three identifiers must be **exactly** equal: | Where | What | |---|---| | Anna `/executa` form (Tool ID field) | The `tool_id` minted with the 🪪 button, e.g. `tool-acme-my-tool-abcd1234` | | Your binary | The `name` field in the manifest your plugin returns from `describe` | | Archive root `manifest.json` | The `name` field in the JSON file you ship inside the `.tar.gz` / `.zip` | The Agent UI joins user-installed tools to running plugins by string-matching these three; the archive `manifest.json` `name` also becomes the launcher symlink at `~/.anna/executa/bin/{name}`. **Fix** Pick the value once when you mint the `tool_id` and paste it everywhere. `display_name` is for the human-readable label — `display_name: "My Tool"` is fine; only `name` has to match. --- ## 3 · Banner / debug text on stdout **Symptom** - Agent log shows `Failed to parse JSON-RPC frame`. - `describe` times out from the Agent's side even though `echo … | ./my-plugin` works. **Cause** You printed something to stdout before — or between — JSON-RPC responses. The Agent only treats lines that parse as JSON objects as protocol frames; banners and stray prints corrupt the stream. **Fix** All human-readable output goes to **stderr**: ```python print("🔌 plugin started", file=sys.stderr) # ✅ sys.stdout.write(json.dumps(response) + "\n") # ✅ JSON-RPC only ``` ```javascript console.error("🔌 plugin started"); // ✅ process.stdout.write(JSON.stringify(response) + "\n"); // ✅ ``` --- ## 4 · Manifest uses MCP-style `input_schema` instead of `parameters` **Symptom** - The plugin loads and the LLM calls the tool, but with **fabricated argument names** like `content`, `input`, or `query` that you never declared. - Your tool's parameter dict shows up empty or partially filled — yet the tool returns success, so the failure is silent. **Cause** Matrix's `ToolDefinition.from_dict` reads the protocol-native `parameters` array. If you ship MCP-flavoured `input_schema` (a JSON Schema object), Matrix sees zero declared parameters; the LLM gets an undocumented tool and hallucinates argument names. **Fix** Use the canonical Executa shape: ```json { "tools": [{ "name": "send", "description": "Send a tweet", "parameters": [ { "name": "text", "type": "string", "required": true, "description": "Tweet body, ≤ 280 chars" } ] }] } ``` Not: ```jsonc // ❌ Silently ignored by Matrix — produces empty parameter list "input_schema": { "type": "object", "properties": { "text": { "type": "string" } }, "required": ["text"] } ``` See [Protocol Specification — Parameter schema](/developers/tools/executa-protocol#parameter-schema) for supported types. --- ## 5 · Wrong `result` shape for `describe` vs `invoke` The two methods are asymmetric — easy to mix up. **`describe`** returns the manifest **directly** as the `result`: ```json { "jsonrpc": "2.0", "id": 1, "result": { "name": "…", "tools": [...] } } ✅ { "jsonrpc": "2.0", "id": 1, "result": { "manifest": { … } } } ❌ ``` The wrong shape causes the Agent to log `❌ 无法获取 describe: …: 'name'` and drop the plugin at load time. **`invoke`** returns a wrapped object inside `result`: ```json { "jsonrpc": "2.0", "id": 2, "result": { "success": true, "data": { … }, "duration_ms": 12 } } ✅ { "jsonrpc": "2.0", "id": 2, "result": { "etag": "…", "count": 5 } } ❌ ``` Without `success: true`, Matrix's `InvokeResult.from_dict` defaults `success = false` and the LLM thinks the call failed — even though your tool ran fine. --- ## 6 · Missing `manifest.json` in multi-file archives **Symptom** - After install, the Agent picks the wrong executable (e.g. a helper binary instead of the main one). - Auxiliary scripts (`bin/post-install.sh`, sub-CLIs) get `Permission denied` at runtime. - `~/.anna/executa/bin/` ends up with a generic name derived from the URL. **Cause** Without `manifest.json`, the Agent walks a five-level fallback (asset `entrypoint` → `bin/{name}` → only-or-first executable) and ZIP archives lose Unix permission bits. Both produce silent footguns when the archive contains more than one executable. **Fix** Always ship `manifest.json` at the archive root, even for single-file binaries: ```json { "name": "tool-acme-my-tool-abcd1234", "version": "1.0.0", "runtime": { "binary": { "entrypoint": { "default": "bin/my-tool", "windows-x86_64": "bin/my-tool.exe" }, "permissions": { "bin/my-tool": "0o755", "bin/post-install.sh": "0o755" } } } } ``` See [Binary Distribution](/developers/tools/executa-binary). --- ## 7 · PyInstaller cold start exceeds the 5 s `describe` timeout **Symptom** - The first invocation after a fresh install fails with `describe timeout`. Subsequent calls work. **Cause** PyInstaller `--onefile` extracts the bundle to a temp directory on first launch; on a 200 MB+ binary this can take 10–30 s, especially on Apple Silicon under Rosetta or on slow filesystems. **Fix** The Agent already grants binary distributions a **60 s** describe timeout for the post-install scan, but the steady-state cap is back to 5 s. Three options, in order of preference: 1. Switch to `--onedir` and ship as a multi-file archive. 2. Reduce bundle size — `--exclude-module`, audit `--collect-all` flags. 3. Move heavy initialization into `invoke` rather than module-import / `describe` time. --- ## 8 · Sampling — `host_capabilities` not declared **Symptom** Your plugin issues `sampling/createMessage`, the host returns `error: { code: -32008, message: "not_negotiated" }`, and the Agent log says *"executa X did not declare host_capabilities['llm.sample']"*. **Cause** Even after v2 negotiation, Nexus refuses sampling unless the plugin's published manifest **also** declares the capability. **Fix** ```json { "name": "my-tool", "host_capabilities": ["llm.sample"], "tools": [ /* ... */ ] } ``` Re-publish the Executa version and ask users to update. See [Sampling](/developers/tools/executa-sampling#three-pre-conditions). --- ## 9 · Sampling / Storage — plugin exits before reverse RPC completes **Symptom** First reverse RPC call works in dev, but in production the result never arrives — Agent logs *"unmatched response id=…"* and the host times out. **Cause** The plugin returned the `invoke` result and immediately did `process.exit()` / `sys.exit()`, killing the stdin reader before the reverse-RPC response could be dispatched. **Fix** Same as Pitfall #1 — the plugin process must be long-running. The official SDKs (`sdk/{python,nodejs,go}` in [anna-executa-examples](https://github.com/whtcjdtc2007/anna-executa-examples)) ship a single-reader-with-dispatch pattern that handles both Agent requests **and** host responses to your reverse RPCs. Use it. --- ## 9a · Published executa shows no **Permission** button — `UPLOAD_NOT_GRANTED` / `-32201` **Symptom** You publish an App with a bundled executa via `anna-app apps publish` (or a standalone `executa publish`). The CLI reports success, the executa installs and runs — but its card on `/executa` has no **Permission** entry, so users cannot grant `host.upload` / `aps.*` / `llm.*`, and the first reverse-RPC call fails, e.g.: ```json { "code": -32201, "message": "Upload token missing — host did not authorize host/uploadFile", "data": { "errorCode": "UPLOAD_NOT_GRANTED" } } ``` **Cause** The permission UI and every reverse-RPC token gate read the capability declaration from the executa's **protocol manifest registered on the server** (`manifest_cache`), not from the binary itself. CLI versions before `0.1.50` never uploaded that manifest, so the server had no idea which capabilities your plugin declares. **Fix** Upgrade to `anna-app` ≥ `0.1.50` and keep the plugin's `describe` manifest next to `executa.json` as `manifest.json` (or point at it with the `executa.json` `manifest_file` field). `executa publish` / `apps publish` / `apps push` then sync it to the server on every publish — the CLI prints `protocol manifest synced (host capabilities: …)` and warns when the file is missing. For executas already published without a manifest, any of these heals the row: - re-publish with CLI ≥ `0.1.50`; - a successful install / reinstall / upgrade on any Agent (the platform now caches the manifest the Agent gets from `describe`); - manually pasting the `describe` JSON in **/executa → My Tools → Edit → Manifest**. Note the capability strings are validated against the platform allow-list at write time — a typo like `host.uploadFile` is now rejected with HTTP 400 instead of silently hiding the Permission entry. --- ## 10 · Sampling — `MAX_TOKENS_EXCEEDED` on a single small call **Symptom** A reasonable sampling request fails with `-32007 MAX_TOKENS_EXCEEDED` even though `maxTokens` is well under 8 192. **Cause** The cap is **cumulative across the same `invoke_id`**, not per call. Default total is 32 000 tokens. **Fix** Send fewer / smaller sampling calls per tool invocation, or ask the user to raise `sampling_grant.maxTokensTotal` in their Anna Admin panel (host caps it at 32 000 in v1). --- ## 11 · Storage — `cur["value"]` looks empty even on a successful read **Symptom** Your read-modify-write pattern silently overwrites previous data: ```python cur = await rpc("storage/get", {"scope": "tool", "key": "log"}) log = cur["value"] if cur["value"] else [] # ← always [] even after writes! ``` **Cause** Legitimate values include `0`, `""`, `false`, `[]`, `{}` — all falsy. Truthiness is the wrong check. The Agent guarantees an `exists` field on **both** hit and miss responses, exactly to avoid this trap. **Fix** Always branch on `exists`: ```python log = cur["value"] if cur.get("exists") else [] ``` See [Persistent Storage — Result shapes](/developers/tools/executa-storage#result-shapes). --- ## 12 · Storage — using the wrong scope or omitting it **Symptom** Data written by version 1 of your plugin is invisible to version 2; or two unrelated plugins clobber each other under the same key. **Cause** `scope` defaults to `"app"` when omitted. If you actually wanted plugin-private state, it ended up in the broader app namespace; if you wanted user-shared state, it ended up siloed by app. **Fix** Always pass `scope` explicitly: | Want | Pass | |---|---| | Plugin-private state | `scope: "tool"` | | Shared between views of the same Anna App | `scope: "app"` | | Visible across the user's whole drive | `scope: "user"` on any `files/*` or `storage/*` call | --- ## 13 · Long jobs — `emit_progress` events never show up **Symptom** Your tool runs fine under `anna.tools.invokeAsync`, but the app's progress bar never moves — no `tool_update` events arrive, no error anywhere. **Cause** Progress notifications are **silently dropped** whenever the host cannot (or will not) route them. The three usual reasons: 1. **Missing `invoke_id` correlation.** `executa/progress` is a JSON-RPC *notification* — the host matches it to its parent invoke solely via `params.context.invoke_id`. If you call the SDK's `emit_progress` outside a `bind_invoke(params)` block (Python) or forget to pass `invokeId` (Node) / `invokeID` (Go), the event has no owner and is dropped. Unknown or already-finished invoke ids are dropped too. 2. **Sync invoke.** Only `tools.invokeAsync` jobs have a progress channel. During a plain synchronous `tools.invoke` the notifications are dropped — the tool still works, there is just nowhere for progress to go. 3. **Rate limit.** 50 events/second per invoke; excess is dropped without feedback. Batch your updates (e.g. one per step, not one per row). **Fix** ```python # Python — bind once at the top of the handler: from executa_sdk import bind_invoke, emit_progress def handle_invoke(req_id, params): with bind_invoke(params): # ① correlation for i in range(1, total + 1): do_step(i) emit_progress("tool_update", # ② whitelisted type {"step": i, "total": total}) ``` Also remember: - Allowed `type` values are `progress` and `tool_update` only — anything else (including `completed` / `failed`) is coerced to `progress`; terminal states cannot be faked from the plugin. - Keep `data` small: the host stores at most **8 KB per event** and keeps the **latest 500** events per job (older ones fall out of the ring). - Progress is best-effort by contract. The authoritative job state is always `tools.getJob` — never gate your plugin's correctness on an event being delivered. See the official demo `anna-executa-examples/examples/anna-app-long-task-demo`. --- ## See also - [Lifecycle & Capability Negotiation](/developers/tools/executa-lifecycle) - [Protocol Specification](/developers/tools/executa-protocol) - [Sampling](/developers/tools/executa-sampling) - [Persistent Storage](/developers/tools/executa-storage) - [Binary Distribution](/developers/tools/executa-binary) --- # === Build a Skill === --- title: What is a Skill description: Skills are the declarative flavour of Executa: a folder of markdown that Anna loads on demand and turns into a LangChain tool. section: skills slug: skill-intro updated: 2026-04-23 estimated_minutes: 4 --- A **Skill** is the *declarative* flavour of [Executa](/developers/overview/concepts). It's a folder containing a `SKILL.md` plus optional supporting files (examples, templates, scripts, datasets) that teaches Anna *how* to do something. At runtime the loader registers each skill as a LangChain `@tool`; when the LLM picks it, the tool returns the skill's markdown body — along with an execution-mode hint and any declared dependencies — and the agent then uses its built-in `exec` / `command` tools to run any bash or Python the body recommends. > [!NOTE] > Skills do **not** execute code by themselves. The skill body is delivered to the LLM as instructions; running anything is the agent's job, via its existing execution tools. That is why `execution_mode` is a *hint* ("this skill is best run via bash") and not an interpreter selection. ## When to ship a Skill (vs. a Tool Executa) Both are Executas — same Hub, same draft → version → visibility lifecycle. The difference is the *shape* of the artifact. | Ship a **Skill** when… | Ship a **Tool** when… | |---|---| | You want to teach Anna a process, style, or workflow | You need to maintain a long-running process with credentials | | The work is mostly markdown + commands the agent can run via `exec` | You need bidirectional JSON-RPC, streaming, or complex SDK integrations | | You want users to read / fork / customise the body | You want a black-box contract behind a stable manifest | The two compose well: a `chart-generator` Skill teaches Anna *when and how* to render a chart, and may itself recommend calling a `pandas-tools` Tool Executa for heavier data wrangling. ## Anatomy ``` my-skill/ ├── SKILL.md # required — frontmatter + body ├── examples/ │ ├── input-1.md │ └── output-1.md ├── templates/ │ └── report.md.tpl └── README.md # optional — for humans browsing the source ``` ## A minimal SKILL.md ```markdown --- name: meeting-summary description: Turn raw meeting notes into a structured summary with decisions, action items, and open questions. metadata: {"matrix":{"emoji":"📝","execution_mode":"prompt","category_name":"productivity"}} --- # Meeting Summary Skill When the user provides raw meeting notes, produce a summary with three sections: ## Decisions - Bullet list of every decision the group made. ## Action Items - `[ ] Owner — task — due date` ## Open Questions - Bullet list of unresolved items. If owner or due date is missing, write `?` and surface it as an open question. ``` The body is markdown that the LLM receives when it calls the skill. Frontmatter has two required keys (`name`, `description`) and one structured `metadata` blob — see [Skill format](/developers/skills/skill-format). ## Where to next - **Format spec** — [Skill format](/developers/skills/skill-format). - **Run locally** — [Local development](/developers/skills/skill-local). - **Publish** — [Publishing](/developers/skills/skill-publish). --- --- title: Skill Format description: The frontmatter, metadata structure, and supporting files that make a Skill loadable. section: skills slug: skill-format updated: 2026-04-23 estimated_minutes: 6 --- A Skill is the declarative flavour of an [Executa](/developers/overview/concepts). Every Skill is a folder; its entry point is **`SKILL.md`** — markdown with YAML frontmatter, where one frontmatter key (`metadata`) carries a JSON blob describing execution mode and dependencies. ## Top-level frontmatter ```yaml --- name: short-kebab-name description: One-sentence description used at skill-discovery time. metadata: {"matrix":{ ... }} --- ``` | Field | Type | Required | Notes | |---|---|---|---| | `name` | string | yes | Lowercase kebab-case; defaults to the parent directory name if omitted | | `description` | string | yes | What the LLM uses to decide when to load the skill — write it as a search query the user might type | | `metadata` | JSON | no | One-line JSON blob (see below) carrying executable metadata | Top-level `version` / `author` are accepted but currently informational — versioning happens at publish time via the Executa version snapshot. ## The `metadata` blob The skill loader parses `metadata` as JSON. If the JSON has a top-level `matrix`, `openclaw`, or `nexus` key (in that order), the value of that key is used as the actual structured metadata; otherwise the JSON is consumed directly. Real example from the bundled `chart-generator` skill: ```yaml --- name: chart-generator description: "Use matplotlib and seaborn to create publication-quality charts…" metadata: {"matrix":{"emoji":"📈","execution_mode":"python","category_name":"data-analysis","requires":{"python_packages":["matplotlib","seaborn"]},"install":[{"id":"pip","kind":"pip","package":"matplotlib seaborn","label":"Install matplotlib & seaborn (pip)"}],"uninstall":[{"id":"pip","kind":"pip","command":"pip uninstall matplotlib seaborn","label":"Uninstall matplotlib & seaborn (pip)"}]}} --- ``` ### Recognized fields under `matrix` | Key | Type | Notes | |---|---|---| | `always` | boolean | Load this skill into every conversation (use sparingly — reserved for foundational tooling like `uv`) | | `skill_key` | string | Override identifier (defaults to `name`) | | `primary_env` | string | Required environment variable hint shown in onboarding | | `emoji` | string | Display icon | | `homepage` | string | Documentation link | | `category_name` | string | Free-form group used by the Skill catalogue (`productivity`, `data-analysis`, `network`, `office`…) | | `os` | array | Limit availability (`["macos", "linux", "windows"]`) | | `execution_mode` | enum | `prompt` (default) / `bash` / `python` / `api` / `hybrid` | | `parameters` | array | Optional input parameters declared like Executa tool parameters | | `requires` | object | Dependency declarations (see below) | | `install` | array | Install recipes (see below) | | `uninstall` | array | Matching uninstall recipes | ### `requires` Declare what the skill needs available at runtime. The agent surfaces missing requirements during onboarding: ```json "requires": { "bins": ["jq"], // executables that MUST be on PATH "any_bins": ["uv", "curl"], // satisfied by ANY one being present "env": ["GITHUB_TOKEN"], // required environment variables "config": ["github.host"], // required config keys "python_packages": ["matplotlib"] // pip-installable packages } ``` ### `install` / `uninstall` A list of recipes; the agent picks the first one matching the host OS and an available installer. ```json "install": [ {"id": "brew", "kind": "brew", "formula": "jq", "bins": ["jq"], "os": ["macos"], "label": "Install jq (brew)"}, {"id": "apt", "kind": "apt", "package": "jq", "os": ["linux"], "label": "Install jq (apt)"}, {"id": "pip", "kind": "pip", "package": "matplotlib seaborn", "label": "Install via pip"} ] ``` | Field | Notes | |---|---| | `id` | Stable identifier within the recipe list | | `kind` | One of `brew`, `pip`, `apt`, `npm`, `go`, `uv`, `download`; uninstall recipes also accept `shell` | | `formula` / `package` / `command` | Provided depending on `kind`; `command` is a raw shell command for `shell` / `download` | | `bins` | Executables this recipe makes available (used to verify success) | | `os` | Restrict the recipe to specific OSes | | `label` | UI string | Uninstall recipes mirror the install side and may use a `command` to run a custom shell uninstall. ## Body conventions When the LLM picks the skill, the runtime returns the body of `SKILL.md` to it (preceded by an execution-mode hint and any declared dependencies). It is not a script the runtime executes — it's instructions the LLM reads. Treat it as prompt engineering: 1. **Lead with intent.** First paragraph: what the skill does, plainly. 2. **Be explicit about output format** when in `prompt` mode. 3. **Provide one or two inline examples**; point to `examples/` for longer ones. 4. **For `bash` / `python` modes**, fence ready-to-run commands in code blocks. The LLM will copy those commands into a follow-up call to the agent's `exec` / `command` tool to run them in the workspace sandbox — the skill loader itself does not execute fenced blocks. 5. **Reference supporting files by relative path** — `templates/report.md.tpl`. > [!TIP] > Ambiguity in the body becomes ambiguity in the output. When in doubt, add a constraint. ## Supporting files - `examples/` — input/output pairs the model can imitate. - `templates/` — file scaffolds with placeholders. - `data/` — small reference datasets (lookup tables, glossaries). - `scripts/` — helper scripts the body references. No manifest is needed for these — reference them by relative path from the body. ## Reference The platform ships bundled skills you can study (chart-generator, csv-data-tools, jq, curl, pdf-tools, postgres-client, …) — open one in the Skill Hub and copy its `SKILL.md` structure. --- --- title: Local Development description: Build and iterate on a skill on your own machine before publishing. section: skills slug: skill-local updated: 2026-04-23 estimated_minutes: 5 --- The fastest iteration loop is: **drop the folder into a discoverable skills directory → reload the agent → trigger the skill → revise.** ## 1. Where the loader looks The Nexus skill loader resolves the **bundled skills directory** by trying these locations in order and using the first one that exists: | Order | Source | Path | Purpose | |---|---|---|---| | 1 | Env override | `$MATRIX_SKILLS_DIR` | Point at any folder of skills (recommended for development) | | 2 | In-tree bundled | `/skills/` | Built-in skills shipped with Nexus (e.g. `chart-generator`, `jq`, `curl`) | | 3 | Package bundled | ships inside the platform package | Internal fallback | In addition, **workspace skills** under `/skills/` are loaded separately by `load_workspace_skills(workspace_path)` and merged on top of the bundled set (workspace entries win on name collision via `merge_skills`). Each immediate subdirectory containing a `SKILL.md` is a skill (the loader recursively walks the tree looking for `SKILL.md` files). On first access the registry builds an index of skill name → file path; the body is parsed lazily the first time a given skill is requested. ```bash export MATRIX_SKILLS_DIR=~/dev/anna-skills mkdir -p "$MATRIX_SKILLS_DIR/my-skill" $EDITOR "$MATRIX_SKILLS_DIR/my-skill/SKILL.md" ``` Restart the agent (or hit the reload endpoint) and trigger the skill by asking Anna something matching its frontmatter `description`. ## 2. Pick the execution mode The `metadata.matrix.execution_mode` field is a **hint** the runtime injects above the skill body so the LLM knows how the skill is intended to be run. The skill loader itself does not execute anything — the LLM uses the hint to decide which built-in agent tool (typically `exec` / `command`) to call next. | Mode | Hint shown to the LLM | |---|---| | `prompt` (default) | "Follow the instructions in the body" — no execution implied | | `bash` | "Run the example commands via `exec` (bash/shell)" | | `python` | "Run the Python via `exec`, preferring `uv run --with python script.py`" | | `api` | "This skill describes an HTTP call — use `exec` to run `curl` or similar" | | `hybrid` | "Mix bash and Python as the body suggests" | For `bash` / `python` skills, declare any required `bins` / `python_packages` in `requires` plus matching `install` recipes so onboarding can ensure dependencies are present before the agent tries to run them. When any loaded skill is `python` mode, the runtime additionally injects a section into the system prompt instructing the agent to prefer `uv` over the system `pip` (see `src/skills/converter.py`). ## 3. Smoke-test checklist - [ ] The frontmatter `description` is the kind of question a user would actually type. (If your skill never loads, this is almost always the cause.) - [ ] Output matches your spec on three different inputs. - [ ] Edge cases (empty input, malformed input) degrade gracefully. - [ ] All `requires` items resolve on a clean machine, or the install recipes succeed. - [ ] Supporting files referenced from the body actually exist at those paths. ## chart-generator walkthrough A real bundled skill looks like this: ``` skills/chart-generator/ ├── SKILL.md └── examples/ ``` Frontmatter (truncated): ```yaml --- name: chart-generator description: "Use matplotlib and seaborn to create publication-quality charts…" metadata: {"matrix":{"emoji":"📈","execution_mode":"python","category_name":"data-analysis","requires":{"python_packages":["matplotlib","seaborn"]},"install":[{"id":"pip","kind":"pip","package":"matplotlib seaborn"}]}} --- ``` The body teaches Anna to: 1. Inspect the user's data. 2. Suggest the most appropriate chart type. 3. Emit a Python snippet that calls `matplotlib` / `seaborn` to render the chart. 4. Save the output as `chart.png` (or SVG/PDF) in the workspace. When the LLM calls the skill, the runtime returns the body to it. The LLM then issues an `exec` call running `uv run --with matplotlib --with seaborn python script.py` (or installs the packages via the declared `install` recipe first). Browse the bundled `chart-generator` skill in the Skill Hub for the live source. ## Next - **Publish your skill** — [Publishing](/developers/skills/skill-publish). --- --- title: Publishing a Skill description: Submit your skill so other users can discover and install it. section: skills slug: skill-publish updated: 2026-04-23 estimated_minutes: 5 --- Once your skill is stable, publishing puts it in the Explore catalogue alongside the platform-bundled skills. Because **a Skill is just an Executa with `executa_type="skill"`**, it shares the *exact same* draft / version / visibility pipeline as a Tool Executa — same wizard, same REST surface, same Hub. ## 1. Prepare - [ ] `SKILL.md` has the required frontmatter (`name`, `description`). - [ ] `metadata.matrix` declares `execution_mode`, `category_name`, and (if applicable) `requires` / `install` / `uninstall`. - [ ] Body is self-contained — no references to files outside the skill folder. - [ ] You have a one-line and one-paragraph description ready for the listing. - [ ] Optional: a screenshot/GIF showing the skill in action. > [!WARNING] > Don't include credentials, `.env` files, or anything you wouldn't paste into a public gist. The skill body ships verbatim to anyone who installs it. ## 2. Create the Skill via the wizard The `/executa` page has a draft-first flow shared by both Executa flavours — you pick `Skill` at step 1 and the rest of the wizard adapts: ``` POST /api/v1/executas/my/drafts → reserves tool_id (executa_type="skill") PATCH /api/v1/executas/my/drafts/{id} → fill in skill_content + metadata POST /api/v1/executas/my/drafts/{id}/commit → promote draft → Skill Executa ``` The UI walks through: 1. **Name & type** — pick `Skill`. The server returns a `tool_id` like `skill-{author_handle}-{slug}-{uniq}` you can copy into App manifests. 2. **Body & metadata** — paste the markdown of `SKILL.md`. The wizard parses your frontmatter (`metadata.matrix`) and surfaces `execution_mode`, `category_name`, and dependency declarations as form fields. 3. **Capabilities & docs** — logo, README, sample prompts. 4. **Visibility** — `private`, `app_bundled`, or `public`. 5. **Commit** — the draft becomes a real Skill Executa. Drafts auto-expire after 24 h if you don't commit (server-enforced TTL). Direct REST mirrors are available for scripting: | Method | Path | Purpose | |---|---|---| | `GET` | `/api/v1/executas/my/skills` | List your Skill Executas | | `POST` | `/api/v1/executas/my/skills/import` | Create a Skill from a JSON payload (server-side validates the frontmatter) | | `GET` | `/api/v1/executas/my/skills/{id}/detail` | Fetch full Skill detail | | `PUT` | `/api/v1/executas/my/skills/{id}` | Update body / metadata | | `DELETE` | `/api/v1/executas/my/skills/{id}` | Delete the Skill | | `GET` | `/api/v1/executas/my/skills/{id}/export` | Round-trip the skill back to a payload you can re-import | | `POST` | `/api/v1/executas/my/skills/{id}/publish` | Promote to `visibility=public` (Pro / Max) | | `POST` | `/api/v1/executas/my/skills/{id}/unpublish` | Revert to `private` | | `POST` | `/api/v1/executas/my/skills/{id}/visibility` | Set visibility explicitly (`private` / `app_bundled` / `public`) | | `POST` | `/api/v1/executas/my/skills/{id}/versions` | Freeze a new immutable version snapshot | ## 3. Visibility model | Visibility | Where it appears | Who can install | |---|---|---| | `private` | Only your `/executa` workspace | Only you | | `app_bundled` | Hidden from Explore, installable as part of any Anna App that bundles it | Anyone who installs the host App | | `public` | Listed in the Explore Hub | Anyone | Use `app_bundled` when the skill only makes sense alongside a particular App. ## 4. Versioning Every `POST /my/skills/{id}/versions` call freezes the current body + metadata into an immutable `ExecutaVersion`. If nothing changed since the last published version, the call returns `409 Conflict` so you don't ship empty updates. Apps that pin a `min_version` see content frozen at that snapshot; users on auto-update get the latest snapshot at install time. ## 5. Bundle into an App The highest-leverage distribution is being part of an Anna App. See [What is an Anna App](/developers/apps/app-intro) for how Apps bundle skills, tools, and prompts into a one-click install. > [!NOTE] > Self-hosted catalogues are on the roadmap. For now everything goes through the public Explore Hub review. --- # === Build an Anna App === --- title: What is an Anna App description: Apps bundle a curated set of Executas plus prompt instructions into a one-click install for end users. section: apps slug: app-intro updated: 2026-04-29 estimated_minutes: 4 --- An **Anna App** is the highest-level packaging unit in the Anna App Store. It bundles: - A curated set of **Executas** (Anna's tool/skill plugins) the app depends on. - Prompt instructions (`system_prompt_addendum`, `user_message_prefix_template`) that steer the assistant when the user `#`mentions the app in a chat. - **Listing metadata** (name, slug, category, tagline, description, logo, screenshots, homepage, pricing model) that powers the App Store entry. - *(Optional, manifest `schema: 2`)* an **App UI bundle** — a static SPA (HTML/JS/CSS/wasm/fonts) that is uploaded to Anna and rendered inside a sandboxed `