Host API reference documentation appears out of sync with current SDK/schema

Developers
1

Hi Anna team,

I reviewed the current host.api reference documentation against the latest public SDK and schema surfaced through @anna-ai/cli@0.1.29, @anna-ai/app-runtime@0.8.0, and @anna-ai/app-schema@0.10.0. I found a few places where the reference docs appear to be out of sync.

  1. host-api-agent is missing current agent session methods

The host.api reference page for agent.* currently documents:

  • agent.session.create
  • agent.session.run
  • agent.session.cancel
  • agent.session.history
  • agent.session.delete

However, the latest SDK and schema also expose:

  • agent.session.list
  • agent.session.refresh

The latest SDK exposes these in the session method list, and methods.json from @anna-ai/app-schema@0.10.0 includes both methods. The reference page should probably add entries for both.

  1. host-api-image still documents the old image timeout

The image.generate documentation says the SDK default per-call timeout is 70s.

In the current SDK, the namespace defaults appear to be:

image: 180000,
upload: 120000,
agent: 300000,
llm: 180000,
tools: 70000,
files: 60000,

So 70s now appears to apply to tools.*, not image.*. The image reference should likely say 180s.

  1. host-api-windows route appears to be wrong

The requested URL:

/developers/reference/host-api-windows

does not correspond to the reference section id. The actual section id appears to be:

host-api-window

So the correct URL should be:

/developers/reference/host-api-window

The window.* methods themselves seem consistent with the schema, but the plural route may need a redirect or alias.

  1. host-api-files conflicts with the schema stub status

The files.* reference page documents these as active APIs:

  • files.upload_init
  • files.upload_finalize
  • files.download_url
  • files.list
  • files.delete

The current SDK also exposes anna.files.*, and the dev harness appears to route these methods.

However, @anna-ai/app-schema@0.10.0 still marks all files.* methods as stub: true with _h_not_implemented handlers.

This creates an ambiguity: either the schema is stale, or the reference page is documenting APIs that are not officially active yet. It would be useful to align the reference docs, SDK, and schema here.

  1. host-api-stubs may also be incomplete depending on the intended files.* status

If files.* is still considered stubbed according to the canonical schema, then the stubs page should probably include the files.* methods too. If files.* is now active, then the schema should remove the stub markers.

Everything else I checked looked consistent at the method-name level:

  • chat.*
  • llm.complete
  • llm.embed
  • upload.*
  • storage.*
  • tools.*
  • window.*
  • artifact.*
  • fs.*
  • prefs.get

Could you confirm whether the source of truth should be the latest SDK/runtime behavior or @anna-ai/app-schema@0.10.0? Right now the host.api reference appears to be partially generated from the schema but not fully aligned with it.