# Feedback on Anna Developer Reference HOST API docs: several pages are inconsistent with current CLI / runtime / examples **URL:** \ **Category:** Developers\ **Created:** [June 15, 2026, 8:50am UTC](https://forum.anna.partners/t/feedback-on-anna-developer-reference-host-api-docs-several-pages-are-inconsistent-with-current-cli-runtime-examples/103 "2026-06-15T08:50:29Z")\ **Posts on this page:** 2\ **Page:** 1
**Author:** ![HappyLight](https://avatars.discourse-cdn.com/v4/letter/h/7feea3/32.png) [@HappyLight](https://forum.anna.partners/u/HappyLight)\ **Post date:** [June 15, 2026, 8:50am UTC](https://forum.anna.partners/t/feedback-on-anna-developer-reference-host-api-docs-several-pages-are-inconsistent-with-current-cli-runtime-examples/103/1 "2026-06-15T08:50:29Z")
Hi Anna team, I recently reviewed the HOST API section of the Anna Developer Reference, mainly covering these pages and subpages: - `agent.*` - `chat.*` - `llm.*` - `image.*` - `upload.*` - `storage.*` - `llm.embed` - `files.*` - `tools.*` During the review, I cross-checked the docs against my locally installed Anna CLI, `@anna-ai/app-runtime`, `@anna-ai/app-schema`, CLI templates, README files, and Anna App examples in the repository. Overall, the Reference already covers much of the Host API surface, but I found several issues where pages appear outdated, use inconsistent naming, describe the permission model inaccurately, include misleading examples, or document response shapes that do not match current examples/SDK behavior. ## Issues 1. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-agent) Issue: The page lists only 5 documented symbols, but the current Host API also exposes `agent.session.list` and `agent.session.refresh`. Impact: Developers may think they cannot enumerate, recover, or refresh existing agent sessions. This can lead to duplicated sessions or poor handling of iframe reloads and long idle periods. Suggestion: Update the count to 7 documented symbols and add `agent.session.list`, `agent.session.refresh`, and their recovery/refresh semantics. 2. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-agent) Issue: The ACL description says `manifest.permissions` must declare `"host.agent"`, which does not match the current CLI/example runtime ACL behavior. Impact: Developers may incorrectly think root `permissions[]` controls Host API authorization and miss the actual `ui.host_api.agent` grant. Suggestion: Explain that runtime ACL is controlled by `manifest.ui.host_api.agent.session`. If `permissions[]` is only for display/audit, document that separately. 3. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-agent/agent-session-create) Issue: The header version appears outdated: `anna-app-runtime v0.2.0 / dispatcher 0.3.0`. Impact: Developers may misjudge the current Host API capability boundary, especially around recovery, refresh, and re-attaching sessions. Suggestion: Update the card page version label and also document the relationship with `list` / `attach` / `refresh`. 4. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-agent/agent-session-create) Issue: The `create` return value omits lifecycle and tool-surface fields currently shown in runtime examples. Impact: Developers may not know to read lifecycle fields or `inherit_host_tools`, making it harder to determine whether a session is near expiry or can actually use tools. Suggestion: Add `inherit_host_tools`, `expires_at`, `max_lifetime_at`, `idle_ttl_seconds`, and `session_expires_in`, with compatibility notes for older hosts. 5. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-agent/agent-session-create) Issue: `granted_tools` is described as an “advisory list from manifest.ui.host\_api.agent.tools”, which differs from current examples that emphasize a runtime-accurate tool surface. Impact: Developers may treat `granted_tools` as just a UI hint and not as a closer-to-runtime indicator of actual tool availability. Suggestion: Describe `granted_tools` / `inherit_host_tools` as authoritative runtime hints for executable tool access, or at least more accurate than the static manifest alone. 6. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-agent/agent-session-run) Issue: The stream event names used in the example may be outdated. Impact: Developers copying the example may not receive expected tokens or may miss `run_meta` tool-authorization warnings. Suggestion: Update the example event names and at least document recommended handling for `run_meta`, `token`, `complete`, and `error`. 7. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-agent/agent-session-run) Issue: Needs confirmation: the `system` parameter name may be outdated; local examples recommend per-run `systemPrompt`. Impact: Developers may pass the wrong field and the per-run system prompt may not take effect. Suggestion: Confirm the current Host API field. If `systemPrompt` is now recommended, rename the field or document it as an alias. 8. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-agent/agent-session-history) Issue: The return type is internally inconsistent. The Signature says `content: string`, while Returns says `content` may be a structured list / opaque objects. Impact: Frontend developers may hard-code string rendering and then crash or render incorrectly for multimodal messages. Suggestion: Change the signature to `content: string | unknown[] | unknown`, or clearly document the current stable shape. 9. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-chat) Issue: The page lists 3 documented symbols, but there are no clickable detail pages and no signatures, parameters, return values, errors, or authorization field documentation. Impact: Developers cannot tell whether `write_message` should receive `{ role, content }` or another shape, and cannot know the parameters/return structures for `read_history` / `append_artifact`. Suggestion: Add signatures, parameters, return values, errors, and examples for the three methods. If detail pages are not ready, provide minimal usable call shapes on the current page. 10. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-chat) Issue: The page does not explain that runtime authorization must enable specific methods through `manifest.ui.host_api.chat`. Impact: Developers may only add `chat.write_message` to root `permissions`, forget `ui.host_api.chat`, and hit runtime denied errors. Suggestion: Add a manifest example such as `"host_api": { "chat": ["write_message"] }`, and explain that `read_history` / `append_artifact` also need to be explicitly listed. 11. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-llm) Issue: The ACL description says `manifest.permissions` must declare `"host.llm"`, which does not match the current CLI/example runtime ACL behavior. Impact: Developers may incorrectly think root `permissions[]` controls LLM Host API authorization and miss the actual `ui.host_api.llm` grant. Suggestion: Explain that runtime ACL is controlled by `manifest.ui.host_api.llm`. If `permissions[]` is only for display/audit, document that separately. 12. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-llm/llm-complete) Issue: The header version appears outdated: `anna-app-runtime v0.2.0 / dispatcher 0.3.0`. Impact: Developers may misjudge current runtime/dispatcher capabilities and error behavior. Suggestion: Update the detail page version label to the current release chain, or remove version numbers that easily become stale. 13. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-llm/llm-complete) Issue: The return signature marks `_meta` as always present, but local mocks/examples/SDK docs do not guarantee `_meta`. Impact: Developers may directly read `reply._meta.quotaConsumed` and crash in mock mode, older hosts, or partial implementations. Suggestion: Mark `_meta` as optional, recommend optional chaining, and specify which environments/versions guarantee it. 14. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-image) Issue: The App Host API permission section appears to describe Anna App `ui.host_api.image` as root `manifest.permissions` entries `"llm.image"` / `"llm.image.edit"`. Impact: Developers may configure root `permissions` as shown but still not get access to `anna.image.*`. Suggestion: Change it to `manifest.ui.host_api.image: ["generate", "edit"]`. If Executa capabilities are relevant, document `host_capabilities: ["llm.image", "llm.image.edit"]` separately. 15. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-image/image-generate); [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-image/image-edit) Issue: The subpages are labeled `ANNA-APP-RUNTIME V0.4`, which does not match the locally installed runtime version. Impact: Developers may think the current Host API is still at runtime v0.4. Suggestion: Update to the current runtime version, or write it as “introduced in v0.4.0 / current latest v0.8.0”. 16. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-image/image-generate) Issue: `SDK default per-call timeout is 70s` does not match the current App runtime default. Impact: Developers may misunderstand timeout behavior or unnecessarily set `timeoutMs`. Suggestion: Change the default to 180s. If 70s was old behavior, mark the version range. 17. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-image); [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-image/image-generate); [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-image/image-edit) Issue: The upload persistence flow is described inconsistently. Some places imply that `upload.confirm` or `upload.negotiate` alone can complete persistence. Impact: Developers may call `upload.confirm` without first calling `upload.negotiate`, or may think `upload.negotiate` itself already persists the file. Suggestion: Standardize the flow: small files use `upload.inline`; large files use `upload.negotiate + PUT + upload.confirm`. 18. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-image/image-generate); [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-image/image-edit) Issue: Needs confirmation: examples use `APP_NOT_GRANTED`, `APP_QUOTA_EXCEEDED`, etc., while local runtime comments refer to App RPC error codes such as `APP_ERR_NOT_GRANTED`, `APP_ERR_QUOTA_EXCEEDED`. Impact: If the actual host returns `APP_ERR_*`, the documented catch examples will fail to match. Suggestion: Verify the dispatcher’s actual return codes. If they are `APP_ERR_*`, update the documented error codes and examples. 19. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-upload/upload-negotiate) Issue: The `upload.negotiate` signature omits the `size_bytes` parameter and says the negotiate stage does not validate `size_bytes`. Impact: Developers following the page may omit the size field, causing request failures or loss of size preflight checks. Suggestion: Add `size_bytes` to the signature and parameter table. Clarify whether it is used only for preflight/signing/recording, or also checked again during confirm. 20. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-upload/upload-inline); [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-upload/upload-confirm) Issue: Needs confirmation: return fields are documented as `bytes_size` / `expires_in`, but local SDK/examples commonly use `size_bytes` / `expires_at`. Impact: Developers may read `bytes_size` or `expires_in` and get undefined if the actual response uses `size_bytes` / `expires_at`. Suggestion: Verify the actual App Host API response. If the current response uses `size_bytes` / `expires_at`, update the signatures and return docs. 21. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-storage) Issue: The ACL description mixes Anna App Host API `ui.host_api.storage`, root `permissions`, and Executa `host_capabilities` / `aps.scope.*`. Impact: Developers may configure `"host.storage"` or `host_capabilities`, but the Anna App iframe still will not get access to `anna.storage.*`. Suggestion: Explain that App iframe authorization uses `manifest.ui.host_api.storage: ["get", "set", "delete", "list"]`; document `storage.read/write` and Executa `aps.*` capabilities separately. 22. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-embed/llm-embed) Issue: The timeout recommendation is misleading: the page says large batches/cold starts may need explicit `{ timeoutMs: 60_000 }`, but the current runtime default for `llm` is already 180s. Impact: Developers who follow the example and explicitly set 60s may make the call more likely to time out than with the default. Suggestion: Document the default as 180s. If showing an override, use a value greater than the default or aligned with the actual host limit. 23. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-files) Issue: The ACL description mixes Anna App Host API `ui.host_api.files`, root `permissions`, and Executa `host_capabilities` / `aps.files`. Impact: Developers may configure `"host.files"` or `host_capabilities`, but the Anna App iframe still will not get access to `anna.files.*`. Suggestion: Explain that App iframe authorization uses `manifest.ui.host_api.files`; document `host.files` install/display permissions and Executa `aps.files` capabilities separately. 24. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-files) Issue: Needs confirmation: the page describes `files.*` as a usable APS object API, but the locally installed `methods.json` still marks `files.delete/download_url/list/upload_finalize/upload_init` as `_h_not_implemented`, `stub: true`. Impact: Developers may hit `not_implemented` in local CLI or some host environments, while the page does not state that APS handlers or `anna-app dev --storage aps` are required. Suggestion: Clarify whether `files.*` is currently stable. If it depends on APS backend/launch options, explicitly document that the fallback returns `not_implemented`. 25. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-files/files-upload-init) Issue: The example code passes an obviously wrong `path` to `upload_finalize`; it generates a new UUID or empty string instead of reusing the `upload_init` path. Impact: Developers copying the example may fail finalize because the pending row cannot be found or the path is inconsistent. Suggestion: Save and reuse the same `path`, for example `const path = ...`, and pass that variable to both init and finalize. 26. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-files/files-download-url) Issue: The return field is documented only as `get_url`, but the local SDK normalizes `get_url` to `url` for compatibility, and example README tool responses use `{ path, url, expires_at }`. Impact: Developers moving between App Host API, SDK, and Executa wrappers may read the wrong field. Suggestion: State that the raw host field is `get_url`, while SDK/examples may expose `url`; examples can use `res.get_url || res.url`. 27. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-files/files-delete) Issue: The `files.delete` signature includes `if_match`, but the local SDK `FilesClient.delete` sends only `{ path, scope }` and does not expose `if_match`. Impact: Developers moving between App Host API and SDK/Executa file APIs may think all surfaces support concurrency-safe deletion. Suggestion: Clarify whether `if_match` only applies to App Host API. If the SDK should also support it, update SDK docs/implementation. 28. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-tools); [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-tools/tools-list); [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-tools/tools-invoke) Issue: The page describes `manifest.ui.host_api.tools` as a required matching condition, but local CLI/examples show it can be omitted; when omitted or empty, declared required/optional Executas can be invoked. Impact: Developers may think `host_api.tools` is mandatory, or misunderstand the semantics of omitted/empty `[]`. Suggestion: Explain that omitted/empty `host_api.tools` defaults to allowing declared Executas; explicit configuration narrows the set. 29. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-tools); [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-tools/tools-list); [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-tools/tools-invoke) Issue: The `:` / “any prefixed form ending in :\” description is too broad. Current behavior only supports `required:`, `optional:`, bare IDs, and dev-time `bundled:` placeholders. Impact: Developers may write `foo:`, which the page implies may work, but CLI/production validation will reject. Suggestion: Replace “any prefix” with an explicit list: `required:`, `optional:`, bare ID, and dev-time `bundled:` placeholder. 30. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-tools/tools-invoke) Issue: The example comment says `timeoutMs: 120_000` will be clamped to MAX 180s, but 120s is below 180s and will not trigger the max clamp. Impact: Developers may misunderstand timeout clamping behavior. Suggestion: If the goal is to demonstrate clamping, change the example to `240_000`; otherwise change the comment to “ask for 2 min, below MAX”. 31. Page: [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-tools/tools-list); [Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference/host-api-tools/tools-invoke) Issue: Needs confirmation: version/release-channel labels appear outdated or unclear. The page shows `ANNA-APP-RUNTIME V0.1`, `TIMEOUTMS SINCE V0.3`, while my local install has `@anna-ai/app-runtime` v0.8.0, schema/dispatcher v0.10.0, and local bridge pin `anna-app-runtime-local@0.2.0a9`. Impact: Developers cannot easily tell whether the page refers to the npm package version, schema wire version, or local runtime version. Suggestion: Clarify whether these badges mean “introduced in” or “current”. If they mean current version, update them to the actual runtime/schema/bridge versions. ## Summary Most of these are not isolated typos. They look like synchronization issues between the documentation and the current Anna App runtime, schema, CLI, and examples. The highest-priority areas to align are: - Whether Host API authorization is controlled by `manifest.ui.host_api.*`, root `permissions[]`, or `host_capabilities`. - Whether page version badges mean “introduced in” or “current”. - Clear separation between App Host API, Executa capabilities, SDK wrappers, and local harness behavior. - Example code should avoid outdated fields or misleading timeout/upload/ACL behavior. I can also split this feedback into smaller page-level issues, or provide concrete local CLI / schema / example evidence for each item if useful. ---
**Author:** ![hunter](https://yyz1.discourse-cdn.com/flex033/user_avatar/forum.anna.partners/hunter/32/8_2.png) [@hunter](https://forum.anna.partners/u/hunter)\ **Post date:** [June 15, 2026, 9:48am UTC](https://forum.anna.partners/t/feedback-on-anna-developer-reference-host-api-docs-several-pages-are-inconsistent-with-current-cli-runtime-examples/103/2 "2026-06-15T09:48:11Z")
Hi @HappyLight! 👋 First off — thank you so much for this incredibly thorough write-up. 🙏 This is exactly the kind of careful, sharp-eyed feedback that makes the Host API better for every Anna App developer. We went through your report point by point against the live source, and you were right on the money for most of it. Here’s what we’ve shipped. 🚀 ## ✅ Fixed in the docs - **ACL model clarified everywhere.** You were spot-on: the dispatcher gates calls on **`manifest.ui.host_api.`** only. The old wording that said you must declare `host.agent` / `host.llm` / `host.storage` / `host.files` / `host.upload` in `manifest.permissions[]` was misleading — `permissions[]` is display/audit metadata and is never checked at dispatch. Every namespace overview (`agent`, `llm`, `image`, `upload`, `storage`, `embed`, `files`) now states the real gate. 🔐 - **Version badges refreshed.** Updated to reflect the current `@anna-ai/app-runtime` and dispatcher releases instead of the stale early-preview numbers. 🏷 - **Timeout values corrected.** `image.*` now shows the real **180 s** default (not 70 s), and the `llm.embed` guidance no longer suggests a value _below_ the default that would shorten your window. ⏱ - **`files.*` cleanup.** Fixed the broken `upload_init` → `upload_finalize` example (the path-reuse bug), corrected the `permission_denied` descriptions, and clarified that the download field is **`get_url`**. 📁 - **`chat.*` now documented.** Brand-new reference page with honest status flags: `append_artifact` is fully implemented ✅, while `write_message` and `read_history` are **Phase-3 stubs** so you know not to depend on persistence yet. 💬 - **`agent.*` completeness.** Added `agent.session.list` and `agent.session.refresh`, plus the real `create` return shape (`system_prompt`, `granted_tools`, `inherit_host_tools`). 🤖 ## 💡 A couple of friendly clarifications A few items turned out to be working as intended — sharing the reasoning so it’s useful for you: - **Error codes** (`APP_NOT_GRANTED`, `APP_QUOTA_EXCEEDED`, etc.) are the correct on-the-wire names. The `-3200x` numbers are internal and get mapped to these strings before they reach you, so your `switch` on the string codes is the right approach. 👍 - **`files.*` vs. the Executa storage SDK** are two different surfaces. The in-iframe `anna.files` runtime is a thin passthrough — it returns `get_url` verbatim and accepts `if_match` on `delete` — so those docs match the runtime SDK you’re calling. The normalize/rename behavior you may have seen lives in the separate Executa-side SDK. - **`upload.negotiate`** intentionally takes only `{filename, mime_type, purpose}` and returns `bytes_size` / `expires_in` — the `size_bytes` field belongs to the APS `files.*` flow. The updated reference should be live shortly. Please keep the feedback coming — issues like this genuinely help us, and we’d love to hear how your app is shaping up. Happy building! 🎉✨ — The Anna Platform team