host.rpc and the low-level surface

This page documents the lowest level of the App SDK: the raw bridge escape hatch (host.rpc), the generic permission-gated resource factory (host.get / host.list), and host to app messaging (host.emit / host.onMessage). Reach for these only when a higher-level namespace does not yet cover what you need; in most apps you will use the typed namespaces instead.

host.rpc

host.rpc dispatches an op directly into the host bridge.

host.rpc(op: string, args: unknown, onPush?: (push: unknown) => void): Promise<unknown>

op: the bridge op name.

args: the op's argument payload.

onPush: an optional callback for streamed push frames the op emits while running.

await host.ready();
const result = await host.rpc('kv.get', { key: 'theme' });

Use it as an escape hatch when the namespaced helper for an op does not exist yet. A new op on a newer host returns unknown_op on an older one, so guard for it. Prefer the typed namespaces (host.kv, host.content, and so on) wherever they exist: they are stable, validated, and documented.

host.get and host.list

host.get(kind, id) resolves a handle to a platform resource the app was granted, and host.list(kind?) enumerates the grants. Grants are written server-side at install (never by the sandboxed app), and the bridge rejects a (kind, id) the app was not granted. This is a defense-in-depth filter; the routes the handle uses still authorize the viewer independently. See the security model.

host.get(kind: 'agent', id: string): Promise<AgentHandle>;
host.get(kind: string, id: string): Promise<unknown>;
host.list(kind?: string): Promise<ResourceRef[]>;

interface ResourceRef { kind: string; id: string; scope?: string[] }

const granted = await host.list('agent');     // ResourceRef[]; reflects grants, no enumeration
const agent = await host.get('agent', granted[0].id); // AgentHandle

Today the supported kind is agent (for which host.agents is the typed sugar). Future kinds (widget, collab, rtc) plug into the same factory.

host.emit and host.onMessage

host.emit fans a payload out on the workspace bus; host.onMessage is a catch-all listener for push frames the host sends to the app.

host.emit(payload: unknown): Promise<void>;
host.onMessage(cb: (push: unknown) => void): () => void; // returns an unsubscribe

// Fan an event out on the workspace bus (e.g. command progress).
await host.emit({ type: 'score', value: 42 });

// Listen for pushes from the host.
const off = host.onMessage((push) => handle(push));
// later:
off();

host.emit is the channel a streaming command uses to report progress: emit events whose names you declared under the command's streams, and the subscribing agent receives them.

host.agents: typed sugar over host.get('agent', ...)

host.commands: host.emit for streaming command progress

Security model: how resource grants are enforced

Error codes: unknown_op and the rest

host.rpc and the low-level surface

host.rpc

host.get and host.list

host.emit and host.onMessage

Related

On this page