@agent-native/core 0.22.35 → 0.22.37

package/docs/content/actions.md

@@ -201,7 +201,9 @@ This advertises the MCP Apps extension (`io.modelcontextprotocol/ui`), exposes t
 The helper launches the action's `link` target through `/_agent-native/embed/start` with a short-lived browser session, so routes such as full dashboards, filtered inboxes, drafts, and extension pages can reuse the app's React components directly.
 Same-app `open_app({ embed: true })` mints that embed-start ticket during the
 original tool call, and custom actions can return `embedStartUrl` for the same
-fast path; otherwise the resource falls back to the app-only
+fast path. The MCP layer keeps ticket-bearing embed-start URLs in hidden
+metadata and removes them from model-visible `structuredContent` and open-link
+metadata; otherwise the resource falls back to the app-only
 `create_embed_session` helper.
 Standard hosts navigate the MCP App frame directly to that signed route.
 Claude web uses a single-frame transplant path that hydrates the signed app
@@ -217,7 +219,9 @@ and explicit diagnostic iframe path proxy `agentNative.mcpHost.*` messages
 through the launch wrapper.
 When a submitted app prompt should continue the host chat, call
 `sendToAgentChat()` from the embedded route; it sends hidden model context and
-then posts a visible user message through the host bridge where supported.
+then posts a visible user message through the host bridge where supported. Keep
+internal route/app-state instructions in the hidden context; the visible prompt
+should be the user's actual request.
 Design those routes with their own scrolling, because the MCP resource reports
 a bounded inline height rather than asking the host to size itself to the full
 app document. `embedApp({ height })` defaults to a `560px` shell, clamps to

package/docs/content/client.md

@@ -77,7 +77,8 @@ When the app route is running inside an MCP App embed created with `embedApp()`,
 auto-submitted messages (`submit` omitted or `true`) are forwarded to the MCP
 App host bridge, which asks the containing host to add hidden context and send
 the visible user turn. `context` is sent as model context before the visible
-message, so it stays model-visible without being posted as user-facing chat.
+message, so it stays model-visible without being posted as user-facing chat or
+concatenated into the host's visible prompt.
 `submit: false` keeps the local prefill/review behavior because MCP Apps do not
 define a standard draft-prefill API.
 

package/docs/content/external-agents.md

@@ -52,7 +52,10 @@ 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. 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:
+tool or MCP App metadata changes. If you still have old per-app connectors
+enabled alongside Dispatch, refresh or reconnect each stale connector; updating
+Dispatch does not rewrite ChatGPT or Claude's cached Calendar/Mail/etc.
+snapshots. The scopes are:
 
 | Scope       | What it enables                                      |
 | ----------- | ---------------------------------------------------- |
@@ -237,11 +240,13 @@ embedded routes so a reload with the same signed URL reconstructs the same
 view.
 
 For same-app `open_app({ embed: true })`, the framework mints the embed-start
-ticket during the original tool call and returns `embedStartUrl` in the hidden
-structured payload. Custom actions can do the same. When no `embedStartUrl` is
+ticket during the original tool call and stores the signed start URL in hidden
+tool metadata. Custom actions can return `embedStartUrl` for the same fast
+path; the MCP layer strips that ticket-bearing URL from model-visible
+`structuredContent` and normal open-link metadata. When no embed start URL is
 present, the resource falls back to the app-only `create_embed_session` helper.
 This keeps production hosts that restrict iframe-initiated tool calls on the
-direct route.
+direct route without leaking one-time app session URLs into the transcript.
 
 ChatGPT gets a dedicated compatibility path through `window.openai`: the launch
 document reads `toolInput`, `toolOutput`, and `toolResponseMetadata` directly,
@@ -438,7 +443,9 @@ loads third-party assets.
 Inside those `embedApp()` routes, `sendToAgentChat()` is embed-aware.
 Auto-submitted prompts relay to the MCP host as `ui/update-model-context` plus
 `ui/message`, so a button in the embedded app can intentionally continue the
-Claude/ChatGPT conversation from the selected app state. `submit: false`
+Claude/ChatGPT conversation from the selected app state. Hidden context is sent
+as model context; the visible user turn stays just the app's prompt, which
+avoids scary host consent around internal app-state file paths. `submit: false`
 remains local prefill/review behavior.
 
 ### The `link` contract {#link-contract}
@@ -587,6 +594,10 @@ The fallback hosted `connect` flow never copies the deployment's shared secret.
 - When validating ChatGPT or Claude web, trigger a fresh tool call after shell
   changes and measure the visible iframe. Previously rendered frames in the
   same conversation may still show cached height or launch behavior.
+- Keep ChatGPT/Claude app-host catalogs compact. Use Dispatch and
+  `open_app({ embed: true })` for full-app previews; only mark a specific
+  action `mcpApp.compactCatalog: true` when it must appear directly in the
+  compact host discovery surface.
 
 **Don't**
 

package/docs/content/mcp-protocol.md

@@ -89,9 +89,10 @@ For normal action authoring, use `embedRoute()` when the action's
 `link` and `mcpApp` should come from the same pure route builder. The route
 itself should derive state from the URL and normal app data fetching.
 Same-app `open_app({ embed: true })` returns a server-minted `embedStartUrl`
-so the resource can launch without a second iframe-originated tool call;
-custom actions can return the same field when they already know the target
-route.
+so the resource can launch without a second iframe-originated tool call. The
+server moves that ticket-bearing URL into hidden metadata and strips it from
+model-visible structured content and normal open-link metadata. 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. `embedApp({ height })` defaults to a `560px` shell,
@@ -158,14 +159,25 @@ Model context updates are opt-in and hidden from the user-facing transcript.
 `ui/message` is the portable way for an embedded app button to ask the host to
 post a visible user message and continue the chat. In agent-native routes,
 `sendToAgentChat()` uses `ui/update-model-context` plus `ui/message` when
-called from a submitted MCP App embed, while `submit: false` remains an
-in-route draft/prefill path.
+called from a submitted MCP App embed. Hidden context is sent through model
+context, while `ui/message` contains only the visible prompt. `submit: false`
+remains an in-route draft/prefill path.
 Display mode requests are best-effort: a host can honor, ignore, or reject the
 request. Embedded routes must remain functional in the default inline mode.
 
 ## Tools {#tools}
 
-Stdio/code developer clients can see all connected app actions as MCP tools. Chat-style app hosts, including OAuth callers that request `mcp:apps` and generic authenticated remote HTTP/static-token callers, get a compact app-host catalog: app-facing builtins (`list_apps`, `open_app`, `ask_app`, and app-only `create_embed_session`) plus rare actions marked `mcpApp.compactCatalog: true`. Their `resources/list` is compact too, normally advertising only the generic `open_app` embed resource. `publicAgent.expose` remains the opt-in for safe read/ingest tools outside that compact app catalog. This keeps ChatGPT/Claude app-host discovery small while preserving the full developer surface for local agents.
+Stdio/code developer clients can see all connected app actions as MCP tools
+when they explicitly request the full catalog. Chat-style app hosts, including
+OAuth callers that request `mcp:apps` and generic authenticated remote
+HTTP/static-token callers, get a compact app-host catalog by default:
+app-facing builtins (`list_apps`, `open_app`, `ask_app`, and app-only
+`create_embed_session`) plus rare actions marked `mcpApp.compactCatalog: true`.
+Their `resources/list` is compact too, normally advertising only the generic
+`open_app` embed resource. `publicAgent.expose` remains the opt-in for safe
+read/ingest tools outside that compact app catalog. This keeps ChatGPT/Claude
+app-host discovery small while preserving the full developer surface for local
+agents.
 
 The mapping is direct:
 

package/package.json

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