Host Bridge Protocol

Most games should not use the host bridge directly. Use @vifu/hub.

This page exists for advanced debugging and host implementers.

Sources

Source	Direction	Purpose
vifu-game-runtime	game to host	Runtime notifications and responses.
vifu-web-host	host to game	Agent Runtime requests.
vifu-ios-host	host to game	iOS WKWebView runtime requests.

Lifecycle

1. The game bundle loads.
2. The VifuHub SDK installs its message listener.
3. The VifuHub SDK announces runtime readiness.
4. The host sends initialization.
5. hub.ready() resolves and hub.status().hostConnected becomes true.

Public VifuHub SDK Mapping

VifuHub SDK API	Bridge purpose
hub.ready()	Wait for host initialization.
hub.tool(...)	Declare a callable tool definition.
hub.agent(...)	Create an isolated runtime agent for an NPC, tutor, companion, or other entity.
hub.run(...)	Run one model/tool loop for a target agent.
hub.resources.*	Resolve or read declared runtime resources.
hub.gameState.*	Save and restore game-owned state.
hub.ai.*	Call Vifu AI through provider routing and quota.
hub.dictionary.*, hub.voice.*, hub.review.*, hub.camera.*, hub.invoke(...)	Call declared host capabilities.

Runtime Agent Tool Registries

The Agent Runtime keeps tools isolated per agent and per run. A tool exposed for one agent is not available to another agent unless the game explicitly registers it there.

Tools passed directly to hub.run(agent, input, { tools }) are scoped to that run and cleaned up after the request. Persistent tools registered on the agent stay available until the agent is disposed.

The companion session socket remains a low-frequency play-session event channel. Runtime tool calls use the dedicated runtime-skill Durable Object/WebSocket path.

Policy

The host rejects undeclared calls. Declare the feature with public manifest nouns such as ai, data, media, bundle, links, save, dictionary, voice, camera, or review.

Do not use raw window.parent.postMessage(...) for game/backend logic. Raw bridge messages are a host implementation detail and may change within the compatibility line.