# Executa Reference Documentation Issues
Hi Anna team,
This feedback is based on the staging reference docs, `~/anna-executa-examples`, the installed `@anna-ai/cli@0.1.29`, production/internal Executa sources under `~/Anna/_internal/src/executa`, and small local probes run through `anna-app executa dev`.
Local probe summary: I used a small Tool Executa plugin to trigger unknown method, invalid params, internal error, sampling reverse-RPC, and storage reverse-RPC paths. The probe reproduced `-32601`, `-32602`, `-32603`, `-32008`, `-32010`, `-32021`, `-32022`, and `-32023` in the local CLI bridge.
## Page 1
### 1. `There is no SDK and no embedded runtime`
`anna-executa-examples` has SDKs under:
- `~/anna-executa-examples/sdk/python`
- `~/anna-executa-examples/sdk/nodejs`
- `~/anna-executa-examples/sdk/go`
The examples README says these are “Reference SDKs used by the sampling examples”.
This should be `no required SDK`, not `no SDK`.
### 2. `Two declarative flavours ship today: Tool (executable JSON-RPC) and Skill (markdown recipe).`
Tool is not declarative. Tool is an executable JSON-RPC process.
This should say that Anna currently supports two Executa types: Tool and Skill.
## Page 2
### 3. Tool Executa: `initialize`
Current doc:
> v2 handshake. Host sends `{protocolVersion: “2.0”, host_capabilities: {“llm.sample”: true}}`. Plugin must echo `protocolVersion` and advertise `client_capabilities`…
But examples are not consistent with that exact shape.
Storage example returns:
```json
{
“protocolVersion”: “2.0”,
“capabilities”: {
"storage": {
"kv": true,
"files": true
}
}
}
```
Evidence: `~/anna-executa-examples/examples/python/storage-notebook/storage_notebook.py:260`
Sampling example returns:
```json
{
“protocolVersion”: “2.0”,
“client_capabilities”: {
"sampling": {}
},
“capabilities”: {}
}
```
Evidence: `~/anna-executa-examples/examples/python/sampling-summarizer/sampling_summarizer.py:269`
CLI local runner also sends initialize params from `HOST_INITIALIZE_PARAMS`.
Evidence: `~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist/runner-BuYbm-ex.js`
### 4. `health` card
The examples do not all return the same `status`.
- Basic example returns `status: “healthy”`: `~/anna-executa-examples/examples/python/basic-tool/example_plugin.py:333`
- Sampling example returns `status: “healthy”`: `~/anna-executa-examples/examples/python/sampling-summarizer/sampling_summarizer.py:283`
- Storage example returns `status: “ok”`: `~/anna-executa-examples/examples/python/storage-notebook/storage_notebook.py:288`
- CLI/minimal-style example returns `status: “ok”`: `~/anna-executa-examples/examples/anna-app-focus-flow/executas/focus-session-python/focus_session_plugin.py:316`
### 5. `shutdown`
Basic example and CLI template-style plugins return `-32601 Method not found` for `shutdown`.
So `shutdown` looks reserved/optional in practice. The real shutdown signal is stdin EOF.
### 6. `agent/session.create · run · cancel · history · delete`
This method list is incomplete. There are also:
- `agent/session.list`
- `agent/session.refresh`
Evidence:
- `~/anna-executa-examples/examples/anna-app-llm-demo/executas/llm-via-executa-python/README.md:102`
- `~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist/agent-CaZVCPs6.js`
### 7. `agent/complete`
`executa-agent-demo` describes this as single-shot stateless completion via `agent/complete`.
It also declares:
```json
[“llm.sample”, “llm.agent.auto”]
```
Evidence:
- `~/anna-executa-examples/examples/python/executa-agent-demo/executa_agent_demo.py:18`
- `~/anna-executa-examples/examples/python/executa-agent-demo/executa_agent_demo.py:71`
So the doc line “same auth chain as `agent/session.*`” is not precise enough unless it also states the exact capabilities required.
### 8. `host_capabilities[]` example includes `“storage”`
The examples use concrete capability names:
```json
[“aps.kv”, “aps.files”]
```
Evidence:
- `~/anna-executa-examples/examples/python/storage-notebook/storage_notebook.py:76`
- `~/anna-executa-examples/examples/anna-app-aps-files-demo/executas/files-via-executa-python/files_via_executa_plugin.py:79`
`“storage”` is not what the examples use.
## Tool Parameter Schema
### 9. `name`, `type`, and `description` are required
`ParameterSchema.from_dict` directly reads:
```python
name = data[“name”]
type = ParameterType(data[“type”])
description = data[“description”]
```
Evidence:
- `~/Anna/_internal/src/executa/protocol.c:6311`
- `~/Anna/_internal/src/executa/protocol.c:6325`
- `~/Anna/_internal/src/executa/protocol.c:6362`
### 10. `default`: `Used by the host when LLM omits the arg.`
Evidence is not enough for this sentence.
The protocol code shows that `default` is put into the exported JSON Schema, so the LLM/function-calling layer can see it. I did not find evidence that the host always fills missing invoke arguments with default values before calling the plugin.
Several examples also keep default handling inside the plugin function itself.
### 11. `items / items_type (array only)`
`Required when type=“array”` is too strong.
The parsing layer does not require it. If omitted, `to_json_schema` falls back to:
```json
{“items”: {“type”: “string”}}
```
Evidence: `~/Anna/_internal/src/executa/protocol.c:8126`
The “host defaults to string” part is correct. I did not find code evidence for “and warns”, so that part should be removed unless the warning code can be located.
### 12. `object` type needs a limitation note
`type` enum can include `object`, but `ParameterSchema.from_dict` does not read nested object schema fields such as:
- `properties`
- nested `required`
- `additionalProperties`
So this is not full JSON Schema support.
## Invoke Envelope
### 13. `params.sampling_token (v2)`
This should be `params.context.sampling_token`, not top-level `params.sampling_token`.
Evidence:
- `~/Anna/_internal/src/executa/loader.c:1745`
- `~/Anna/_internal/src/executa/loader.c:18313`
### 14. Other context tokens
The loader also passes:
- `params.context.storage_token`: for `storage/*` and `files/*`
- `params.context.image_token`: for `image/generate` and `image/edit`
- `params.context.upload_token`: for `host/uploadFile`
Evidence:
- `~/Anna/_internal/src/executa/loader.c:1750`
- `~/Anna/_internal/src/executa/loader.c:1752`
- `~/Anna/_internal/src/executa/loader.c:1756`
- `~/Anna/_internal/src/executa/loader.c:26781`
So storage/files are not using `sampling_token`; they use `storage_token`.
## JSON-RPC Error Codes
### 15. `-32700 Parse error`
This is not only host-emitted. `example_plugin.py` also emits it:
Evidence: `~/anna-executa-examples/examples/python/basic-tool/example_plugin.py:345`
```python
write_response({
"jsonrpc": "2.0",
"id": None,
"error": {"code": -32700, "message": "Parse error"},
})
```
## Sampling Error Codes
### 16. Missing `-32010 SAMPLING_UNSUPPORTED_RESPONSE_FORMAT`
The source has:
```python
SAMPLING_ERR_UNSUPPORTED_RESPONSE_FORMAT = -32010
```
Evidence:
- `~/anna-executa-examples/sdk/python/executa_sdk/sampling.py:64`
- `~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist/sampling-DwV7VPfT.js:23`
I also reproduced `-32010` through `anna-app executa dev` using `–sampling-unsupported-format`.
### 17. `maxTokens > 8192`
The doc currently places this under `-32004 SAMPLING_INVALID_REQUEST`.
Production/internal source maps over-limit `maxTokens` to `SAMPLING_ERR_MAX_TOKENS_EXCEEDED`, i.e. `-32007`.
Evidence:
- `~/Anna/_internal/src/executa/sampling.c:6744`
- `~/Anna/_internal/src/executa/sampling.c:6898`
- `~/Anna/_internal/src/executa/sampling.c:6907`
- `~/Anna/_internal/src/executa/sampling.c:6916`
Note: local CLI mock sampling did not enforce this cap in my probe, so this specific point is from production/internal source.
### 18. `no invoke_id`
Source shows that “no invoke_id” also goes through `-32008 SAMPLING_NOT_NEGOTIATED`.
Evidence:
- `~/Anna/_internal/src/executa/sampling.c:12658`
- `~/Anna/_internal/src/executa/sampling.c:12671`
- `~/Anna/_internal/src/executa/sampling.c:12679`
## Storage Reverse-RPC Error Codes
### 19. Missing `STORAGE_ERR_TIMEOUT = -32030`
The Python SDK has:
```python
STORAGE_ERR_TIMEOUT = -32030
```
This is an SDK-local timeout code when the SDK waits for a response but does not receive one.
Evidence:
- `~/anna-executa-examples/sdk/python/executa_sdk/storage.py:80`
- `~/anna-executa-examples/sdk/python/executa_sdk/storage.py:191`
### 20. Missing key behavior in `StorageClient.get()`
The SDK comment says `StorageClient.get()` normalizes a missing key to:
```json
{“value”: null, “exists”: false}
```
So it is not always necessarily exposed as `-32022`.
Evidence:
- `~/anna-executa-examples/sdk/python/executa_sdk/storage.py:225`
- `~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist/storage-CKTmE87u.js:129`
### 21. Storage invalid request code
The doc says:
```text
-32028 INVALID_REQUEST
```
But CLI local bridge has:
```js
const STORAGE_ERR_INVALID_REQUEST = -32020;
```
Evidence: `~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist/storage-CKTmE87u.js:8`
This needs canonical confirmation, because CLI local dev and the reference page disagree.
## Agent Reverse-RPC Error Codes
### 22. `_MAX_FRAMES_PER_RUN = 4096`
The doc says the 4096-frame cap belongs to `-32045 QUOTA_EXCEEDED`.
Production `agent.c` throws `AGENT_ERR_PROVIDER_ERROR`, i.e. `-32046`, when `_MAX_FRAMES_PER_RUN = 4096` is exceeded.
CLI 0.1.29 local dev bridge maps it to `AGENT_ERR_RUN_TOO_LARGE = -32047`.
Evidence:
- `~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist/agent-CaZVCPs6.js:11`
- `~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist/agent-CaZVCPs6.js:12`
- `~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist/agent-CaZVCPs6.js:13`
- `~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist/agent-CaZVCPs6.js:194`
## Timeouts And Lifecycle Limits
### 23. `INITIALIZE_TIMEOUT = 5s`
Production Executa uses 5s.
But `anna-app executa dev` local runner defaults initialize timeout to 8s:
```js
const initTimeout = this.opts.initTimeoutMs ?? 8e3;
```
Evidence: `~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist/runner-BuYbm-ex.js:72`
So the doc is correct for production, but not for local `anna-app executa dev`.
## Large Response / File Transport
### 24. 512 KiB vs 2 MiB
The examples use 512 KiB as the file transport threshold, but the hard reader cap is 2 MiB.
Evidence:
- `MAX_STDIO_MESSAGE_BYTES = 512 KiB`: `~/Anna/_internal/src/executa/protocol.c:19512`
- `MAX_READLINE_BYTES = 2 MiB`: `~/Anna/_internal/src/executa/protocol.c:19521`
- Loader overlong-line handling: `~/Anna/_internal/src/executa/loader.c:336`
Production loader supports `__file_transport`:
- `_resolve_file_transport`: `~/Anna/_internal/src/executa/loader.c:12564`
- response read loop: `~/Anna/_internal/src/executa/loader.c:14189`
- deletes file with `os.unlink`: `~/Anna/_internal/src/executa/loader.c:13177`
Examples implement the pointer envelope:
- Python basic example: `~/anna-executa-examples/examples/python/basic-tool/example_plugin.py:383`, `~/anna-executa-examples/examples/python/basic-tool/example_plugin.py:397`
- Node example: `~/anna-executa-examples/examples/nodejs/example_plugin.js:389`, `~/anna-executa-examples/examples/nodejs/example_plugin.js:401`
Also, `anna-app executa dev` local runner does not appear to resolve `__file_transport`; its line handler only processes `method`, `id`, `error`, and `result`.
Evidence: `~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist/runner-BuYbm-ex.js:173`
So 512 KiB is a soft threshold, while 2 MiB is the hard reader cap.
## Hard Rules
### 25. `describe result is bare`: `KeyError: ‘name’` is stale
Current text:
> Return the manifest dict directly. `_ok(id, {“manifest”: …})` → `KeyError: ‘name’`, plugin gets dropped.
Current `ToolManifest.from_dict` uses:
```python
display_name = data.get(“display_name”) or “”
```
It does not directly read `data[“name”]`.
Evidence: `~/Anna/_internal/src/executa/protocol.c:8923`
Node example also says top-level `name` is no longer declared in the manifest and identity comes from server-assigned `tool_id`.
Evidence: `~/anna-executa-examples/examples/nodejs/example_plugin.js:38`
However, stale comments still exist in examples, for example:
Evidence: `~/anna-executa-examples/examples/python/storage-notebook/storage_notebook.py:283`
The key issue is still correct: describe result should be the bare manifest object, not wrapped as `{manifest: …}`. But the `KeyError: ‘name’` explanation is no longer accurate.
## Source-Of-Truth Note
There are three related but not always identical sources:
- production/internal Anna runtime: `~/Anna/_internal/src/executa`
- local CLI dev bridge: `~/.nvm/versions/node/v22.22.3/lib/node_modules/@anna-ai/cli/dist`
- examples and SDKs: `~/anna-executa-examples`
Some discrepancies above are production-vs-local-runner differences, not necessarily the same bug category.