@anna-ai/app-runtime

Browser runtime SDK for Anna Apps. A native ES module imported by every Anna App iframe; exports AnnaAppRuntime, which proxies RPC calls over postMessage to the host page (Anna dashboard in production, the anna-app dev harness in local development).

0.3.1+: the SDK is a pure ES module. Load it with <script type="module"> + import { AnnaAppRuntime } from "…". The old classic <script src> + window.AnnaAppRuntime global is removed.

Use inside an Anna App bundle

Make your entry script a module and import the SDK directly:

<!-- index.html -->
<script src="./app.js" type="module"></script>

// app.js
import { AnnaAppRuntime } from "/static/anna-apps/_sdk/latest/index.js";

const anna = await AnnaAppRuntime.connect();

await anna.window.set_title({ title: "My App" });

const out = await anna.tools.invoke({
  tool_id: "tool-twitter-handle-twitter-tool-abcd1234",
  method: "post_tweet",
  args: { text: "hi" },
});

anna.on("entry_payload", (p) => console.log(p));

Don't use inline <script>. The bundle CSP is script-src 'self' <sdk-origin> with no unsafe-inline/nonce, so any inline script (including an inline module that bridges the SDK to a global) is blocked. Always make your entry an external module (<script src="app.js" type="module">) and import the SDK inside it.

Wire envelope

{ kind: "req"|"res"|"event", id, ns, method, args | result | error }

The host validates every call against the app's manifest ACL before forwarding to the backend.

RPC timeouts

Each call has a per-namespace default; apps can override per call:

// Use the namespace default (image: 180s)
const out = await anna.image.generate({ prompt: "..." });

// Override for one call (e.g. high-res / many images)
const out = await anna.image.generate(
  { prompt: "...", n: 4, size: "2048x2048" },
  { timeoutMs: 240000 }
);

| Namespace | Default | Rationale | | --- | --- | --- | | image.* | 180 s | Matches host's upstream provider timeout (Seedream / Qwen / native) | | upload.* | 120 s | Large multipart / negotiate+confirm | | agent.* | 300 s | session.run loops model + tools many turns | | llm.* | 180 s | Long completions / large context | | everything else | 30 s | storage / chat / window / prefs / fs / tools / artifact |

The timeout is a client-side deadline. The host bridge fetch has no abort signal — the backend always runs to completion, but a timed-out promise rejects with Error("RPC <ns>.<method> timed out after Nms") and the eventual response is discarded.

Where the script comes from

| Environment | Source | | --- | --- | | Production (Anna dashboard) | matrix-nexus static server, path /static/anna-apps/_sdk/<version>/index.js | | Local dev (anna-app dev) | @anna-ai/cli harness server resolves this package from its node_modules and serves the same path |

The bundle author writes the same import { AnnaAppRuntime } from "/static/anna-apps/_sdk/latest/index.js" either way; the URL is part of the host contract.

Versioning

This package's version tracks dispatcher_version (wire protocol). See packages/VERSIONS.md for the full pin matrix and bump procedure.

Contents

Single file dist/index.js. Native ES module (ends in export { AnnaAppRuntime, ... }), no build step, runs directly in any modern browser via <script type="module"> / import.