Mini Apps and sessions

• One backend per Mini App: Each Mini App starts only one Node process. Whichever session you call it from, you reach the same backend and read and write the same data.
• Pages are isolated per session: Each session has its own Mini App tab, but within one session a Mini App opens in only one tab.
• Sessions a Mini App starts are private to it: Sessions a Mini App starts through the Agent API don’t appear in the chat list on the left; only that Mini App maintains and continues them.

​

Opening a Mini App in a session

• Once opening has started, removing the reference, cancelling the message, or switching sessions doesn’t withdraw it. The tab stays in the session that requested it until you close it.
• The session list on the left marks sessions that have a Mini App open, so you can get back to the right workspace.

​

One service for every session

• When sessions A and B open the same Mini App, both pages talk to the same Node service and read and write the same dataDir.
• A change made in session A shows up on session B’s page only after a refresh or a pushed update. Authors should route every write through the Node business service and push SSE or WebSocket events after committing; see State and persistence.
• Removing an @ reference from the input doesn’t stop the shared service.
• Closing a running Mini App’s tab and confirming stops its shared service and closes that plugin’s pages in every session.
• At most 3 different Mini App services run at once, and referencing a Mini App that is already running doesn’t take a new slot. If you @ a Mini App that needs a new slot and none is free, it doesn’t start or open; you see a service-limit notice and the reference stays. Select it again once a slot frees up.
• After a service restart, refresh or reopen an open tab to recover.

​

How the Agent uses a Mini App in a session

• Managed MCP tools: while the Mini App service runs, the Agent can call the tools it exposes. Tools follow the service, not any session’s page.
• Ready before sending: when a message references a Mini App, the host starts its service, connects MCP, and confirms the tools are available before calling the model. If a required managed MCP is unavailable, the request fails instead of letting the model continue without its tools.
• No implicit starts: the host never starts a Mini App because of message history, quoted messages, or model output.
• Looking at the page: the Agent can inspect the Mini App page open in the current session with the built-in browser. That is how screenshot acceptance works when building with /miniapp-creator.

​

Handing content to this session’s input

• message.append always targets the session the page belongs to. It never writes to another session or the home draft, and never creates a session.
• It only appends to local, writable sessions. If the session is deleted, becomes read-only, or switches to cloud or Remote Control, the call rejects with target_unavailable instead of writing somewhere else.
• It can append to the session’s draft even when that session isn’t in the foreground.
• Every append needs user confirmation, and the user sends the message.

​

A Mini App’s own Agent sessions

• These sessions don’t appear in your session list. Each Mini App can continue only sessions it created.
• The agent is fixed at creation; create a new session to use a different agent.
• The model is captured at creation and then decoupled from the chat: switching models in your main chat doesn’t affect the Mini App’s session. run and answer can switch models explicitly.
• A session the page creates with create can be handed to Node by passing its sessionId, and Node continues it with run({ sessionId }).

​

Showing it in the chat panel

• The page can open any session this Mini App owns, including ones Node created.
• One session can show in the side panels of several chats at once; it counts as unanswerable only after all of them close.
• Tool approvals wait only while someone can answer: the call passed onEvent, or the session is showing in a chat side panel. The chat a session was originally created from doesn’t count. Approvals nobody can answer are denied, and the model is told to continue without that tool.
• Reloading or closing the host window counts as closing the panel. After the chat is deleted or the runtime restarts, the page needs to call open again.

​

Reading and observing user sessions

​

Pop-out windows and sessions

• A popped-out window still belongs to the original session’s tab. Closing it or pressing Cmd/Ctrl+W requests a return to its original file panel.
• Changing between inline and window is separate from reopening the Mini App in the same session. When the host returns modeChangeReloadsPage: true, changing mode rebuilds the page: unsaved memory, media streams, and page subscriptions do not survive, while the logical window ID and Node service remain. Authors need to save state first and restore it when the destination page starts; see Page rebuilds and confirmation.
• From v3.1.10, popping out or returning a page that requires rebuilding displays the impact and waits for confirmation. Closing the separate window or pressing Cmd/Ctrl+W keeps the original window until confirmation finishes; cancellation leaves the page and requests in the original window unchanged.
• The window’s visibility doesn’t follow the main window: hiding, minimizing, or closing the main window to the tray leaves popped-out windows as they are.
• When the Mini App stops, the page closes, or the app quits, the window closes with it.

​

Sign-in and accounts

• When the same sign-in refreshes its credentials, running Mini Apps, managed MCP, and tools stay as they are.
• After you sign out, Host Connector tool lists and authorized references are revoked. Sign back in with the same account and the Mini App lists its tools again to keep working, with no republish.
• When you switch to a different account, official Mini Apps running under the old account are retired before the new account can activate them. Local Mini Apps keep running, but their Connector access from the old account is revoked for good; restart the service to use Connectors under the new account.