@agent-native/core 0.210.2 → 0.211.0-nightly-20261020183616

package/dist/action.d.ts

@@ -661,6 +661,14 @@ export declare function actionCallIntent(entry: {
  * share one, so none can change what another reads.
  */
 export declare function preparedCallArguments(call: PreparedActionCall): unknown;
+/**
+ * Whether `call` needs a person's approval before it runs, by the action's
+ * `needsApproval`. Every surface that can run an action decides with this, so
+ * a predicate means the same thing to the agent loop, MCP, and HTTP.
+ */
+export declare function preparedCallNeedsApproval(entry: {
+    needsApproval?: boolean | ((args: any, ctx?: ActionRunContext) => boolean | Promise<boolean>);
+}, call: PreparedActionCall, ctx: ActionRunContext): Promise<boolean>;
 /**
  * @internal Executes a prepared call: `entry.run` receives its own copy of the
  * prepared arguments, which the action's input validation and classification

package/dist/action.js

@@ -1398,6 +1398,23 @@ export function preparedCallArguments(call) {
     }
     return copyActionArguments(prepared.snapshot);
 }
+/**
+ * Whether `call` needs a person's approval before it runs, by the action's
+ * `needsApproval`. Every surface that can run an action decides with this, so
+ * a predicate means the same thing to the agent loop, MCP, and HTTP.
+ */
+export async function preparedCallNeedsApproval(entry, call, ctx) {
+    const gate = entry.needsApproval;
+    if (typeof gate !== "function")
+        return gate === true;
+    try {
+        return Boolean(await gate(preparedCallArguments(call), ctx));
+    }
+    catch {
+        // coercion-ok: a predicate that cannot decide fails closed and asks.
+        return true;
+    }
+}
 /**
  * @internal Executes a prepared call: `entry.run` receives its own copy of the
  * prepared arguments, which the action's input validation and classification

package/dist/agent/production-agent.js

@@ -8,7 +8,7 @@ import { parseA2AAgentActivityPart } from "../a2a/activity.js";
 import { actionCallIsRetrySafe, actionChangeResource, classifyActionCall, } from "../action-call-classification.js";
 import { runOutsideActionInvocation, vouchedOutcome } from "../action-frame.js";
 import { ACTION_CHAT_UI_RECORD_CHANGE_RENDERER, normalizeActionChangeResult, } from "../action-ui.js";
-import { AgentConnectionRequiredError, describeToolParameterSignature, isActionContractError, isActionHiddenFromEveryAgentSurface, isAgentActionStopError, isAgentConnectionRequiredError, actionCallIntent, invocationEffect, runPreparedActionCall, boundActionCallIntent, preparedCallArguments, recordInvalidActionCall, stripUnsupportedSchemaKeywords, } from "../action.js";
+import { AgentConnectionRequiredError, describeToolParameterSignature, isActionContractError, isActionHiddenFromEveryAgentSurface, isAgentActionStopError, isAgentConnectionRequiredError, actionCallIntent, invocationEffect, runPreparedActionCall, boundActionCallIntent, preparedCallArguments, preparedCallNeedsApproval, recordInvalidActionCall, stripUnsupportedSchemaKeywords, } from "../action.js";
 import { getAppConfig } from "../app-config/index.js";
 import { MAX_BACKGROUND_RUN_CONTINUATIONS, MAX_CONSECUTIVE_NO_PROGRESS_CONTINUATIONS, MAX_TURN_WALL_CLOCK_MS, } from "../app-config/run-lifecycle-invariants.js";
 import { readAppState } from "../application-state/script-helpers.js";
@@ -6131,25 +6131,16 @@ export async function runAgentLoop(opts) {
                 ? await opts.consumeApproval(approvalBinding())
                 : requestedApproval;
             if (actionEntry.needsApproval && !wasApproved) {
-                let mustApprove = false;
-                try {
-                    mustApprove =
-                        typeof actionEntry.needsApproval === "function"
-                            ? Boolean(await actionEntry.needsApproval(preparedCallArguments(intent), {
-                                userEmail: getRequestUserEmail(),
-                                orgId: getRequestOrgId() ?? null,
-                                appId: opts.appId,
-                                caller: opts.actionCaller ?? "tool",
-                                automation: opts.automation,
-                                networkProtocol: opts.networkProtocol,
-                                networkId: opts.networkId,
-                                networkPeer: opts.networkPeer,
-                            }))
-                            : actionEntry.needsApproval === true;
-                }
-                catch {
-                    mustApprove = true;
-                }
+                let mustApprove = await preparedCallNeedsApproval(actionEntry, intent, {
+                    userEmail: getRequestUserEmail(),
+                    orgId: getRequestOrgId() ?? null,
+                    appId: opts.appId,
+                    caller: opts.actionCaller ?? "tool",
+                    automation: opts.automation,
+                    networkProtocol: opts.networkProtocol,
+                    networkId: opts.networkId,
+                    networkPeer: opts.networkPeer,
+                });
                 if (mustApprove &&
                     actionEntry.allowPersistentApproval !== false &&
                     opts.isToolAlwaysAllowed) {

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

@@ -1077,9 +1077,15 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
         }
         return activeOwners[0] ?? owners.at(-1);
     }
-    function indexRun(run, runtimeRunId = run.turn.runId ?? run.runId) {
+    function indexRun(run, runtimeRunId = run.turn.runId ?? run.runId, allowReplay = false) {
         const existingRun = runs.get(run.runId);
         if (existingRun && existingRun !== run) {
+            if (allowReplay &&
+                existingRun.threadId === run.threadId &&
+                existingRun.turn.id !== undefined &&
+                existingRun.turn.id === run.turn.id) {
+                return existingRun;
+            }
             throw new Error(`Duplicate AgentKit run id: ${run.runId}`);
         }
         if (runtimeRunId && runtimeRunId !== run.runId) {
@@ -1098,6 +1104,7 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
             runtimeRunAliases.set(aliasKey, run);
         }
         runs.set(run.runId, run);
+        return run;
     }
     async function resolveRuntimeRunOwner(threadId, runtimeRunId, sessionId, authorityRead) {
         if (!runAuthority)
@@ -1468,7 +1475,11 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
                 : {}),
             listeners: new Set(),
         };
-        indexRun(run, turn.runId ?? input.runId);
+        const indexedRun = indexRun(run, turn.runId ?? input.runId, true);
+        if (indexedRun !== run) {
+            await closeDiscardedTurnEvents(turn);
+            return indexedRun;
+        }
         if (restoreRead)
             run.initialAuthorityRead = restoreRead;
         if (state && "pendingConnectionRequestId" in state) {
@@ -1488,7 +1499,7 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
      * 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) {
+    async function openStartedRun(threadId, session, turn, turnMetadata, observability, start = {}) {
         const runId = turn.runId ?? turn.id ?? createId("run");
         const runMetadata = mergeTrustedProtocolMetadata(options.metadata, turnMetadata, turn.metadata, {
             [AGENT_NATIVE_PROTOCOL_METADATA_KEY]: {
@@ -1535,8 +1546,34 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
             await disposeSession(session).catch(() => undefined);
             throw new Error("The AgentKit adapter was disposed during turn creation.");
         }
+        const existingRun = start.attachReplayedRun
+            ? findRun(threadId, runId)
+            : undefined;
+        if (existingRun) {
+            // A duplicate queued submission is answered with the run that already
+            // took it, replayed from its first event. This adapter reads that run
+            // already, so the replay is drained rather than indexed a second time.
+            // The replayed stream stays open until the run ends; closing it early
+            // needs a transport abort, because turn.cancel would cancel the run.
+            void (async () => {
+                for await (const _event of turn.events) {
+                    // Discarded: the existing run delivers these events.
+                }
+            })().catch((error) => {
+                console.warn(`[agentkit] replayed stream for run ${runId} failed`, error);
+            });
+            touchRun(existingRun);
+            ensurePump(existingRun);
+            // A runtime alias resolves to the run that owns it, which may use a
+            // different protocol id; the caller must address that run.
+            return existingRun.runId;
+        }
         pruneRetainedRuns(run.lastAccessedAtMs);
-        indexRun(run, turn.runId);
+        const indexedRun = indexRun(run, turn.runId, true);
+        if (indexedRun !== run) {
+            await closeDiscardedTurnEvents(turn);
+            return indexedRun.runId;
+        }
         append(run, {
             type: "run.started",
             agentId: runtime.id,
@@ -1552,6 +1589,10 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
         disposedSessions.add(session);
         await session.dispose?.();
     }
+    async function closeDiscardedTurnEvents(turn) {
+        const iterator = turn.events[Symbol.asyncIterator]();
+        await Promise.all([turn.closeEvents?.(), iterator.return?.()]);
+    }
     function append(run, event) {
         const lastType = run.events.at(-1)?.type;
         const terminalStatus = event.type === "run.completed" ||
@@ -3082,7 +3123,9 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
                     metadata: turnMetadata,
                     abortSignal: readers.signal,
                 });
-                return openStartedRun(input.threadId, session, turn, turnMetadata);
+                return openStartedRun(input.threadId, session, turn, turnMetadata, undefined, {
+                    attachReplayedRun: true,
+                });
             };
             if (!queuePromotionKey) {
                 return { runId: await createRun(), capabilities };

package/dist/client/chat/runtime.d.ts

@@ -550,6 +550,8 @@ export interface AgentChatRuntimeTurn<TEvent extends AgentChatRuntimeEventBase =
     readonly runId?: string;
     readonly metadata?: AgentChatRuntimeMetadata;
     readonly events: AsyncIterable<TEvent>;
+    /** Close the local event stream without cancelling the underlying run. */
+    closeEvents?(): Promise<void> | void;
     cancel?(input?: AgentChatRuntimeCancelInput): Promise<AgentChatRuntimeCancelResult>;
 }
 export interface AgentChatRuntimeSendMessageInput extends AgentChatRuntimeTurnInput {

package/dist/client/chat/runtime.js

@@ -504,13 +504,18 @@ export function createHttpAgentChatRuntime(options) {
                     cleanup();
                 }
             })();
+            const closeEvents = () => {
+                controller.abort();
+                cleanup();
+            };
             return {
                 id: turnId,
                 sessionId,
                 runId,
                 events,
+                closeEvents,
                 cancel: async (cancelInput) => {
-                    controller.abort();
+                    closeEvents();
                     if (!options.cancelEndpoint)
                         return { status: "cancelled" };
                     const endpoint = typeof options.cancelEndpoint === "function"

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

@@ -6,7 +6,7 @@ export { useDemoModeStatus, type DemoModeStatus, } from "../use-demo-mode-status
 export { useReconciledState } from "../use-external-value.js";
 export { beginSignOut, isSigningOut, notifySessionInvalidated, useSession, type AuthSession, } from "../use-session.js";
 export { signOut, type SignOutOptions } from "../sign-out.js";
-export { ACTION_KEEPALIVE_BODY_BUDGET_BYTES, actionErrorMessage, callAction, callActionBlob, callActionWithRetry, tryCallActionKeepalive, useActionQuery, useActionMutation, type ActionRegistry, type ClientActionCallOptions, type ClientActionMethod, type RetriedActionCallOptions, type KeepaliveActionCallRejectionReason, type KeepaliveActionCallResult, } from "../use-action.js";
+export { ACTION_KEEPALIVE_BODY_BUDGET_BYTES, actionErrorMessage, callAction, callActionBlob, callActionWithRetry, currentActionQueryCacheBinding, recordActionQueryBrowserPersist, tryCallActionKeepalive, useActionQuery, useActionMutation, type ActionRegistry, type ClientActionCallOptions, type ClientActionMethod, type RetriedActionCallOptions, type KeepaliveActionCallRejectionReason, type KeepaliveActionCallResult, } from "../use-action.js";
 export { actionErrorCode, isTerminalActionError, } from "../action-failure-circuit.js";
 export { createAgentNativeQueryClient } from "../create-query-client.js";
 export { APP_CHAT_SIDEBAR_STATE_EVENT, APP_CHAT_SIDEBAR_STATE_MESSAGE, APP_CHAT_SIDEBAR_STATE_REQUEST_MESSAGE, buildAppChatSidebarStateMessage, buildAppChatSidebarStateRequest, isPerAppChatStorageKey, requestPerAppChatCommand, usePerAppChatState, usePerAppChatOpen, type AppChatSidebarCommand, type AppChatSidebarState, } from "../app-chat-sidebar.js";

package/dist/client/hooks/index.js

@@ -6,7 +6,7 @@ export { useDemoModeStatus, } from "../use-demo-mode-status.js";
 export { useReconciledState } from "../use-external-value.js";
 export { beginSignOut, isSigningOut, notifySessionInvalidated, useSession, } from "../use-session.js";
 export { signOut } from "../sign-out.js";
-export { ACTION_KEEPALIVE_BODY_BUDGET_BYTES, actionErrorMessage, callAction, callActionBlob, callActionWithRetry, tryCallActionKeepalive, useActionQuery, useActionMutation, } from "../use-action.js";
+export { ACTION_KEEPALIVE_BODY_BUDGET_BYTES, actionErrorMessage, callAction, callActionBlob, callActionWithRetry, currentActionQueryCacheBinding, recordActionQueryBrowserPersist, tryCallActionKeepalive, useActionQuery, useActionMutation, } from "../use-action.js";
 export { actionErrorCode, isTerminalActionError, } from "../action-failure-circuit.js";
 export { createAgentNativeQueryClient } from "../create-query-client.js";
 export { APP_CHAT_SIDEBAR_STATE_EVENT, APP_CHAT_SIDEBAR_STATE_MESSAGE, APP_CHAT_SIDEBAR_STATE_REQUEST_MESSAGE, buildAppChatSidebarStateMessage, buildAppChatSidebarStateRequest, isPerAppChatStorageKey, requestPerAppChatCommand, usePerAppChatState, usePerAppChatOpen, } from "../app-chat-sidebar.js";

package/dist/client/resources/mcp-integration-logos.js

@@ -223,6 +223,10 @@ const LOGOS = {
         mime: "image/svg+xml",
         data: "PHN2ZyBmaWxsPSIjRTM3NDAwIiByb2xlPSJpbWciIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48dGl0bGU+R29vZ2xlIEFuYWx5dGljczwvdGl0bGU+PHBhdGggZD0iTTIyLjg0IDIuOTk4MnYxNy45OTg3Yy4wMDg2IDEuNjQ3My0xLjMxOTcgMi45ODk3LTIuOTY3IDIuOTk4NGEyLjk4MDggMi45ODA4IDAgMDEtLjM2NzctLjAyMDhjLTEuNTI4LS4yMjYtMi42NDc3LTEuNTU1OC0yLjYxMDUtMy4xVjMuMTIwNGMtLjAzNjktMS41NDU4IDEuMDg1Ni0yLjg3NjIgMi42MTU3LTMuMSAxLjYzNjEtLjE5MTUgMy4xMTc4Ljk3OTYgMy4zMDkzIDIuNjE1OC4wMTQuMTIwMS4wMjA4LjI0MS4wMjAyLjM2MTl6TTQuMTMyNiAxOC4wNTQ4Yy0xLjY0MTcgMC0yLjk3MjYgMS4zMzEtMi45NzI2IDIuOTcyNkMxLjE2IDIyLjY2OTEgMi40OTA5IDI0IDQuMTMyNiAyNHMyLjk3MjYtMS4zMzA5IDIuOTcyNi0yLjk3MjYtMS4zMzEtMi45NzI2LTIuOTcyNi0yLjk3MjZ6bTcuODcyOC05LjAwOThjLS4wMTcxIDAtLjAzNDIgMC0uMDUxMy4wMDAzLTEuNjQ5NS4wOTA0LTIuOTI5MyAxLjQ3NC0yLjg5MSAzLjEyNTZ2Ny45ODQ2YzAgMi4xNjcuOTUzNSAzLjQ4MjUgMi4zNTA1IDMuNzYzIDEuNjExOC4zMjY2IDMuMTgzMi0uNzE1MiAzLjUwOTgtMi4zMjcuMDQtLjE5NzQuMDYtLjM5ODMuMDU5My0uNTk5OHYtOC45NTg1Yy4wMDMtMS42NDc0LTEuMzMtMi45ODUyLTIuOTc3My0yLjk4ODJ6Ii8+PC9zdmc+",
     },
+    "google-search-console": {
+        mime: "image/svg+xml",
+        data: "PHN2ZyBmaWxsPSIjNDU4Q0Y1IiByb2xlPSJpbWciIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48dGl0bGU+R29vZ2xlIFNlYXJjaCBDb25zb2xlPC90aXRsZT48cGF0aCBkPSJNOC41NDggMS4xNTZMNi44MzIgMi44NzJ2MS42ODJoMS43MTZ6bTAgMy4zOTh2LjAzNUg2LjgzMnYtLjAzNUgzLjM4NkwwIDcuODQ0djMuNTc3aDIuODI2VjguOTRjMC0uNTI1LjQyOS0uOTU0Ljk1NC0uOTU0aDE2LjQ3NmMuNTI1IDAgLjk1NC40My45NTQuOTU0djIuNDhoMi43NTRWNy44NDRsLTMuMzg2LTMuMjlIMTcuM3YuMDM1aC0xLjcxN3YtLjAzNXptNy4wMzUgMEgxNy4zVjIuODcybC0xLjcxNy0xLjcxNnpNOC42NzkgMS4xODhWMi44NGg2Ljc3M1YxLjE4OHptMTEuNDcxIDcuMDdhLjgzNC44MzQgMCAwMC0uMTMyLjAxbC0uNTQzLjAwMmMtNS4yMTYuMDE0LTEwLjQzMi0uMDA4LTE1LjY0OC4wMS0uNDM1LS4wNjMtLjc5NC40MzYtLjcxNi44ODN2Mi4yNjRoMTcuODEyYy0uMDE2LS44ODguMDQ1LTEuNzgyLS4wMzQtMi42NjYtLjEwNC0uMzQyLS40MjctLjUwMi0uNzM5LS41MDJ6bS0xNS40MjIuNjM0YS42ODkuNjk4IDAgMDEuNjg5LjY5OC42ODkuNjk4IDAgMDEtLjY4OS42OTcuNjg5LjY5OCAwIDAxLS42ODgtLjY5Ny42ODkuNjk4IDAgMDEuNjg4LS42OTh6bTIuMTM0IDBhLjY4OS42OTggMCAwMS42ODkuNjk4LjY4OS42OTggMCAwMS0uNjg5LjY5Ny42ODkuNjk4IDAgMDEtLjY4OC0uNjk3LjY4OS42OTggMCAwMS42ODgtLjY5OHpNLjAzNiAxMS42NDV2OS4xNTZjMCAxLjA1Ljg1OCAxLjkwOCAxLjkwNyAxLjkwOGguODgzVjExLjY0NXptMjEuMTc0IDB2MTEuMDY0aC44ODJjMS4wNSAwIDEuOTA4LS44NTggMS45MDgtMS45MDh2LTkuMTU2ek00LjA1NyAxMy4xMzN2Ni44NWg2LjEzN3YtNi44NXptMTMuMjQzLjAyMXYzLjc3N2wtMS43MDguOTc3LTEuNzA4LS45Nzd2LTMuNzU4YTQuMDA2IDQuMDA2IDAgMDAwIDcuMjN2Mi40NDFoMy40NTd2LTIuNDQyYTQuMDA2IDQuMDA2IDAgMDAtLjA0MS03LjI0OHptLTEzLjI0MyA4LjI2djEuNDNoNy45MjV2LTEuNDN6Ii8+PC9zdmc+",
+    },
     "google-sheets": {
         mime: "image/svg+xml",
         data: "PHN2ZyBmaWxsPSIjMzRBODUzIiByb2xlPSJpbWciIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48dGl0bGU+R29vZ2xlIFNoZWV0czwvdGl0bGU+PHBhdGggZD0iTTExLjMxOCAxMi41NDVINy45MXYtMS45MDloMy40MXYxLjkxek0xNC43MjggMHY2aDZsLTYtNnptMS4zNjMgMTAuNjM2aC0zLjQxdjEuOTFoMy40MXYtMS45MXptMCAzLjI3M2gtMy40MXYxLjkxaDMuNDF2LTEuOTF6TTIwLjcyNyA2LjV2MTUuODY0YzAgLjkwNC0uNzMyIDEuNjM2LTEuNjM2IDEuNjM2SDQuOTA5YTEuNjM2IDEuNjM2IDAgMCAxLTEuNjM2LTEuNjM2VjEuNjM2QzMuMjczLjczMiA0LjAwNSAwIDQuOTA5IDBoOS4zMTh2Ni41aDYuNXptLTMuMjczIDIuNzczSDYuNTQ1djcuOTA5aDEwLjkxdi03Ljkxem0tNi4xMzYgNC42MzZINy45MXYxLjkxaDMuNDF2LTEuOTF6Ii8+PC9zdmc+",

package/dist/client/session-identity.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The identity of the session this tab last read: a string when signed in,
+ * `null` when known to be signed out (or signing out), `undefined` before the
+ * first read. Kept apart from `use-session` so action fetches can read it
+ * without depending on the session hook.
+ */
+export declare function currentSessionIdentity(): string | null | undefined;
+export declare function recordSessionIdentity(value: string | null | undefined): void;

package/dist/client/session-identity.js

@@ -0,0 +1,13 @@
+let identity;
+/**
+ * The identity of the session this tab last read: a string when signed in,
+ * `null` when known to be signed out (or signing out), `undefined` before the
+ * first read. Kept apart from `use-session` so action fetches can read it
+ * without depending on the session hook.
+ */
+export function currentSessionIdentity() {
+    return identity;
+}
+export function recordSessionIdentity(value) {
+    identity = value;
+}

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

@@ -44,6 +44,8 @@ export interface ClientActionCallOptions {
     headers?: Record<string, string>;
     /** Set when the action is declared `uiOnly`, so its first request carries the UI capability. */
     uiOnly?: boolean;
+    /** Sees each HTTP response, e.g. to pass to `recordActionQueryBrowserPersist`. */
+    onResponse?: (response: Response) => void;
 }
 export declare function serializeActionQueryParams(params: Record<string, any>): string;
 export interface ActionFetchOptions {
@@ -56,6 +58,8 @@ export interface ActionFetchOptions {
     headers?: Record<string, string>;
     uiOnly?: boolean;
 }
+/** Drop the remembered capability so the next call that needs one mints it. */
+export declare function forgetUiActionCapability(): void;
 export declare const ACTION_KEEPALIVE_BODY_BUDGET_BYTES = 48000;
 /**
  * `undefined` when there is no document to ask (SSR, a non-browser caller) —
@@ -121,6 +125,16 @@ export declare function isBrowserPersistableActionQueryForBinding(query: Query,
 /** @internal used only after a persisted action result is accepted and hydrated. */
 export declare function markRestoredBrowserPersistableActionQuery(query: Query, token?: object): void;
 export declare function revokeBrowserPersistableActionQuery(query: Query): void;
+/** The persisted-cache binding to capture when a fetch starts, for `recordActionQueryBrowserPersist`. */
+export declare function currentActionQueryCacheBinding(): object | undefined;
+/**
+ * Lets an `["action", ...]` query filled by a hand-written `queryFn` or
+ * `setQueryData` join the browser's persisted query cache the way a
+ * `useActionQuery` result does: only when its response carried the persist
+ * header, and only into the binding that was active when the fetch began, so a
+ * result fetched for one user is never written into another user's record.
+ */
+export declare function recordActionQueryBrowserPersist(query: Query, response: Response | undefined, bindingTokenAtFetch: object | undefined): void;
 export declare function useActionQuery<TResult = undefined, TName extends ActionName = ActionName>(actionName: TName, params?: ActionParams<TName>, options?: Omit<UseQueryOptions<TResult extends undefined ? ActionResult<TName> : TResult>, "queryKey" | "queryFn"> & {
     queryKeyScope?: readonly unknown[];
     /**

package/dist/client/use-action.js

@@ -3,6 +3,7 @@ import { useContext } from "react";
 import { ACTION_BATCH_ACTION_NAME } from "../shared/action-batch.js";
 import { ACTION_BROWSER_PERSIST_ALLOW, ACTION_BROWSER_PERSIST_HEADER, } from "../shared/action-browser-persist.js";
 import { ACTION_CHANGE_MARKER_FAILED, ACTION_CHANGE_MARKER_HEADER, } from "../shared/action-change-marker-header.js";
+import { UI_CAPABILITY_REQUIRED_ERROR_CODE } from "../shared/action-error-codes.js";
 import { SLOW_ACTION_RESPONSE_MS } from "../shared/analytics-events.js";
 import { ANALYTICS_CLIENT_PLATFORM_HEADER } from "../shared/analytics-platform.js";
 import { actionCircuitRemainingMs, actionErrorCode, actionErrorRetryAfterMs, actionErrorStatus, assertActionCircuitClosed, endsActionPolling, isActionCircuitOpenError, isTerminalActionError, recordActionFailure, resetActionFailureCircuit, resetActionFailureCircuits, } from "./action-failure-circuit.js";
@@ -19,6 +20,7 @@ import { clientBuildId, clientCompatibilityVersion, reloadForClientCompatibility
 import { ensureEmbedAuthFetchInterceptor, isEmbedAuthActive, } from "./embed-auth.js";
 import { recordActionStart } from "./recorder.js";
 import { currentRouteTemplate } from "./route-template.js";
+import { currentSessionIdentity } from "./session-identity.js";
 import { recheckSessionAfterUnauthorized } from "./use-session.js";
 function actionPrefix() {
     return agentNativePath("/_agent-native/actions");
@@ -119,20 +121,54 @@ function appendActionQueryParam(qs, key, value) {
     }
     qs.append(key, String(value));
 }
+// The server's capability lives 10 minutes; re-mint a minute early so a call
+// never leaves with a capability that expires in flight.
+const UI_CAPABILITY_REUSE_MS = 9 * 60_000;
+// Every signed-in write waits on the shared mint, so a mint that never answers
+// must settle on its own instead of holding writes until their own timeouts.
+const UI_CAPABILITY_MINT_TIMEOUT_MS = 10_000;
 let uiCapabilityRequest;
+let uiCapability = null;
+function hasFreshUiCapability() {
+    return (uiCapability !== null &&
+        uiCapability.identity === currentSessionIdentity() &&
+        Date.now() - uiCapability.at < UI_CAPABILITY_REUSE_MS);
+}
+/** Drop the remembered capability so the next call that needs one mints it. */
+export function forgetUiActionCapability() {
+    uiCapability = null;
+}
 // The mint is shared by concurrent callers, so one caller's abort rejects only
 // its own wait and never cancels the request the others are waiting on.
 function ensureUiActionCapability(signal) {
-    const request = uiCapabilityRequest ??
-        (uiCapabilityRequest = fetch(agentNativePath("/_agent-native/ui-capability"), { credentials: "same-origin", cache: "no-store" })
-            .then((response) => {
-            if (!response.ok) {
+    if (hasFreshUiCapability())
+        return Promise.resolve();
+    const identity = currentSessionIdentity();
+    const request = uiCapabilityRequest ?? (uiCapabilityRequest = mint());
+    function mint() {
+        const controller = typeof AbortController === "undefined" ? null : new AbortController();
+        let timer;
+        const timedOut = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                controller?.abort();
+                reject(new Error("Timed out establishing the browser UI capability."));
+            }, UI_CAPABILITY_MINT_TIMEOUT_MS);
+        });
+        const response = fetch(agentNativePath("/_agent-native/ui-capability"), {
+            credentials: "same-origin",
+            cache: "no-store",
+            signal: controller?.signal,
+        }).then((res) => {
+            if (!res.ok) {
                 throw new Error("Could not establish the browser UI capability.");
             }
-        })
-            .finally(() => {
+            uiCapability = { identity, at: Date.now() };
+        });
+        return Promise.race([response, timedOut]).finally(() => {
+            clearTimeout(timer);
             uiCapabilityRequest = undefined;
-        }));
+        });
+    }
     if (!signal)
         return request;
     return new Promise((resolve, reject) => {
@@ -145,6 +181,45 @@ function ensureUiActionCapability(signal) {
             .finally(() => signal.removeEventListener("abort", onAbort));
     });
 }
+/**
+ * Every write from the signed-in app carries the UI capability, so an action
+ * that needs approval runs on its first request instead of failing once and
+ * retrying. The mint waits for a known signed-in session: a public page or an
+ * embed has none to mint from, and its writes go out as they are. A failed
+ * mint never holds a write back; the server decides what the write may do.
+ * A keepalive write never waits on a mint: it is sent as the page goes away,
+ * and a deferred send can be lost with it.
+ */
+function presentUiCapability(method, options, signal) {
+    const identity = currentSessionIdentity();
+    let pending;
+    if (options?.uiOnly) {
+        pending = ensureUiActionCapability(signal);
+    }
+    else if (method === "GET" ||
+        options?.keepalive ||
+        typeof window === "undefined" ||
+        isEmbedAuthActive() ||
+        typeof identity !== "string") {
+        return undefined;
+    }
+    else {
+        pending = ensureUiActionCapability(signal).catch((error) => {
+            if (signal?.aborted)
+                throw error;
+        });
+    }
+    if (typeof identity !== "string")
+        return pending;
+    // The write leaves only after the mint, and the browser sends whichever
+    // session's cookies it holds by then: a user who changed in between must not
+    // receive the first user's write.
+    return pending.then(() => {
+        if (currentSessionIdentity() !== identity) {
+            throw new Error("The signed-in user changed before this write was sent.");
+        }
+    });
+}
 export const ACTION_KEEPALIVE_BODY_BUDGET_BYTES = 48_000;
 let reservedKeepaliveBodyBytes = 0;
 function utf8ByteLength(value) {
@@ -271,9 +346,8 @@ async function performActionFetch(name, method, params, options) {
                     batchUrl: `${actionPrefix()}/${ACTION_BATCH_ACTION_NAME}`,
                 })
                 : fetch(url, init);
-            const request = options?.uiOnly
-                ? ensureUiActionCapability(controller?.signal).then(send)
-                : send();
+            const capability = presentUiCapability(method, options, controller?.signal);
+            const request = capability ? capability.then(send) : send();
             res = await Promise.race([request, timedOutSignal]);
             throwIfAborted(outerSignal);
             options?.onResponse?.(res);
@@ -340,9 +414,10 @@ async function performActionFetch(name, method, params, options) {
     }
     if (!res.ok) {
         if (res.status === 403 &&
-            data?.errorCode === "ui_capability_required" &&
+            data?.errorCode === UI_CAPABILITY_REQUIRED_ERROR_CODE &&
             !options?.uiCapabilityRetry &&
             typeof window !== "undefined") {
+            forgetUiActionCapability();
             return performActionFetch(name, method, params, {
                 ...options,
                 uiOnly: true,
@@ -616,6 +691,7 @@ export function callAction(actionName, params, options = {}) {
         includeRequestSource: false,
         headers: options.headers,
         uiOnly: options.uiOnly,
+        onResponse: options.onResponse,
     });
 }
 export function callActionBlob(actionName, params, options = {}) {
@@ -626,6 +702,7 @@ export function callActionBlob(actionName, params, options = {}) {
         headers: options.headers,
         responseType: "blob",
         uiOnly: options.uiOnly,
+        onResponse: options.onResponse,
     });
 }
 function isAbortError(error) {
@@ -854,6 +931,32 @@ export function revokeBrowserPersistableActionQuery(query) {
     browserPersistableActionQueries.delete(query);
     browserPersistableActionQueryBindings.delete(query);
 }
+/** The persisted-cache binding to capture when a fetch starts, for `recordActionQueryBrowserPersist`. */
+export function currentActionQueryCacheBinding() {
+    return actionQueryCacheBindingToken;
+}
+/**
+ * Lets an `["action", ...]` query filled by a hand-written `queryFn` or
+ * `setQueryData` join the browser's persisted query cache the way a
+ * `useActionQuery` result does: only when its response carried the persist
+ * header, and only into the binding that was active when the fetch began, so a
+ * result fetched for one user is never written into another user's record.
+ */
+export function recordActionQueryBrowserPersist(query, response, bindingTokenAtFetch) {
+    if (response?.headers.get(ACTION_BROWSER_PERSIST_HEADER) !==
+        ACTION_BROWSER_PERSIST_ALLOW) {
+        revokeBrowserPersistableActionQuery(query);
+        return;
+    }
+    browserPersistableActionQueries.add(query);
+    if (bindingTokenAtFetch !== undefined &&
+        actionQueryCacheBindingToken === bindingTokenAtFetch) {
+        browserPersistableActionQueryBindings.set(query, bindingTokenAtFetch);
+    }
+    else {
+        browserPersistableActionQueryBindings.delete(query);
+    }
+}
 const UNBATCHED_REFETCHES_META_KEY = "actionUnbatchedRefetches";
 /**
  * A first fetch is what the page is waiting on, so it goes alone. On
@@ -887,16 +990,14 @@ export function useActionQuery(actionName, params, options) {
             const query = client.getQueryCache().find({ queryKey, exact: true });
             const bindingTokenAtFetch = actionQueryCacheBindingToken;
             assertActionCircuitClosed(key);
-            let browserPersist = false;
+            let lastResponse;
             let result;
             try {
                 result = await actionFetch(actionName, "GET", params, {
                     signal,
                     batch: canBatchActionQueryFetch(query),
                     onResponse: (response) => {
-                        browserPersist =
-                            response.headers.get(ACTION_BROWSER_PERSIST_HEADER) ===
-                                ACTION_BROWSER_PERSIST_ALLOW;
+                        lastResponse = response;
                     },
                 });
             }
@@ -916,19 +1017,7 @@ export function useActionQuery(actionName, params, options) {
             resetActionFailureCircuit(key);
             if (query && !signal.aborted) {
                 clearAccessDeniedActionQueryBinding(query);
-                if (browserPersist) {
-                    browserPersistableActionQueries.add(query);
-                    if (bindingTokenAtFetch !== undefined &&
-                        actionQueryCacheBindingToken === bindingTokenAtFetch) {
-                        browserPersistableActionQueryBindings.set(query, bindingTokenAtFetch);
-                    }
-                    else {
-                        browserPersistableActionQueryBindings.delete(query);
-                    }
-                }
-                else {
-                    revokeBrowserPersistableActionQuery(query);
-                }
+                recordActionQueryBrowserPersist(query, lastResponse, bindingTokenAtFetch);
             }
             return result;
         },

package/dist/client/use-session.js

@@ -4,6 +4,7 @@ import { setSentryUser, trackEvent, trackSessionStatus } from "./analytics.js";
 import { agentNativeApiDisabledReason } from "./api-surface.js";
 import { expireClientStatusResult, fetchAuthSessionStatus, invalidateClientStatusRequest, SESSION_RESULT_LIFETIME_MS, } from "./client-status-requests.js";
 import { getFrameOrigin, getFramePostMessageTargetOrigin } from "./frame.js";
+import { recordSessionIdentity } from "./session-identity.js";
 export { hasSessionHint, isSessionNavigationPending, } from "../shared/ssr-session-bootstrap.js";
 /**
  * True while the app tree is mounted hidden ahead of the session read (a hinted
@@ -105,6 +106,7 @@ function hasFreshSessionCache() {
 function publishSessionIdentity(session) {
     const identity = session?.userId ?? session?.email ?? null;
     const authUserId = session?.authUserId;
+    recordSessionIdentity(identity);
     if (trackedSessionIdentity !== identity ||
         trackedSessionAuthUserId !== authUserId) {
         trackedSessionIdentity = identity;

package/dist/collab/awareness.d.ts

@@ -38,19 +38,19 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
-    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
+    error?: undefined;
 }>>;
 export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
     users?: undefined;
 } | {
-    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
+    error?: undefined;
 }>>;

package/dist/collab/routes.d.ts

@@ -13,8 +13,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
     };
 }>>;
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/collab/struct-routes.d.ts

@@ -1,6 +1,6 @@
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;