Feedback on Anna Developer Reference HOST API docs: several pages are inconsistent with current CLI / runtime / examples

Developers
1

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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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; Reference — Anna Developer Hub
    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
    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; Reference — Anna Developer Hub; Reference — Anna Developer Hub
    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; Reference — Anna Developer Hub
    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
    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; Reference — Anna Developer Hub
    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
    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
    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
    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
    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
    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
    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
    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; Reference — Anna Developer Hub; Reference — Anna Developer Hub
    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; Reference — Anna Developer Hub; Reference — Anna Developer Hub
    Issue: The <prefix>:<tool_id> / “any prefixed form ending in :<tool_id>” description is too broad. Current behavior only supports required:, optional:, bare IDs, and dev-time bundled: placeholders.
    Impact: Developers may write foo:<tool_id>, 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
    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; Reference — Anna Developer Hub
    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.

2

Hi @HappyLight! :waving_hand:

First off — thank you so much for this incredibly thorough write-up. :folded_hands: 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. :rocket:

:white_check_mark: Fixed in the docs

  • ACL model clarified everywhere. You were spot-on: the dispatcher gates calls on manifest.ui.host_api.<namespace> 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. :locked_with_key:
  • Version badges refreshed. Updated to reflect the current @anna-ai/app-runtime and dispatcher releases instead of the stale early-preview numbers. :label:
  • 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. :stopwatch:
  • 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. :file_folder:
  • chat.* now documented. Brand-new reference page with honest status flags: append_artifact is fully implemented :white_check_mark:, while write_message and read_history are Phase-3 stubs so you know not to depend on persistence yet. :speech_balloon:
  • agent.* completeness. Added agent.session.list and agent.session.refresh, plus the real create return shape (system_prompt, granted_tools, inherit_host_tools). :robot:

:light_bulb: 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. :+1:
  • 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! :tada::sparkles:

— The Anna Platform team