@agent-native/core 0.22.25 → 0.22.27

package/docs/content/external-agents.md

@@ -50,7 +50,9 @@ the connector in a chat.
 
 OAuth grants are per host and per user. The host stores the tokens and
 mediates tool/resource calls, so inline MCP App previews never receive raw
-OAuth tokens. The scopes are:
+OAuth tokens. ChatGPT can keep a reviewed or published connector's tool
+snapshot until you refresh/review it again, so rescan the connector after MCP
+tool or MCP App metadata changes. The scopes are:
 
 | Scope       | What it enables                                      |
 | ----------- | ---------------------------------------------------- |
@@ -170,7 +172,15 @@ When the client requests no explicit scope, the app grants all three so the conn
 
 ## What you can do once connected {#what-you-can-do}
 
-Once your agent is connected, the app's full action surface is available as MCP tools, plus the `ask-agent` meta-tool that runs the full agent loop (the same entry point [A2A](/docs/a2a-protocol) uses). Ask your agent to do real work and it hands back a link straight into the running app:
+Once your agent is connected, the available MCP tool surface depends on the
+host. Developer clients and bearer/static-token clients get the app's full
+action surface plus the `ask-agent` meta-tool that runs the full agent loop
+(the same entry point [A2A](/docs/a2a-protocol) uses). OAuth chat hosts that
+request `mcp:apps`, including Claude and ChatGPT, get a compact app-facing
+catalog instead: cross-app verbs such as `list_apps` and `open_app`, app-only
+embed helpers, and actions that explicitly declare `mcpApp`. In both cases,
+ask the agent to do real work and it hands back a link straight into the
+running app:
 
 ```
 > draft an email to John about the Q3 report
@@ -183,7 +193,13 @@ Click that link and Mail opens with the draft restored — focused exactly where
 
 ### MCP Apps compatibility {#mcp-apps-compatibility}
 
-Agent-native apps also speak the official MCP Apps extension. When any action declares `mcpApp`, the server advertises `extensions["io.modelcontextprotocol/ui"]`, includes both `_meta.ui.resourceUri` and the legacy-compatible `_meta["ui/resourceUri"]` in `tools/list`, and serves the HTML UI through `resources/list` + `resources/read` as `text/html;profile=mcp-app`.
+Agent-native apps also speak the official MCP Apps extension. When any action
+declares `mcpApp`, the server advertises
+`extensions["io.modelcontextprotocol/ui"]`, includes `_meta.ui.resourceUri` /
+`_meta["ui/resourceUri"]` in `tools/list`, and serves the HTML UI through
+`resources/list` + `resources/read` as `text/html;profile=mcp-app`. Resource
+security metadata such as CSP and sandbox permissions lives on the resource
+entries and `resources/read` content, not on the tool descriptor.
 
 That makes the same app surface available to every compatible host rather than building per-client shims. The current official MCP Apps client list includes Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT, and Cursor; host support still varies by plan, release channel, and client version, so check the [MCP extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix). ChatGPT custom MCP apps are available through developer mode for Business and Enterprise/Edu workspaces on ChatGPT web; see OpenAI's [developer mode and MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-apps-in-chatgpt-beta) notes.
 
@@ -223,13 +239,15 @@ relays the same host actions over `agentNative.mcpHost.*` postMessage
 requests. Keep the result shape identical for both paths: return a focused
 `link` and concise structured content.
 
-The resource shell owns the outer host size. Keep embedded app routes
-internally scrollable and let the launcher report a bounded intrinsic height
-rather than the full document height; otherwise host auto-resize can turn a
-normal app page into a very tall chat artifact. A changed shell only affects
-new MCP App resources and new tool calls. Old ChatGPT/Claude conversation
-frames can keep the previous resource behavior, so verify sizing with a fresh
-inline render before judging a fix.
+The resource shell owns the outer host size. `embedApp({ height })` defaults
+to `560px`, clamps the shell to `320-900px`, and reserves `44px` for the small
+toolbar, so the route viewport is `height - 44px`. Keep embedded app routes
+internally scrollable and let the launcher report that bounded intrinsic
+height rather than the full document height; otherwise host auto-resize can
+turn a normal app page into a very tall chat artifact. A changed shell only
+affects new MCP App resources and new tool calls. Old ChatGPT/Claude
+conversation frames can keep the previous resource behavior, so verify sizing
+with a fresh inline render before judging a fix.
 
 Claude uses the single-frame transplant path by default. You can also force it
 in other hosts with `embedMode: "transplant"` or `frame: "transplant"` when

package/docs/content/mcp-protocol.md

@@ -94,7 +94,9 @@ custom actions can return the same field when they already know the target
 route.
 
 The outer MCP resource reports a bounded inline height to the host and the app
-route scrolls internally. Do not rely on host auto-resize measuring the full
+route scrolls internally. `embedApp({ height })` defaults to a `560px` shell,
+clamps to `320-900px`, and subtracts `44px` for the wrapper toolbar before
+sizing the route viewport. Do not rely on host auto-resize measuring the full
 document; in ChatGPT and Claude this can make a normal full-app route appear as
 a huge chat artifact. Host conversations also keep already-rendered iframes, so
 after changing the resource shell or `ui://` version, test a fresh tool call

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.22.25",
+  "version": "0.22.27",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",