@agent-native/core 0.204.0 → 0.204.1-nightly-20261008065100

package/dist/client/chat/agentkit-agent-native.js

@@ -365,6 +365,31 @@ function durableRunFailures(messages) {
         ];
     }));
 }
+/** The turn each durable prompt started, keyed by the run it was submitted to. */
+function durableSubmittedTurns(messages) {
+    return new Map(messages.flatMap((message) => {
+        const custom = asRecord(asRecord(message.metadata)?.custom);
+        return message.role === "user" &&
+            typeof custom?.submittedRunId === "string" &&
+            typeof custom.submittedTurnId === "string"
+            ? [[custom.submittedRunId, custom.submittedTurnId]]
+            : [];
+    }));
+}
+/** The runs that left a durable reply on each turn. */
+function durableReplyRunsByTurn(messages) {
+    const result = new Map();
+    for (const message of messages) {
+        const turnId = asRecord(asRecord(message.metadata)?.custom)?.turnId;
+        if (message.role !== "assistant" || typeof turnId !== "string")
+            continue;
+        const runIds = result.get(turnId) ?? new Set();
+        for (const runId of durableRunIds(message))
+            runIds.add(runId);
+        result.set(turnId, runIds);
+    }
+    return result;
+}
 /** A durable reply's terminal run plus every continuation run folded into it. */
 function durableRunIds(message) {
     const metadata = asRecord(message.metadata);
@@ -561,6 +586,38 @@ function reconcileDurableMessages(messages, durable, events, runs, toolCalls) {
             durableByFoldedRun.set(runId, durableByFoldedRun.has(runId) ? null : message);
         }
     }
+    const textOf = (parts) => parts
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("");
+    // A run that recovered an interrupted turn records only itself on its reply,
+    // while an open page streamed it into the run the prompt was submitted to.
+    // The recovering run's events open their own message, so the reply is on
+    // screen only when one of that run's messages is exactly it; anything less
+    // keeps the saved reply, so the answer is never dropped.
+    const submittedRunByTurn = new Map();
+    for (const stored of submittedUsers) {
+        const turnId = asRecord(asRecord(stored.metadata)?.custom)?.submittedTurnId;
+        if (typeof turnId !== "string")
+            continue;
+        submittedRunByTurn.set(turnId, submittedRunByTurn.has(turnId) ? null : submittedRunId(stored));
+    }
+    const shownByInterruptedRun = (reply) => {
+        const turnId = asRecord(asRecord(reply.metadata)?.custom)?.turnId;
+        const submitted = typeof turnId === "string" ? submittedRunByTurn.get(turnId) : undefined;
+        if (!submitted ||
+            durableRunIds(reply).includes(submitted) ||
+            durableByRun.has(submitted)) {
+            return false;
+        }
+        const ids = assistantIdsByRun.get(submitted);
+        const replyText = textOf(reply.parts);
+        if (!ids || !replyText)
+            return false;
+        return messages.some((message) => message.role === "assistant" &&
+            ids.has(message.id) &&
+            textOf(message.parts) === replyText);
+    };
     const rootAssistantProjection = projectRootAssistantMessages({
         rootMessages: durable,
         snapshotMessages: messages,
@@ -676,6 +733,8 @@ function reconcileDurableMessages(messages, durable, events, runs, toolCalls) {
         if (typeof runId !== "string" || !recoverableAssistantRunIds.has(runId)) {
             continue;
         }
+        if (shownByInterruptedRun(message))
+            continue;
         missingMessages.push(message);
         representedAssistantIds.add(message.id);
     }
@@ -694,10 +753,6 @@ function reconcileDurableMessages(messages, durable, events, runs, toolCalls) {
             snapshotRunIdsByMessageId.get(message.id) ??
             (typeof metadataRunId === "string" ? metadataRunId : undefined));
     };
-    const textOf = (parts) => parts
-        .filter((part) => part.type === "text")
-        .map((part) => part.text)
-        .join("");
     const reconciledMessages = projectedMessages.map((message) => {
         if (message.role === "user") {
             const stored = storedUserBySnapshotId.get(message.id);
@@ -1652,8 +1707,7 @@ export function createAgentNativeAgentKitTransport(options = {}) {
         }
         return value;
     }
-    async function activeRunSnapshot(threadId) {
-        const value = await activeRunStatus(threadId);
+    async function activeRunSnapshot(threadId, value) {
         const status = value.status;
         if (typeof value.active !== "boolean")
             return undefined;
@@ -1775,7 +1829,8 @@ export function createAgentNativeAgentKitTransport(options = {}) {
         const completedRunIds = completedDurableRunIds(durableMessages);
         const userStoppedRunIds = userStoppedDurableRunIds(durableMessages);
         const durableFailures = durableRunFailures(durableMessages);
-        const activeRun = await activeRunSnapshot(threadId);
+        const activeStatus = await activeRunStatus(threadId);
+        const activeRun = await activeRunSnapshot(threadId, activeStatus);
         if (activeRun === undefined)
             return thread;
         let discoveredRun = activeRun;
@@ -1792,9 +1847,30 @@ export function createAgentNativeAgentKitTransport(options = {}) {
             !["completed", "failed", "cancelled"].includes(discoveredRun.status)
             ? discoveredRun.id
             : undefined;
+        const submittedTurns = durableSubmittedTurns(durableMessages);
+        const replyRunsByTurn = durableReplyRunsByTurn(durableMessages);
+        const discoveredTurnId = typeof activeStatus.turnId === "string" ? activeStatus.turnId : undefined;
+        // The stale-run reaper hands an interrupted turn to a successor run, which
+        // then owns the turn's outcome: the server reports it, or it completed a
+        // reply. A successor that failed or was stopped leaves the failure showing.
+        const carriedOnByNewerRun = (runId) => {
+            const turnId = submittedTurns.get(runId);
+            if (!turnId)
+                return false;
+            if (discoveredRun && discoveredTurnId === turnId)
+                return true;
+            return [...(replyRunsByTurn.get(turnId) ?? [])].some((id) => id !== runId && completedRunIds.has(id));
+        };
         const runs = (thread.runs ?? [])
             .filter((entry) => entry.id !== discoveredRun?.id)
             .map((run) => {
+            if ((["queued", "running"].includes(run.status) ||
+                (run.status === "failed" &&
+                    runOutcomeForCode(run.error?.code) === "interrupted")) &&
+                carriedOnByNewerRun(run.id)) {
+                const { error: _error, ...attempt } = run;
+                return { ...attempt, status: "completed" };
+            }
             if (activeRun === null &&
                 run.status === "running" &&
                 userStoppedRunIds.has(run.id)) {

package/dist/client/chat/agentkit-protocol.js

@@ -1,5 +1,5 @@
 import { AGENT_TOOL_CALL_HISTORY_MEDIA_TYPE, AGENT_TOOL_RESULT_HISTORY_MEDIA_TYPE, AGENTKIT_PROTOCOL_VERSION, AgentProtocolValidationError, approvalResponseFromResume, createCapabilityUnavailableError, createCapabilityUnsupportedError, inferAgentActivityKind, negotiateAgentKitProtocolVersion, resumeEntryFromApproval, resumeOptionId, } from "@agent-native/agentkit/protocol";
-import { AUTO_CONTINUE_OF_RUN_METADATA_KEY, AUTO_CONTINUE_PROMPT, AUTO_CONTINUE_REFUSAL_CODES, } from "../../agent/auto-continue.js";
+import { AUTO_CONTINUE_OF_RUN_METADATA_KEY, AUTO_CONTINUE_PROMPT, AUTO_CONTINUE_REFUSAL_CODES, CONTINUE_OF_RUN_METADATA_KEY, CONTINUE_UNAVAILABLE_CODE, } from "../../agent/auto-continue.js";
 import { emitChatFirstOpenApp, emitChatFirstOpenBrowser, } from "../chat-first-state.js";
 import { decideAfterStreamClosed, runOutcomeForCode, } from "./run-outcome.js";
 function isTerminalRunStatus(status) {
@@ -1104,6 +1104,67 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
         ensurePump(run);
         return run;
     }
+    /**
+     * Registers a run the runtime just started and begins reading it. A disposed
+     * adapter keeps no run it can no longer read.
+     */
+    async function openStartedRun(threadId, session, turn, turnMetadata, observability) {
+        const runId = turn.runId ?? turn.id ?? createId("run");
+        const runMetadata = mergeTrustedProtocolMetadata(options.metadata, turnMetadata, turn.metadata, {
+            [AGENT_NATIVE_PROTOCOL_METADATA_KEY]: {
+                observability: {
+                    protocolRunId: runId,
+                    ...(turn.runId === undefined ? {} : { runtimeRunId: turn.runId }),
+                    runtimeId: runtime.id,
+                    sessionId: session.id,
+                    turnId: turn.id,
+                    threadId,
+                    ...observability,
+                },
+            },
+        });
+        setRuntimeRunIdMetadata(runMetadata, turn.runId);
+        const run = {
+            runId,
+            threadId,
+            session,
+            turn,
+            events: [],
+            firstRetainedSequence: 1,
+            sequence: 0,
+            status: "queued",
+            lastAccessedAtMs: timeMs(),
+            activeReaders: 0,
+            metadata: runMetadata,
+            activeMessageCompleted: false,
+            pendingWidgets: new Map(),
+            actions: new Map(),
+            activeTools: new Map(),
+            pendingToolMessageAssociations: new Map(),
+            activeActivities: new Map(),
+            terminalAppendDepth: 0,
+            pumpPromise: null,
+            continuationPromise: null,
+            streamClosed: false,
+            terminal: false,
+            waitingForContinuation: false,
+            listeners: new Set(),
+        };
+        if (disposed) {
+            await disposeSession(session).catch(() => undefined);
+            throw new Error("The AgentKit adapter was disposed during turn creation.");
+        }
+        pruneRetainedRuns(run.lastAccessedAtMs);
+        indexRun(run, turn.runId);
+        append(run, {
+            type: "run.started",
+            agentId: runtime.id,
+            metadata: runMetadata,
+        });
+        append(run, { type: "run.status", status: "running" });
+        ensurePump(run);
+        return runId;
+    }
     async function disposeSession(session) {
         if (disposedSessions.has(session))
             return;
@@ -2012,21 +2073,26 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
                         payload: run.usage,
                     },
                 ];
-            case "error":
+            case "error": {
+                const error = {
+                    code: event.code ?? "runtime_error",
+                    message: event.error,
+                    retryable: event.retryable ?? event.recoverable,
+                    details: event.details ?? event.cause,
+                };
+                // An interruption ends this runtime run, not necessarily the turn.
+                if (runAuthority &&
+                    capabilities.resumableRuns === true &&
+                    runOutcomeForCode(error.code) === "interrupted") {
+                    run.heldInterruption = error;
+                    return [];
+                }
                 run.terminal = true;
                 return [
                     { type: "run.status", ...base, status: "failed" },
-                    {
-                        type: "run.failed",
-                        ...base,
-                        error: {
-                            code: event.code ?? "runtime_error",
-                            message: event.error,
-                            retryable: event.retryable ?? event.recoverable,
-                            details: event.details ?? event.cause,
-                        },
-                    },
+                    { type: "run.failed", ...base, error },
                 ];
+            }
             case "done":
                 if (!isTerminalReason(event.reason)) {
                     run.waitingForContinuation = true;
@@ -2256,6 +2322,18 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
             }
             if (stopped())
                 return null;
+            // An unreachable server says nothing about a successor; keep holding
+            // through the usual backoff until it answers.
+            if (run.heldInterruption && read.kind !== "unreachable") {
+                const successor = read.kind === "read" &&
+                    read.state.status !== "missing" &&
+                    read.state.runId !== runtimeRunId;
+                if (!successor) {
+                    appendHeldInterruption(run);
+                    return null;
+                }
+                run.heldInterruption = undefined;
+            }
             const decision = decideAfterStreamClosed(read, {
                 runId: runtimeRunId,
                 drain: run.terminalDrain,
@@ -2406,6 +2484,14 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
             append(run, { type: "run.cancelled" });
         }
     }
+    /** The runtime run's own interruption, once no newer run carries the turn. */
+    function appendHeldInterruption(run) {
+        const error = run.heldInterruption;
+        run.heldInterruption = undefined;
+        run.terminal = true;
+        append(run, { type: "run.status", status: "failed" });
+        append(run, { type: "run.failed", error });
+    }
     function setResumedRuntimeTurn(run, resumed) {
         const runtimeRunId = run.turn.runId ?? run.runId;
         if (resumed.runId && resumed.runId !== runtimeRunId) {
@@ -2439,8 +2525,11 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
                             for (const protocolEvent of runtimeEventToProtocolEvents(run, event)) {
                                 append(run, protocolEvent);
                             }
-                            if (run.waitingForContinuation || run.terminal)
+                            if (run.waitingForContinuation ||
+                                run.terminal ||
+                                run.heldInterruption) {
                                 break;
+                            }
                         }
                     }
                     catch (error) {
@@ -2452,7 +2541,7 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
                     }
                     if (run.restoredWithoutStream)
                         run.restoredWithoutStream = false;
-                    else
+                    else if (!run.heldInterruption)
                         run.pipeClosedBeforeTerminal = true;
                     const resumed = runAuthority && capabilities.resumableRuns === true
                         ? await followRunAuthority(run, runAuthority, stream)
@@ -2578,59 +2667,7 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
                 metadata: turnMetadata,
                 abortSignal: readers.signal,
             });
-            const runId = turn.runId ?? turn.id ?? createId("run");
-            const runMetadata = mergeTrustedProtocolMetadata(options.metadata, turnMetadata, turn.metadata, {
-                [AGENT_NATIVE_PROTOCOL_METADATA_KEY]: {
-                    observability: {
-                        protocolRunId: runId,
-                        ...(turn.runId === undefined ? {} : { runtimeRunId: turn.runId }),
-                        runtimeId: runtime.id,
-                        sessionId: session.id,
-                        turnId: turn.id,
-                        threadId: input.threadId,
-                    },
-                },
-            });
-            setRuntimeRunIdMetadata(runMetadata, turn.runId);
-            const run = {
-                runId,
-                threadId: input.threadId,
-                session,
-                turn,
-                events: [],
-                firstRetainedSequence: 1,
-                sequence: 0,
-                status: "queued",
-                lastAccessedAtMs: timeMs(),
-                activeReaders: 0,
-                metadata: runMetadata,
-                activeMessageCompleted: false,
-                pendingWidgets: new Map(),
-                actions: new Map(),
-                activeTools: new Map(),
-                pendingToolMessageAssociations: new Map(),
-                activeActivities: new Map(),
-                terminalAppendDepth: 0,
-                pumpPromise: null,
-                continuationPromise: null,
-                streamClosed: false,
-                terminal: false,
-                waitingForContinuation: false,
-                listeners: new Set(),
-            };
-            if (disposed) {
-                await disposeSession(session).catch(() => undefined);
-                throw new Error("The AgentKit adapter was disposed during turn creation.");
-            }
-            pruneRetainedRuns(run.lastAccessedAtMs);
-            indexRun(run, turn.runId);
-            append(run, {
-                type: "run.started",
-                agentId: runtime.id,
-                metadata: runMetadata,
-            });
-            append(run, { type: "run.status", status: "running" });
-            ensurePump(run);
+            const runId = await openStartedRun(input.threadId, session, turn, turnMetadata);
             return { runId, capabilities };
         },
         async *subscribeToRun(input) {
@@ -2984,6 +3021,42 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
             });
         };
     }
+    if (runAuthority) {
+        const authority = runAuthority;
+        // Continues the turn a stopped run belonged to rather than starting a new
+        // one, so the turn's journal still blocks repeating a finished write. The
+        // server reads which run ended the turn; this page may know only the one
+        // it watched, or none after a reload.
+        transport.continueRun = async (input) => {
+            if (disposed)
+                throw new Error("The AgentKit adapter is disposed.");
+            pruneRetainedRuns();
+            const local = runs.get(input.runId);
+            if (local && local.threadId !== input.threadId) {
+                throw new Error(`Unknown AgentKit run: ${input.runId}`);
+            }
+            const session = local?.session ?? (await getSession(input.threadId));
+            if (!session.continueTurn) {
+                throw new Error("The Core runtime does not support run continuation.");
+            }
+            const state = await authority.readRunState({
+                sessionId: session.id,
+                runId: local?.turn.runId ?? input.runId,
+                abortSignal: readers.signal,
+            });
+            if (state.status === "missing" || !state.turnId) {
+                throw Object.assign(new Error(`Agent run ${input.runId} cannot be continued.`), { code: CONTINUE_UNAVAILABLE_CODE, retryable: false });
+            }
+            const turn = await session.continueTurn({
+                turnId: state.turnId,
+                prompt: AUTO_CONTINUE_PROMPT,
+                metadata: { [CONTINUE_OF_RUN_METADATA_KEY]: state.runId },
+                abortSignal: readers.signal,
+            });
+            const runId = await openStartedRun(input.threadId, session, turn, undefined, { continuedRunId: input.runId });
+            return { runId, capabilities };
+        };
+    }
     if (runtime.capabilities.rich?.connectionRequests) {
         transport.resolveConnectionRequest = async (input) => {
             pruneRetainedRuns();

package/dist/client/chat/runtime.js

@@ -1,5 +1,5 @@
 import { AgentKitRunSlotBusyError } from "@agent-native/agentkit/client";
-import { AUTO_CONTINUE_OF_RUN_METADATA_KEY } from "../../agent/auto-continue.js";
+import { AUTO_CONTINUE_OF_RUN_METADATA_KEY, CONTINUE_OF_RUN_METADATA_KEY, } from "../../agent/auto-continue.js";
 import { agentChatStreamingUrl, agentNativePath } from "../api-path.js";
 import { CHAT_REQUEST_TOO_LARGE_MESSAGE } from "../error-format.js";
 import { appendMissingFinalResponseWarning, } from "../sse-event-processor.js";
@@ -2449,12 +2449,17 @@ export function createAgentNativeChatRuntime(options = {}) {
             const approvedToolCalls = metadataStringList(turn.metadata, AGENT_NATIVE_APPROVED_TOOL_CALLS_METADATA_KEY);
             const continuationTurnId = metadataString(turn.metadata, AGENT_NATIVE_CONTINUATION_TURN_ID_METADATA_KEY);
             const autoContinueOfRunId = metadataString(turn.metadata, AUTO_CONTINUE_OF_RUN_METADATA_KEY);
+            const continueOfRunId = metadataString(turn.metadata, CONTINUE_OF_RUN_METADATA_KEY);
             const continuationMessageState = continuationTurnId
                 ? messageStates.get(continuationTurnId)
                 : undefined;
             if (continuationMessageState) {
                 messageStates.set(turnId, continuationMessageState);
             }
+            const turnEngine = turn.metadata?.engine;
+            const engine = typeof turnEngine === "string" && turnEngine.trim()
+                ? turnEngine
+                : options.engine;
             const history = nativeHistoryFromMessages(turn.messages, prompt);
             const pendingApprovalHistory = approvedToolCalls && continuationMessageState
                 ? pendingApprovalRuntimeMessages(continuationMessageState)
@@ -2481,6 +2486,7 @@ export function createAgentNativeChatRuntime(options = {}) {
                     ? { internalContinuation: true }
                     : {}),
                 ...(autoContinueOfRunId ? { autoContinueOfRunId } : {}),
+                ...(continueOfRunId ? { continueOfRunId } : {}),
                 ...(turn.metadata?.agentNativeSkipPendingSelectionContext === true
                     ? { skipPendingSelectionContext: true }
                     : {}),
@@ -2489,7 +2495,7 @@ export function createAgentNativeChatRuntime(options = {}) {
                 ...((turn.model ?? options.model)
                     ? { model: turn.model ?? options.model }
                     : {}),
-                ...(options.engine ? { engine: options.engine } : {}),
+                ...(engine ? { engine } : {}),
                 ...((turn.reasoningEffort ?? options.effort)
                     ? { effort: turn.reasoningEffort ?? options.effort }
                     : {}),
@@ -2527,8 +2533,8 @@ export function createAgentNativeChatRuntime(options = {}) {
         },
         continueTurn: ({ session, continuation, previousTurn, startTurn }) => {
             // Only the continuation that names a stopped run continues it; an approval
-            // or connection answered later is not another automatic continuation.
-            const { [AUTO_CONTINUE_OF_RUN_METADATA_KEY]: _autoContinueOf, ...previousMetadata } = previousTurn?.metadata ?? {};
+            // or connection answered later is not another continuation of that run.
+            const { [AUTO_CONTINUE_OF_RUN_METADATA_KEY]: _autoContinueOf, [CONTINUE_OF_RUN_METADATA_KEY]: _continueOf, ...previousMetadata } = previousTurn?.metadata ?? {};
             const approval = continuation.approval;
             const connection = continuation.connection;
             const messageStateKey = continuation.turnId ?? session.id;

package/dist/client/embed-auth.d.ts

@@ -2,6 +2,21 @@ export declare function readEmbedMcpChatBridgeFlagFromUrl(): boolean;
 export declare function markEmbedMcpChatBridgeActive(): void;
 export declare function isEmbedMcpChatBridgeActive(): boolean;
 export declare function getEmbedAuthToken(): string | null;
+/**
+ * True when the embed credential is a directory-widget read capability, which
+ * only the MCP App widget flows mint. It stays readable after a client
+ * navigation drops the URL params, so it identifies a widget document without
+ * the chat-bridge flag. The token's claims are only a UI hint (the signature
+ * is checked server-side), so this decides what not to attempt, never what is
+ * allowed.
+ */
+export declare function hasMcpDirectoryWidgetCapabilityToken(): boolean;
+/**
+ * True when this document is the app nested in an MCP App widget shell (the
+ * chat bridge is active) on a directory-widget read capability, which the
+ * server limits to the widget's own resource reads.
+ */
+export declare function isMcpDirectoryWidgetReadOnlyEmbed(): boolean;
 export declare function isEmbedAuthActive(): boolean;
 export declare function _resetEmbedAuthForTests(): void;
 /**

package/dist/client/embed-auth.js

@@ -1,13 +1,14 @@
 import { EMBED_MODE_QUERY_PARAM, EMBED_START_PATH, EMBED_TARGET_HEADER, EMBED_TARGET_QUERY_PARAM, EMBED_TOKEN_QUERY_PARAM, MCP_APP_CHAT_BRIDGE_QUERY_PARAM, } from "../shared/embed-auth.js";
+import { isMcpDirectoryWidgetReadCapabilityScope } from "../shared/embed-auth.js";
 import { FRAMEWORK_INTERNAL_ROUTE_PREFIX } from "../shared/framework-route-prefix.js";
+import { MCP_APP_HOST_FILL_ATTRIBUTE } from "../shared/mcp-app-display.js";
+import { EMBED_TOKEN_STORAGE_KEY, MCP_CHAT_BRIDGE_STORAGE_KEY, } from "../shared/mcp-app-widget-embed.js";
 import { SIGN_IN_ENTRY_PATH, SIGN_IN_LEGACY_ENTRY_PATH, } from "../shared/sign-in-journey.js";
 import { frameworkRoutePrefix } from "./api-path.js";
 let installed = false;
 let memoryToken = null;
 let mcpChatBridgeActive = false;
 let mcpChatBridgeScope = null;
-const EMBED_TOKEN_STORAGE_KEY = "agent-native:embed-auth-token";
-const MCP_CHAT_BRIDGE_STORAGE_KEY = "agent-native:mcp-chat-bridge";
 const AUTH_FAILURE_COOLDOWN_MS = 60_000;
 const GUARDED_METHODS = new Set(["GET", "HEAD"]);
 const AUTH_FAILURE_HEADER = "x-agent-native-auth-circuit-breaker";
@@ -146,6 +147,48 @@ export function getEmbedAuthToken() {
     }
     return memoryToken ?? storedToken(win);
 }
+function readEmbedTokenScope(token) {
+    const payload = token.split(".")[0] ?? "";
+    try {
+        const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+        const bytes = Uint8Array.from(atob(base64 + "=".repeat((4 - (base64.length % 4)) % 4)), (char) => char.charCodeAt(0));
+        const claims = JSON.parse(new TextDecoder().decode(bytes));
+        return typeof claims.scope === "string" ? claims.scope : undefined;
+        // coercion-ok: an unreadable token reads as a normal session; the server still enforces the real scope on every request.
+    }
+    catch {
+        return undefined;
+    }
+}
+let readOnlyScopeCache = null;
+/**
+ * True when the embed credential is a directory-widget read capability, which
+ * only the MCP App widget flows mint. It stays readable after a client
+ * navigation drops the URL params, so it identifies a widget document without
+ * the chat-bridge flag. The token's claims are only a UI hint (the signature
+ * is checked server-side), so this decides what not to attempt, never what is
+ * allowed.
+ */
+export function hasMcpDirectoryWidgetCapabilityToken() {
+    const token = getEmbedAuthToken();
+    if (!token)
+        return false;
+    if (readOnlyScopeCache?.token !== token) {
+        readOnlyScopeCache = {
+            token,
+            readOnly: isMcpDirectoryWidgetReadCapabilityScope(readEmbedTokenScope(token)),
+        };
+    }
+    return readOnlyScopeCache.readOnly;
+}
+/**
+ * True when this document is the app nested in an MCP App widget shell (the
+ * chat bridge is active) on a directory-widget read capability, which the
+ * server limits to the widget's own resource reads.
+ */
+export function isMcpDirectoryWidgetReadOnlyEmbed() {
+    return hasMcpDirectoryWidgetCapabilityToken() && isEmbedMcpChatBridgeActive();
+}
 export function isEmbedAuthActive() {
     const win = browserWindow();
     if (!win)
@@ -165,18 +208,22 @@ function ensureMcpChatBridgeViewportClamp(win) {
         const style = doc.createElement("style");
         style.id = MCP_CHAT_BRIDGE_VIEWPORT_STYLE_ID;
         const height = `${MCP_CHAT_BRIDGE_VIEWPORT_HEIGHT}px`;
+        // An inline card sizes itself to this document, so `100vh` must not follow
+        // the frame. A host that owns the frame's height (see
+        // mcpAppHostFillsContainer) sets the fill attribute and the clamp lifts.
+        const inline = `html:not([${MCP_APP_HOST_FILL_ATTRIBUTE}])`;
         style.textContent = `
-html,
-body {
+${inline},
+${inline} body {
   min-height: 0 !important;
   height: ${height} !important;
   max-height: ${height} !important;
   overflow: hidden !important;
 }
 
-#root,
-#__next,
-[data-agent-native-app-root] {
+${inline} #root,
+${inline} #__next,
+${inline} [data-agent-native-app-root] {
   min-height: 0 !important;
   height: ${height} !important;
   max-height: ${height} !important;
@@ -256,6 +303,7 @@ export function _resetEmbedAuthForTests() {
     }
     installed = false;
     memoryToken = null;
+    readOnlyScopeCache = null;
     mcpChatBridgeActive = false;
     mcpChatBridgeScope = null;
     authFailureCache.clear();
@@ -337,6 +385,22 @@ function isAgentNativeRuntimePath(pathname) {
         pathname.endsWith(prefix) ||
         pathname.includes(`${prefix}/`));
 }
+// What a read-only widget session is refused whatever it asks for: the agent
+// state it can never write.
+function isReadOnlyWidgetRefusedPath(pathname) {
+    return [FRAMEWORK_INTERNAL_ROUTE_PREFIX, frameworkRoutePrefix()].some((prefix) => pathname.endsWith(`${prefix}/application-state`) ||
+        pathname.includes(`${prefix}/application-state/`));
+}
+// The refusal the server's auth guard already sends such a session, answered
+// locally so each caller takes the error path it takes today without the
+// request or its console error.
+function readOnlyWidgetRefusal() {
+    return new Response(JSON.stringify({ error: "Unauthorized" }), {
+        status: 401,
+        statusText: "Unauthorized",
+        headers: { "Content-Type": "application/json" },
+    });
+}
 function requestMethod(input, init) {
     return (init?.method ??
         (input instanceof Request ? input.method : undefined) ??
@@ -480,6 +544,12 @@ export function ensureEmbedAuthFetchInterceptor() {
         return;
     const originalFetch = win.fetch.bind(win);
     const patchedFetch = (async (input, init) => {
+        if (isMcpDirectoryWidgetReadOnlyEmbed() && sameOrigin(input, win)) {
+            const url = inputUrl(input, win);
+            if (url && isReadOnlyWidgetRefusedPath(url.pathname)) {
+                return readOnlyWidgetRefusal();
+            }
+        }
         const request = requestUrlAndKey(input, init, win);
         if (request?.shouldGuard) {
             const cached = getCachedAuthFailure(request.key);

package/dist/client/host/index.d.ts

@@ -1,6 +1,6 @@
 export { initializeAgentNativeClient } from "../client-bootstrap.js";
 export { agentNativeApiDisabledReason, AgentNativeApiDisabledError, setAgentNativeApiDisabled, } from "../api-surface.js";
-export { ensureEmbedAuthFetchInterceptor, getEmbedAuthToken, isEmbedAuthActive, isEmbedMcpChatBridgeActive, } from "../embed-auth.js";
+export { ensureEmbedAuthFetchInterceptor, getEmbedAuthToken, isEmbedAuthActive, isEmbedMcpChatBridgeActive, isMcpDirectoryWidgetReadOnlyEmbed, } from "../embed-auth.js";
 export { sendToFrame, onFrameMessage, requestUserInfo, getFrameOrigin, getFramePostMessageTargetOrigin, getCallbackOrigin, oauthRedirectUri, isInFrame, isTrustedFrameMessage, enterStyleEditing, enterTextEditing, exitSelectionMode, type UserInfo, } from "../frame.js";
 export { getBuilderParentOrigin, isInBuilderFrame, sendToBuilderChat, shouldParentFrameOwnAgentPanel, isTrustedBuilderMessage, tryDelegateBuildRequestToBuilder, type BuilderChatMessage, } from "../builder-frame.js";
 export { getClientSurface, type ClientSurface } from "../client-surface.js";

package/dist/client/host/index.js

@@ -1,6 +1,6 @@
 export { initializeAgentNativeClient } from "../client-bootstrap.js";
 export { agentNativeApiDisabledReason, AgentNativeApiDisabledError, setAgentNativeApiDisabled, } from "../api-surface.js";
-export { ensureEmbedAuthFetchInterceptor, getEmbedAuthToken, isEmbedAuthActive, isEmbedMcpChatBridgeActive, } from "../embed-auth.js";
+export { ensureEmbedAuthFetchInterceptor, getEmbedAuthToken, isEmbedAuthActive, isEmbedMcpChatBridgeActive, isMcpDirectoryWidgetReadOnlyEmbed, } from "../embed-auth.js";
 export { sendToFrame, onFrameMessage, requestUserInfo, getFrameOrigin, getFramePostMessageTargetOrigin, getCallbackOrigin, oauthRedirectUri, isInFrame, isTrustedFrameMessage, enterStyleEditing, enterTextEditing, exitSelectionMode, } from "../frame.js";
 export { getBuilderParentOrigin, isInBuilderFrame, sendToBuilderChat, shouldParentFrameOwnAgentPanel, isTrustedBuilderMessage, tryDelegateBuildRequestToBuilder, } from "../builder-frame.js";
 export { getClientSurface } from "../client-surface.js";

package/dist/client/mcp-app-host.d.ts

@@ -45,6 +45,25 @@ export interface McpAppHostContextSnapshot {
     version: unknown;
     hostInfo?: McpAppHostInfo;
 }
+/**
+ * True when this document is an app running inside an MCP App widget (a
+ * ChatGPT, Codex, or Claude card or panel). The host, not the app, owns
+ * navigation and chat there, so apps drop their own navigation chrome.
+ *
+ * Being a widget is a property of the document, not of its current URL: the
+ * first positive answer is kept (and marked on `<html>`, where the first-paint
+ * script in `getMcpAppWidgetEmbedBootScriptBody` also marks it), so a client
+ * navigation that drops the embed query params, or a token swap that
+ * de-enrolls the chat bridge, never brings the app's own chrome back.
+ */
+export declare function isMcpAppWidgetEmbed(): boolean;
+export declare function useIsMcpAppWidgetEmbed(): boolean;
+/**
+ * True for a directory widget, whose scoped session can only read its own
+ * resource. Apps skip application-state writes and save-failure surfaces there
+ * instead of showing errors for requests that can never land.
+ */
+export declare function useIsMcpDirectoryWidgetReadOnlyEmbed(): boolean;
 export declare function isOpenAiMcpAppHost(): boolean;
 export declare function initializeMcpAppHost(): Promise<boolean>;
 export declare function sendMcpAppHostMessage(chat: McpAppHostChatMessage): Promise<boolean | null> | false;