@belonguniverseai/react-sdk 0.6.20 → 0.6.22

package/README.md

@@ -78,6 +78,75 @@ the init values.
 Neither value is persisted — a reload re-derives both from the host's next
 `init`.
 
+### Opening the dock from the host (`window.belong.open`)
+
+`belong.open({ size?, draft? })` shows the chat view at the requested size:
+`"fullscreen"` covers the viewport on desktop (a phone resolves it to the open
+sheet, like the rail's own toggle), `"expanded"` docks it beside the page, and
+omitting `size` keeps the current size (a collapsed dock expands). `draft`
+prefills the composer — never sends it, only when the composer is empty, at
+most 4,000 characters — and focuses it. The user can always leave fullscreen.
+
+It is safe to call BEFORE `init` resolves: a request made before the dock
+mounts is applied at mount, so `open({ size: "fullscreen" })` followed by
+`init(...)` mounts straight into fullscreen with no flash of the docked size.
+
+### Host-bridged MCP (`init({ hostMcp })`)
+
+Some tools can only be reached from the signed-in user's own page — an MCP
+server behind an identity-aware proxy, an intranet, a cookie session. A tenant
+publishes such a server as an MCP plugin entry with `transport: "host"` and a
+same-origin `mcpUri` path (see `docs/guides/009-manual-agent-integration.md`);
+the agent's calls then travel to the dock, which POSTs each JSON-RPC
+`tools/call` to that path on the page's own origin with `credentials:
+"same-origin"` and relays the raw answer back.
+
+The host must opt in, per path:
+
+```js
+window.belong.init({
+  // …
+  hostMcp: { allowedPaths: ["/mcp"] }, // root-relative, exact match, at most 8
+});
+```
+
+A path not listed is refused in the page (`mcp_not_allowed`) whatever the
+tenant publishes; omitting `hostMcp` disables the feature. Requests carry
+`x-belong-source: dock` so the host can label its own audit logs; they follow no
+redirects (an expired proxy session reads as "sign-in expired", not as a login
+page), abort after 55 s, and relay at most 1,000,000 characters of body.
+
+### Restricting what the agent can do on the page (`init({ browserControl })`)
+
+By default the dock runs every browser-control op the agent sends: reading the
+page (`snapshot`, `read`), driving it (`click`, `type`, `select`, `press`,
+`navigate`), running JavaScript in it (`eval`) and host MCP calls (`mcp_call`).
+All of them act with the signed-in user's own session on your origin.
+
+A host can limit that to the ops it wants:
+
+```js
+window.belong.init({
+  // …
+  hostMcp: { allowedPaths: ["/mcp"] },
+  browserControl: { allowedOps: ["mcp_call"] }, // only the bridged MCP calls
+});
+```
+
+Every other op is refused in the page before it runs (`op_not_allowed`), and the
+agent is told the page does not allow it. `allowedOps: []` refuses everything.
+Omitting `browserControl` keeps every op, as before. A value that is present but
+invalid (an unknown op name, a misspelt key) refuses everything and logs a
+console warning, because a host that passed one meant to restrict the page. Like
+`hostMcp`, it is restated on every `init`.
+
+**If your page only bridges MCP, pass `allowedOps: ["mcp_call"]`.** Otherwise
+the agent can also script and click through the page with the viewer's session,
+which reaches everything `hostMcp.allowedPaths` was meant to fence off. That
+matters most when the agent reads text written by other people (customer
+conversations, tickets, email), since such text can carry instructions aimed at
+the agent.
+
 ## Account authorization and Content Security Policy
 
 Browser-bound account authorization opens an `about:blank` popup, clears its