@agent-native/core 0.161.7 → 0.161.9

package/corpus/templates/slides/app/context/DeckContext.tsx

@@ -112,6 +112,8 @@ export interface Slide {
   animations?: SlideAnimation[];
   /** @deprecated Use animations instead */
   splitByParagraph?: boolean;
+  /** Excluded from Present/Presenter mode playback, but stays in the deck. */
+  skipped?: boolean;
 }
 
 export type AnimationType = "appear" | "fade" | "slide-up" | "zoom";
@@ -237,6 +239,14 @@ interface DeckContextType {
   ) => void;
   deleteSlide: (deckId: string, slideId: string) => void;
   duplicateSlide: (deckId: string, slideId: string) => string | undefined;
+  /** Inserts a copy of arbitrary slide data after `afterSlideId`. Used for
+   *  slide cut/paste, where the original may already be deleted so there is
+   *  no live slide id left to duplicate from. */
+  pasteSlide: (
+    deckId: string,
+    afterSlideId: string,
+    slideFields: Omit<Slide, "id">,
+  ) => string | undefined;
   reorderSlides: (deckId: string, oldIndex: number, newIndex: number) => void;
   setDeckSlides: (deckId: string, slides: Slide[]) => void;
   /**
@@ -287,13 +297,54 @@ type DuplicateDeckActionResult = {
   url?: string;
 };
 
+/** Per-slide fields `get-deck` computes for the agent (slide position/hash
+ *  hints) that aren't part of the client's own `Slide` shape. Left on the
+ *  fetched deck, they make every server refetch look "changed" relative to
+ *  the client's slim optimistic copy — see `normalizeActionDeck`. */
+const GET_DECK_ONLY_SLIDE_FIELDS = [
+  "slideNumber",
+  "zeroBasedIndex",
+  "contentHash",
+] as const;
+
+/** Deck-level fields `get-deck` computes for the agent (counts, deep links,
+ *  the currently-selected slide) that aren't part of the client's own `Deck`
+ *  shape. See `normalizeActionDeck`. */
+const GET_DECK_ONLY_DECK_FIELDS = [
+  "slideCount",
+  "slideNumbering",
+  "deepLink",
+  "selectedSlideId",
+] as const;
+
 function normalizeActionDeck(value: unknown): Deck | null {
   if (!value || typeof value !== "object") return null;
   const deck = value as Partial<Deck>;
   if (typeof deck.id !== "string") return null;
 
+  const deckRecord = deck as unknown as Record<string, unknown>;
+  const cleanedDeck = { ...deckRecord };
+  for (const field of GET_DECK_ONLY_DECK_FIELDS) delete cleanedDeck[field];
+
+  // Strip the same decorative fields from every slide, so a deck fetched from
+  // `get-deck` is structurally identical to one built by local mutations —
+  // otherwise `deckContentSignature` sees a "change" on every refetch of the
+  // open deck and spams the undo stack with no-op `replace-deck` entries.
+  const slides = Array.isArray(deck.slides)
+    ? deck.slides.map((slide) => {
+        if (!slide || typeof slide !== "object") return slide;
+        const cleanedSlide = {
+          ...(slide as unknown as Record<string, unknown>),
+        };
+        for (const field of GET_DECK_ONLY_SLIDE_FIELDS) {
+          delete cleanedSlide[field];
+        }
+        return cleanedSlide as unknown as Slide;
+      })
+    : [];
+
   return {
-    ...deck,
+    ...cleanedDeck,
     id: deck.id,
     title: typeof deck.title === "string" ? deck.title : "Untitled",
     createdAt:
@@ -304,7 +355,7 @@ function normalizeActionDeck(value: unknown): Deck | null {
       typeof deck.updatedAt === "string"
         ? deck.updatedAt
         : deck.createdAt || "",
-    slides: Array.isArray(deck.slides) ? deck.slides : [],
+    slides,
   } as Deck;
 }
 
@@ -873,7 +924,14 @@ export function deriveInverseOp(
         // restores exactly what changed (including clearing fields back to
         // undefined).
         if (!equalDeckValue(prior[key], op.fields[key])) {
-          (priorFields as Record<string, unknown>)[key] = prior[key];
+          let priorValue: unknown = prior[key];
+          // `skipped` is undefined on a slide that was never skipped, but
+          // `undefined` doesn't survive JSON transport to the server — its
+          // `patch-slide` handler treats an absent field as "don't touch",
+          // so the persisted deck would stay skipped after undo. `false` is
+          // equivalent for this boolean field and does survive.
+          if (key === "skipped" && priorValue === undefined) priorValue = false;
+          (priorFields as Record<string, unknown>)[key] = priorValue;
         }
       }
       if (Object.keys(priorFields).length === 0) return null;
@@ -2346,6 +2404,38 @@ export function DeckProvider({ children }: { children: ReactNode }) {
     [markDeckDirty, recordUndo, setDecksLocal],
   );
 
+  const pasteSlide = useCallback(
+    (deckId: string, afterSlideId: string, slideFields: Omit<Slide, "id">) => {
+      const before = decksRef.current.find((d) => d.id === deckId);
+      if (!before) return undefined;
+
+      markDeckDirty(deckId);
+      const newSlide: Slide = { ...slideFields, id: nanoid(8) };
+      setDecksLocal((prev) =>
+        prev.map((d) => {
+          if (d.id !== deckId) return d;
+          const idx = d.slides.findIndex((s) => s.id === afterSlideId);
+          const insertAt = idx === -1 ? d.slides.length : idx + 1;
+          const slides = [...d.slides];
+          slides.splice(insertAt, 0, newSlide);
+          return { ...d, slides, updatedAt: new Date().toISOString() };
+        }),
+      );
+      // Granular add-slide op, same as duplicateSlide — inserts after
+      // afterSlideId regardless of whether that id is also the copy source.
+      const op: PatchDeckOp = {
+        op: "add-slide",
+        slideId: newSlide.id,
+        afterSlideId,
+        fields: addSlideFields(newSlide),
+      };
+      enqueueDeckOp(deckId, op);
+      recordUndo(before, op, { label: "Paste slide" });
+      return newSlide.id;
+    },
+    [markDeckDirty, recordUndo, setDecksLocal],
+  );
+
   const reorderSlides = useCallback(
     (deckId: string, oldIndex: number, newIndex: number) => {
       markDeckDirty(deckId);
@@ -2432,6 +2522,7 @@ export function DeckProvider({ children }: { children: ReactNode }) {
         updateSlide,
         deleteSlide,
         duplicateSlide,
+        pasteSlide,
         reorderSlides,
         setDeckSlides,
         markDeckDirty,

package/corpus/templates/slides/app/i18n/en-US.ts

@@ -524,6 +524,11 @@ const messages = {
     newSlide: "New slide",
     closeAddSlides: "Close",
     describeThisSlide: "Describe this slide",
+    cut: "Cut",
+    copy: "Copy",
+    paste: "Paste",
+    skipSlide: "Skip slide",
+    unskipSlide: "Unskip slide",
   },
   presentation: {
     loadFailed: "Could not load this presentation.",

package/corpus/templates/slides/app/pages/DeckEditor.tsx

@@ -60,6 +60,7 @@ import { Button } from "@/components/ui/button";
 import {
   deckIdFromPathname,
   hasUnsavedDeckChanges,
+  type Slide,
   useDecks,
   useSaveState,
 } from "@/context/DeckContext";
@@ -185,6 +186,7 @@ export default function DeckEditor() {
     updateSlide,
     deleteSlide,
     duplicateSlide,
+    pasteSlide,
     duplicateDeck,
     addSlide,
     flushDeckSave,
@@ -852,11 +854,107 @@ export default function DeckEditor() {
     return () => document.removeEventListener("keydown", handleKeyDown);
   }, [deck, id, activeSlideId, deleteSlideWithUndo, pinMode, drawMode]);
 
-  // Command/Ctrl+C then Command/Ctrl+V on the slide rail duplicates the
+  // Slide-level clipboard backing both the Cmd+C/Cmd+V shortcut below and the
+  // rail's right-click Cut/Copy/Paste menu. Holds a full slide snapshot
+  // (rather than just an id) so paste still works after Cut has already
+  // removed the original slide from the deck.
+  const slideClipboardRef = useRef<Slide | null>(null);
+  const [hasSlideClipboard, setHasSlideClipboard] = useState(false);
+
+  const copySlide = useCallback(
+    (slideId: string) => {
+      const slide = deck?.slides.find((s) => s.id === slideId);
+      if (!slide) return;
+      slideClipboardRef.current = slide;
+      setHasSlideClipboard(true);
+    },
+    [deck],
+  );
+
+  const cutSlide = useCallback(
+    (slideId: string) => {
+      if (!deck || !id || deck.slides.length <= 1) return; // don't cut the last slide
+      const slide = deck.slides.find((s) => s.id === slideId);
+      if (!slide) return;
+      slideClipboardRef.current = slide;
+      setHasSlideClipboard(true);
+      const idx = deck.slides.findIndex((s) => s.id === slideId);
+      const nextSlide = deck.slides[idx + 1] || deck.slides[idx - 1];
+      deleteSlideWithUndo(id, slideId);
+      if (activeSlideId === slideId && nextSlide) {
+        setActiveSlideId(nextSlide.id);
+      }
+    },
+    [deck, id, activeSlideId, deleteSlideWithUndo],
+  );
+
+  const pasteSlideAfter = useCallback(
+    (targetSlideId: string) => {
+      const clipboard = slideClipboardRef.current;
+      if (!clipboard || !id) return;
+      const { id: _clipboardId, ...fields } = clipboard;
+      const newId = pasteSlide(id, targetSlideId, fields);
+      if (newId) setActiveSlideId(newId);
+    },
+    [id, pasteSlide],
+  );
+
+  // Handlers backing the slide rail's right-click menu.
+  const handleDeleteSlideFromRail = useCallback(
+    (slideId: string) => {
+      if (!deck || !id || deck.slides.length <= 1) return; // don't delete the last slide
+      const idx = deck.slides.findIndex((s) => s.id === slideId);
+      const nextSlide = deck.slides[idx + 1] || deck.slides[idx - 1];
+      deleteSlideWithUndo(id, slideId);
+      if (activeSlideId === slideId && nextSlide) {
+        setActiveSlideId(nextSlide.id);
+      }
+    },
+    [deck, id, activeSlideId, deleteSlideWithUndo],
+  );
+
+  const handleDuplicateSlideFromRail = useCallback(
+    (slideId: string) => {
+      if (!id) return;
+      const newId = duplicateSlide(id, slideId);
+      if (newId) setActiveSlideId(newId);
+    },
+    [id, duplicateSlide],
+  );
+
+  const handleNewSlideAfter = useCallback(
+    (afterSlideId: string) => {
+      if (!deck || !id) return;
+      const afterIdx = deck.slides.findIndex((s) => s.id === afterSlideId);
+      // Immediate persistence: mirrors handleAddEmptySlide, since this also
+      // opens the "describe this slide" popover right away.
+      const newId = addSlide(
+        id,
+        "blank",
+        afterIdx >= 0 ? afterIdx : undefined,
+        { persistence: "immediate" },
+      );
+      setActiveSlideId(newId);
+      setSidebarOpen(true);
+      setDescribeSlideId(newId);
+    },
+    [deck, id, addSlide],
+  );
+
+  const handleToggleSkipSlide = useCallback(
+    (slideId: string) => {
+      if (!deck || !id) return;
+      const slide = deck.slides.find((s) => s.id === slideId);
+      if (!slide) return;
+      updateSlide(id, slideId, { skipped: !slide.skipped });
+    },
+    [deck, id, updateSlide],
+  );
+
+  // Command/Ctrl+C then Command/Ctrl+V on the slide rail copies/pastes the
   // selected slide directly below itself. Only claims the shortcut when no
   // slide element is selected — SlideEditor owns Cmd+C/V for object copy/paste
   // in that case.
-  const copiedSlideIdRef = useRef<string | null>(null);
   useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
       if (!deck || !id || !canEdit) return;
@@ -925,19 +1023,27 @@ export default function DeckEditor() {
 
       if (key === "c") {
         if (!activeSlideId) return;
-        copiedSlideIdRef.current = activeSlideId;
+        copySlide(activeSlideId);
         return;
       }
 
-      const copiedId = copiedSlideIdRef.current;
-      if (!copiedId || !deck.slides.some((s) => s.id === copiedId)) return;
+      if (!hasSlideClipboard || !activeSlideId) return;
       e.preventDefault();
-      const newId = duplicateSlide(id, copiedId);
-      if (newId) setActiveSlideId(newId);
+      pasteSlideAfter(activeSlideId);
     };
     document.addEventListener("keydown", handleKeyDown);
     return () => document.removeEventListener("keydown", handleKeyDown);
-  }, [deck, id, canEdit, activeSlideId, duplicateSlide, pinMode, drawMode]);
+  }, [
+    deck,
+    id,
+    canEdit,
+    activeSlideId,
+    copySlide,
+    hasSlideClipboard,
+    pasteSlideAfter,
+    pinMode,
+    drawMode,
+  ]);
 
   // Resolve the active slide from URL/deck state. Imports replace slide IDs, so
   // keep this valid after deck contents change instead of only on first load.
@@ -1371,6 +1477,14 @@ export default function DeckEditor() {
                     setGeneratingSlideSelected(true);
                     if (window.innerWidth < 768) setSidebarOpen(false);
                   }}
+                  hasSlideClipboard={hasSlideClipboard}
+                  onCutSlide={cutSlide}
+                  onCopySlide={copySlide}
+                  onPasteSlide={pasteSlideAfter}
+                  onDeleteSlide={handleDeleteSlideFromRail}
+                  onNewSlideAfter={handleNewSlideAfter}
+                  onDuplicateSlide={handleDuplicateSlideFromRail}
+                  onToggleSkipSlide={handleToggleSkipSlide}
                 />
               </DndContext>
             </div>

package/corpus/templates/videos/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "videos",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "node ../../scripts/build-retired-netlify-site.ts videos"
+  },
+  "agentNativeRetiredCompatibility": true
+}

package/dist/a2a/correlation.d.ts

@@ -3,11 +3,11 @@ export declare const MAX_A2A_CORRELATION_VALUE_CHARS = 200;
 export declare const MAX_A2A_DELEGATION_HOPS = 3;
 export declare function sanitizeA2ACorrelationId(value: unknown): string | undefined;
 /**
- * Keep only bounded, opaque ASCII correlation identifiers. These values
- * remain telemetry hints; authentication continues to come exclusively from
- * the verified A2A token/request context. `callerModel` is the one value here
- * a receiver may act on, and only as a preference — it never reaches identity,
- * org, access, or approval resolution, and it can only name a model the
- * receiver's own engine already offers (see `resolveDelegatedRunModel`).
+ * Keep only bounded, opaque ASCII correlation and routing identifiers.
+ * Authentication continues to come exclusively from the verified A2A
+ * token/request context. A receiver may use `selectedReceiverApp` only to
+ * prioritize its matching local tool surface, and `callerModel` only to choose
+ * a model its own engine already offers. Neither reaches identity, data
+ * ownership, org, access, or approval resolution.
  */
 export declare function sanitizeA2ACorrelationMetadata(value: unknown): A2ACorrelationMetadata;

package/dist/a2a/correlation.js

@@ -19,18 +19,19 @@ export function sanitizeA2ACorrelationId(value) {
     return boundedIdentifier(value, CORRELATION_ID_PATTERN);
 }
 /**
- * Keep only bounded, opaque ASCII correlation identifiers. These values
- * remain telemetry hints; authentication continues to come exclusively from
- * the verified A2A token/request context. `callerModel` is the one value here
- * a receiver may act on, and only as a preference — it never reaches identity,
- * org, access, or approval resolution, and it can only name a model the
- * receiver's own engine already offers (see `resolveDelegatedRunModel`).
+ * Keep only bounded, opaque ASCII correlation and routing identifiers.
+ * Authentication continues to come exclusively from the verified A2A
+ * token/request context. A receiver may use `selectedReceiverApp` only to
+ * prioritize its matching local tool surface, and `callerModel` only to choose
+ * a model its own engine already offers. Neither reaches identity, data
+ * ownership, org, access, or approval resolution.
  */
 export function sanitizeA2ACorrelationMetadata(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return {};
     const metadata = value;
     const callerApp = boundedIdentifier(metadata.callerApp, APP_ID_PATTERN);
+    const selectedReceiverApp = boundedIdentifier(metadata.selectedReceiverApp, APP_ID_PATTERN);
     const callerThreadId = sanitizeA2ACorrelationId(metadata.callerThreadId);
     const parentRunId = sanitizeA2ACorrelationId(metadata.parentRunId);
     const parentTurnId = sanitizeA2ACorrelationId(metadata.parentTurnId);
@@ -62,6 +63,7 @@ export function sanitizeA2ACorrelationMetadata(value) {
                 : undefined;
     return {
         ...(callerApp ? { callerApp } : {}),
+        ...(selectedReceiverApp ? { selectedReceiverApp } : {}),
         ...(callerThreadId ? { callerThreadId } : {}),
         ...(parentRunId ? { parentRunId } : {}),
         ...(parentTurnId ? { parentTurnId } : {}),

package/dist/a2a/types.d.ts

@@ -117,14 +117,16 @@ export interface A2ASourceContextReference {
     integrationTaskId: string;
 }
 /**
- * Telemetry-only cross-app correlation, plus `callerModel` — a preference
- * hint. Receivers must never use any caller-supplied value here for identity,
- * ownership, org scoping, access, or approval decisions. `callerModel` widens
- * this channel to a preference, never to an authorization: it may at most pick
- * a model the receiver's already-resolved engine advertises.
+ * Bounded cross-app correlation and routing preferences. Receivers must never
+ * use any caller-supplied value here for identity, data ownership, org scoping,
+ * access, or approval decisions. `selectedReceiverApp` may only prioritize the
+ * matching receiver's local tool surface, while `callerModel` may only pick a
+ * model the receiver's already-resolved engine advertises.
  */
 export interface A2ACorrelationMetadata {
     callerApp?: string;
+    /** App the caller deliberately selected for this delegated objective. */
+    selectedReceiverApp?: string;
     callerThreadId?: string;
     parentRunId?: string;
     parentTurnId?: string;

package/dist/client/RuntimeConfigNotice.js

@@ -3,6 +3,7 @@ import { IconAlertCircle, IconAlertTriangle, IconCheck, IconChevronDown, IconChe
 import { useEffect, useMemo, useState } from "react";
 import { parseRuntimeConfigReport, } from "../shared/runtime-config.js";
 import { agentNativePath } from "./api-path.js";
+import { agentNativeApiDisabledReason } from "./api-surface.js";
 import { writeClipboardText } from "./clipboard.js";
 import { useT } from "./i18n.js";
 function injectedAppConfig() {
@@ -31,6 +32,8 @@ export function RuntimeConfigNotice() {
     useEffect(() => {
         if (typeof window.fetch !== "function")
             return;
+        if (agentNativeApiDisabledReason())
+            return;
         const controller = new AbortController();
         let active = true;
         const timeout = window.setTimeout(() => controller.abort(), 5000);

package/dist/client/api-surface.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Some surfaces are framed by a host and carry no agent-native session at all —
+ * Builder's Design tab frames a canvas that owns no design row and holds no
+ * credential. Every `/_agent-native/*` call from one is unauthenticated by
+ * construction, so the client must not make them: a 401 per poll buries real
+ * failures, and a write can never land.
+ */
+/** Pass `null` to re-enable, so a surface can be entered and left. */
+export declare function setAgentNativeApiDisabled(reason: string | null): void;
+export declare function agentNativeApiDisabledReason(): string | null;
+/**
+ * Thrown rather than resolved: a caller that cannot tell "no backend" from
+ * "empty result" reports success for work that never happened.
+ */
+export declare class AgentNativeApiDisabledError extends Error {
+    readonly reason: string;
+    constructor(detail: string);
+}
+export declare function assertAgentNativeApiEnabled(detail: string): void;

package/dist/client/api-surface.js

@@ -0,0 +1,32 @@
+/**
+ * Some surfaces are framed by a host and carry no agent-native session at all —
+ * Builder's Design tab frames a canvas that owns no design row and holds no
+ * credential. Every `/_agent-native/*` call from one is unauthenticated by
+ * construction, so the client must not make them: a 401 per poll buries real
+ * failures, and a write can never land.
+ */
+let disabledReason = null;
+/** Pass `null` to re-enable, so a surface can be entered and left. */
+export function setAgentNativeApiDisabled(reason) {
+    disabledReason = reason?.trim() ? reason.trim() : null;
+}
+export function agentNativeApiDisabledReason() {
+    return disabledReason;
+}
+/**
+ * Thrown rather than resolved: a caller that cannot tell "no backend" from
+ * "empty result" reports success for work that never happened.
+ */
+export class AgentNativeApiDisabledError extends Error {
+    reason;
+    constructor(detail) {
+        const reason = disabledReason ?? "unknown surface";
+        super(`agent-native API is disabled on this surface (${reason}): ${detail}`);
+        this.name = "AgentNativeApiDisabledError";
+        this.reason = reason;
+    }
+}
+export function assertAgentNativeApiEnabled(detail) {
+    if (disabledReason)
+        throw new AgentNativeApiDisabledError(detail);
+}

package/dist/client/application-state.js

@@ -1,4 +1,5 @@
 import { agentNativePath } from "./api-path.js";
+import { assertAgentNativeApiEnabled } from "./api-surface.js";
 const APP_STATE_KEY_PATTERN = /^[a-zA-Z0-9_:-]+$/;
 function appStateUrl(key) {
     if (!APP_STATE_KEY_PATTERN.test(key)) {
@@ -63,6 +64,7 @@ function jsonBody(value) {
 /** Server caps a batch at 100 keys; stay under it when splitting. */
 const MAX_BATCH_KEYS = 100;
 export async function readClientAppStateMany(keys, options = {}) {
+    assertAgentNativeApiEnabled(`read application state [${keys.join(", ")}]`);
     const unique = [...new Set(keys)];
     for (const key of unique)
         appStateUrl(key); // validates the key shape
@@ -142,6 +144,7 @@ export async function readClientAppState(key, options = {}) {
     return (batch.values[key] ?? null);
 }
 export async function writeClientAppState(key, value, options = {}) {
+    assertAgentNativeApiEnabled(`write application state "${key}"`);
     const response = await fetch(appStateUrl(key), {
         method: "PUT",
         headers: buildHeaders(options.requestSource),
@@ -152,6 +155,7 @@ export async function writeClientAppState(key, value, options = {}) {
     return parseAppStateResponse(response, `Write application state "${key}"`);
 }
 export async function deleteClientAppState(key, options = {}) {
+    assertAgentNativeApiEnabled(`delete application state "${key}"`);
     const response = await fetch(appStateUrl(key), {
         method: "DELETE",
         // DELETE carries no JSON body, so this custom header is the only

package/dist/client/builder-frame.d.ts

@@ -19,6 +19,12 @@ export interface BuilderChatMessage {
     submit?: boolean;
     mode?: "act" | "plan";
     requestMode?: "act" | "plan";
+    /**
+     * Origin an embedder already verified for itself. `getBuilderParentOrigin()`
+     * needs `?builder.*` params to trust a loopback parent, which a handshake-based
+     * embed never carries — without this the message falls back to `"*"`.
+     */
+    targetOrigin?: string;
 }
 export declare function sendToBuilderChat(opts: BuilderChatMessage): boolean;
 /**

package/dist/client/builder-frame.js

@@ -116,7 +116,7 @@ export function sendToBuilderChat(opts) {
     if (typeof window === "undefined" || !opts.message?.trim())
         return false;
     const hasParentFrame = window.parent !== window;
-    const targetOrigin = getBuilderParentOrigin() ?? "*";
+    const targetOrigin = opts.targetOrigin ?? getBuilderParentOrigin() ?? "*";
     const payload = {
         type: "builder.submitChat",
         data: {

package/dist/client/client-status-requests.js

@@ -1,4 +1,5 @@
 import { agentNativePath } from "./api-path.js";
+import { agentNativeApiDisabledReason } from "./api-surface.js";
 const RESULT_TTL_MS = 500;
 const REQUEST_TIMEOUT_MS = 15_000;
 const cache = new Map();
@@ -31,6 +32,10 @@ function installInvalidationListeners() {
     }
 }
 async function fetchClientStatus(path) {
+    // "unavailable" rather than a fabricated payload: callers already treat it as
+    // "could not read", and there is genuinely nothing to read here.
+    if (agentNativeApiDisabledReason())
+        return { state: "unavailable" };
     installInvalidationListeners();
     const url = agentNativePath(path);
     const cached = cache.get(url);

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

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

package/dist/client/host/index.js

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

package/dist/client/use-action.d.ts

@@ -73,7 +73,7 @@ export declare const ACTION_KEEPALIVE_BODY_BUDGET_BYTES = 48000;
  * `/_agent-native/actions/*` in components.
  */
 export declare function callAction<TResult = undefined, TName extends ActionName = ActionName>(actionName: TName, params?: ActionParams<TName>, options?: ClientActionCallOptions): Promise<TResult extends undefined ? ActionResult<TName> : TResult>;
-export type KeepaliveActionCallRejectionReason = "body-too-large" | "budget-exhausted";
+export type KeepaliveActionCallRejectionReason = "body-too-large" | "budget-exhausted" | "api-disabled";
 export type KeepaliveActionCallResult<TResult> = {
     accepted: true;
     bodyBytes: number;

package/dist/client/use-action.js

@@ -27,6 +27,7 @@ import { getAnalyticsClientPlatform } from "./analytics-platform.js";
 import { getOrCreateAnalyticsSessionId } from "./analytics-session.js";
 import { trackEvent } from "./analytics.js";
 import { agentNativePath } from "./api-path.js";
+import { agentNativeApiDisabledReason, assertAgentNativeApiEnabled, } from "./api-surface.js";
 import { getBrowserTabId } from "./browser-tab-id.js";
 import { clientBuildId, clientCompatibilityVersion, reloadForClientCompatibilityMismatch, } from "./build-compatibility.js";
 import { ensureEmbedAuthFetchInterceptor } from "./embed-auth.js";
@@ -398,6 +399,7 @@ function shouldTrackActionResponse(error, durationMs, response) {
     return Math.random() < rate;
 }
 async function actionFetch(name, method, params, options) {
+    assertAgentNativeApiEnabled(`${method} ${name}`);
     const startedAt = actionTelemetryNow();
     let response;
     let responseAt;
@@ -501,6 +503,16 @@ export function callAction(actionName, params, options = {}) {
 export function tryCallActionKeepalive(actionName, params, options = {}) {
     const serializedBody = JSON.stringify(params ?? {});
     const bodyBytes = utf8ByteLength(serializedBody);
+    // Reported as a refusal rather than thrown: callers keep the work queued on
+    // `accepted: false`, which is the honest outcome for a surface with no backend.
+    if (agentNativeApiDisabledReason()) {
+        return {
+            accepted: false,
+            bodyBytes,
+            reason: "api-disabled",
+            completion: null,
+        };
+    }
     if (bodyBytes > ACTION_KEEPALIVE_BODY_BUDGET_BYTES) {
         return {
             accepted: false,
@@ -547,6 +559,10 @@ export function tryCallActionKeepalive(actionName, params, options = {}) {
  * ```
  */
 export function useActionQuery(actionName, params, options) {
+    // Not `enabled: false` via options: a disabled surface must win over whatever
+    // the caller asked for, and an unfired query reads as "no data" rather than
+    // as an error the UI has to special-case.
+    const apiDisabled = Boolean(agentNativeApiDisabledReason());
     return useQuery({
         queryKey: ["action", actionName, params],
         // Thread React Query's per-fetch AbortSignal into the network request so
@@ -556,6 +572,7 @@ export function useActionQuery(actionName, params, options) {
         retry: defaultActionQueryRetry,
         retryDelay: defaultActionQueryRetryDelay,
         ...options,
+        ...(apiDisabled ? { enabled: false } : {}),
     });
 }
 // ---------------------------------------------------------------------------

package/dist/client/use-session.js

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useState } from "react";
 import { setSentryUser, trackSessionStatus } from "./analytics.js";
+import { agentNativeApiDisabledReason } from "./api-surface.js";
 import { fetchAuthSessionStatus, invalidateClientStatusRequest, } from "./client-status-requests.js";
 import { getFrameOrigin, getFramePostMessageTargetOrigin } from "./frame.js";
 const SESSION_CACHE_TTL_MS = 30_000;
@@ -98,6 +99,10 @@ export function notifySessionInvalidated() {
     }
 }
 function fetchSharedSession() {
+    // A surface with no agent-native backend is genuinely signed out. `undefined`
+    // would read as "unavailable" and retry until it gave up with an error.
+    if (agentNativeApiDisabledReason())
+        return Promise.resolve(null);
     if (hasFreshSessionCache())
         return Promise.resolve(cachedSession ?? null);
     if (sessionRequest)