@agent-native/core 0.200.0-nightly-20261002124406 → 0.200.0

package/dist/agent/production-agent.d.ts

@@ -10,6 +10,7 @@ import { type BuilderGatewayAuth } from "../server/credential-provider.js";
 import { fireInternalDispatch } from "../server/self-dispatch.js";
 import { type RefusedTurnRetryContext } from "../shared/agent-chat-run-not-started.js";
 import { type ReasoningEffort } from "../shared/reasoning-effort.js";
+import type { TrackingMeta } from "../tracking/registry.js";
 import { type ResolveEngineConfig } from "./engine/index.js";
 import { PROVIDER_TO_ENV } from "./engine/provider-env-vars.js";
 import type { AgentEngine, EngineTool, EngineMessage, EngineContentPart } from "./engine/types.js";
@@ -232,6 +233,9 @@ export declare function filterActionsByAllowedNames(actions: Record<string, Acti
 export declare const PLAN_MODE_SYSTEM_PROMPT = "## Plan Mode Active\n\nYou are in Plan mode. This turn is for research, clarification, and a proposed approach only.\n\nHard rules:\n- Use only read-only tools. Do not edit files, write resources, run mutating bash commands, mutate SQL rows, navigate the UI, send notifications, create jobs, create tools, send messages or tasks to external agents, or change external systems.\n- If a needed detail is unclear, ask a concise clarifying question before proposing a plan.\n- When ready, present a concrete plan with the files/tools you expect to touch, the intended changes, validation steps, and notable risks.\n- Do not treat approval as implicit while Plan mode is still active. Tell the user to switch to Act mode with the mode selector or /act before implementation.";
 export declare function isPlanModeToolCallAllowed(name: string, input: unknown, entry: ActionEntry): boolean;
 export declare function createPlanModeActionRegistry(actions: Record<string, ActionEntry>): Record<string, ActionEntry>;
+type AgentRunTrackingSource = Pick<TrackingMeta, "userId" | "authUserId" | "anonymousId" | "sessionId"> & {
+    isSyntheticTraffic?: boolean;
+};
 export interface ProductionAgentOptions {
     actions?: Record<string, ActionEntry>;
     /** @deprecated Use `actions` instead */
@@ -252,7 +256,7 @@ export interface ProductionAgentOptions {
     hostedHarnessConfig?: AgentNativeHarnessSetting;
     reasoningEffort?: ReasoningEffort;
     providerOptions?: EngineMessage extends never ? never : any;
-    onRunComplete?: (run: ActiveRun, threadId: string | undefined) => void;
+    onRunComplete?: (run: ActiveRun, threadId: string | undefined, trackingSource?: AgentRunTrackingSource) => void;
     onRunPrepared?: (details: {
         runId: string;
         turnId: string;

package/dist/agent/production-agent.js

@@ -958,6 +958,35 @@ export async function resolveAgentOwnerEmail(options, event) {
     }
     return ownerEmail ?? getRequestUserEmail() ?? null;
 }
+function snapshotAgentRunTrackingSource() {
+    const requestContext = getRequestContext();
+    if (!requestContext)
+        return undefined;
+    const source = requestContext.agentRunAnonymous
+        ? {
+            ...(requestContext.userEmail
+                ? { anonymousId: requestContext.userEmail }
+                : {}),
+            ...(requestContext.browserSessionId
+                ? { sessionId: requestContext.browserSessionId }
+                : {}),
+        }
+        : {
+            ...(requestContext.userEmail
+                ? { userId: requestContext.userEmail }
+                : {}),
+            ...(requestContext.authUserId
+                ? { authUserId: requestContext.authUserId }
+                : {}),
+            ...(requestContext.browserSessionId
+                ? { sessionId: requestContext.browserSessionId }
+                : {}),
+        };
+    const isSyntheticTraffic = requestContext.isSyntheticTraffic === true;
+    return Object.keys(source).length > 0 || isSyntheticTraffic
+        ? { ...source, ...(isSyntheticTraffic ? { isSyntheticTraffic: true } : {}) }
+        : undefined;
+}
 const MAX_RETRIES = 3;
 const COMPLETION_DATABASE_RETRY_DELAYS_MS = [250, 750, 1_500];
 export async function runCompletionCallbackWithDatabaseRetry(callback, options) {
@@ -6336,6 +6365,9 @@ export function createProductionAgentHandler(options) {
     };
     const getEngineTools = (actions) => actionsToEngineTools(getRequestActions(actions));
     return defineEventHandler(async (event) => {
+        let completionTrackingSource = options.onRunComplete
+            ? snapshotAgentRunTrackingSource()
+            : undefined;
         const setupT0 = Date.now();
         const setupMarks = {};
         const setupMark = (k) => {
@@ -7634,12 +7666,15 @@ export function createProductionAgentHandler(options) {
         const baseHandleRunComplete = options.onRunComplete || trackedProgressRunId
             ? async (run) => {
                 try {
-                    await runCompletionCallbackWithDatabaseRetry(() => options.onRunComplete?.(run, threadId));
+                    await runCompletionCallbackWithDatabaseRetry(() => options.onRunComplete?.(run, threadId, completionTrackingSource));
                 }
                 catch (err) {
                     await completeTrackedProgressRun(run, err);
                     throw err;
                 }
+                finally {
+                    completionTrackingSource = undefined;
+                }
                 await completeTrackedProgressRun(run);
             }
             : undefined;

package/dist/app-config/runtime.d.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 export declare const runtimeConfig: z.ZodObject<{
     backgroundJobsEnabled: z.ZodOptional<z.ZodBoolean>;
     databasePoolMax: z.ZodOptional<z.ZodNumber>;
+    searchDrainBudgetMs: z.ZodDefault<z.ZodNumber>;
     agentChatStreaming: z.ZodDefault<z.ZodBoolean>;
     vercelBranchUrl: z.ZodOptional<z.ZodString>;
     databaseUrlUnpooled: z.ZodOptional<z.ZodString>;

package/dist/app-config/runtime.js

@@ -8,6 +8,10 @@ export const runtimeConfig = z.object({
         env: "AGENT_NATIVE_DB_POOL_MAX",
         doc: "Maximum connections per database pool. Serverless runtimes always use one connection; local runtimes default to twenty.",
     }),
+    searchDrainBudgetMs: z.number().int().min(0).default(100).meta({
+        env: "AGENT_NATIVE_SEARCH_DRAIN_BUDGET_MS",
+        doc: "Milliseconds a search spends processing pending search index changes before answering; if changes remain, that search uses the app's fallback. Zero processes none, leaving them to the drains that follow writes and the recurring sweep.",
+    }),
     agentChatStreaming: z.boolean().default(false).meta({
         env: "AGENT_NATIVE_AGENT_CHAT_STREAM_RUNTIME",
         doc: "Run the dedicated Nitro agent-chat response-streaming route used by an AWS Lambda Function URL.",

package/dist/app-config/schema.d.ts

@@ -131,6 +131,7 @@ export declare const appConfigSchema: z.ZodObject<{
     runtime: z.ZodPrefault<z.ZodObject<{
         backgroundJobsEnabled: z.ZodOptional<z.ZodBoolean>;
         databasePoolMax: z.ZodOptional<z.ZodNumber>;
+        searchDrainBudgetMs: z.ZodDefault<z.ZodNumber>;
         agentChatStreaming: z.ZodDefault<z.ZodBoolean>;
         vercelBranchUrl: z.ZodOptional<z.ZodString>;
         databaseUrlUnpooled: z.ZodOptional<z.ZodString>;

package/dist/cli/design-connect.d.ts

@@ -51,6 +51,7 @@ export interface DesignConnectManifest {
 }
 export interface DesignConnectBridge {
     server: Server;
+    close: () => Promise<void>;
     manifest: DesignConnectManifest;
     /** Per-rootPath bridge token. Kept in-process only; never serialised into
      *  the manifest JSON so it is not exposed over the network via GET /manifest.

package/dist/cli/design-connect.js

@@ -5,6 +5,7 @@ import fs from "node:fs/promises";
 import http from "node:http";
 import https from "node:https";
 import path from "node:path";
+import { WebSocket, WebSocketServer } from "ws";
 import { injectDocumentMarkup } from "../shared/html-document.js";
 const DEFAULT_BRIDGE_PORT = 7331;
 const ROUTE_MANIFEST_FILE = path.join(".agent-native", "design-routes.json");
@@ -1200,6 +1201,53 @@ function addPreviewTokenToResourceUrl(resourceUrl, previewToken) {
     const withoutStaleToken = stripQueryPair(search, "previewToken");
     return `${pathname}${appendQueryPair(withoutStaleToken, "previewToken", previewToken)}${hash}`;
 }
+const MAX_PREVIEW_HMR_MESSAGE_BYTES = 1024 * 1024;
+function rewriteViteHmrUpdate(payload, previewToken) {
+    if (payload.length > MAX_PREVIEW_HMR_MESSAGE_BYTES)
+        return undefined;
+    let message;
+    try {
+        message = JSON.parse(payload.toString("utf8"));
+    }
+    catch {
+        // coercion-ok: non-JSON Vite control frames are relayed unchanged.
+        return undefined;
+    }
+    if (!message ||
+        typeof message !== "object" ||
+        !("type" in message) ||
+        message.type !== "update" ||
+        !("updates" in message) ||
+        !Array.isArray(message.updates)) {
+        return undefined;
+    }
+    let changed = false;
+    for (const candidate of message.updates) {
+        if (!candidate ||
+            typeof candidate !== "object" ||
+            !("type" in candidate) ||
+            candidate.type !== "js-update" ||
+            !("acceptedPath" in candidate) ||
+            typeof candidate.acceptedPath !== "string" ||
+            !("timestamp" in candidate) ||
+            typeof candidate.timestamp !== "number" ||
+            !Number.isSafeInteger(candidate.timestamp)) {
+            continue;
+        }
+        // Vite compares path and acceptedPath as module identities before it imports
+        // the update, so carry proxy auth in its cache-busting query instead.
+        candidate.timestamp = `${candidate.timestamp}&previewToken=${encodeURIComponent(previewToken)}`;
+        changed = true;
+    }
+    return changed ? Buffer.from(JSON.stringify(message)) : undefined;
+}
+function webSocketDataBuffer(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (Array.isArray(data))
+        return Buffer.concat(data);
+    return Buffer.from(data);
+}
 function addOpaqueFrameCredentials(html, previewToken) {
     const withCredentialedResources = html.replace(/<(script|link|img|audio|video|source|track|iframe)\b([^>]*?)>/gi, (fullTag, tagName, attributes) => {
         const resourceMatch = attributes.match(/\b(src|href)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i);
@@ -1243,9 +1291,12 @@ function addOpaqueFrameCredentials(html, previewToken) {
         },
     });
     const withImportMap = injectDocumentMarkup(withHmrToken, `<script type="importmap" data-agent-native-opaque-preview-imports>${previewImportMap}</script>`, { target: "head" });
-    return injectDocumentMarkup(withImportMap, 
+    const withViteHmrStyleAuth = injectDocumentMarkup(withImportMap, 
+    // coercion-ok: malformed Vite-generated CSS URLs stay unchanged in the frame.
+    `<script data-agent-native-vite-css-auth>(function(t){var p=Element.prototype.after;Element.prototype.after=function(){for(var i=0;i<arguments.length;i++){var n=arguments[i];if(!n||n.nodeType!==1||n.tagName!=="LINK")continue;try{var b=new URL(document.baseURI),u=new URL(n.getAttribute("href"),b);if(u.origin===b.origin&&!u.searchParams.has("previewToken")){u.searchParams.set("previewToken",t);n.setAttribute("href",u.toString())}}catch(_){}}return p.apply(this,arguments)}})(${previewTokenLiteral});</script>`, { target: "head" });
+    return injectDocumentMarkup(withViteHmrStyleAuth, 
     // coercion-ok: invalid browser-owned URLs stay unchanged in the frame.
-    String.raw `<script data-agent-native-opaque-preview-auth>(function(){var t=${previewTokenLiteral},o,h;try{var b=new URL(document.baseURI);o=b.origin;h=b.host}catch(_){return}function u(v){try{var a=new URL(String(v),document.baseURI),same=a.origin===o||(h===a.host&&(a.protocol==="ws:"||a.protocol==="wss:"));if(!same||a.searchParams.has("previewToken"))return null;a.searchParams.set("previewToken",t);return a.toString()}catch(_){return null}}function c(v){return String(v).replace(/url\(\s*(["']?)([^"'()]+)\1\s*\)/gi,function(h,q,v){var s=u(v);return s?"url("+q+s+q+")":h})}var f=window.fetch.bind(window);window.fetch=function(i,n){var v=i instanceof Request?i.url:i,s=u(v);return s?f(i instanceof Request?new Request(s,i):s,n):f(i,n)};var x=XMLHttpRequest.prototype.open;XMLHttpRequest.prototype.open=function(m,v){var s=u(v);return x.call(this,m,s||v,...Array.prototype.slice.call(arguments,2))};var e=window.EventSource;if(e){var E=function(v,n){return new e(u(v)||v,n);};E.prototype=e.prototype;window.EventSource=E}var W=window.WebSocket;if(W){var S=function(v,p){var s=u(v);return p===undefined?new W(s||v):new W(s||v,p)};S.prototype=W.prototype;S.CONNECTING=W.CONNECTING;S.OPEN=W.OPEN;S.CLOSING=W.CLOSING;S.CLOSED=W.CLOSED;window.WebSocket=S}var p=Node.prototype.appendChild;Node.prototype.appendChild=function(n){if(n&&n.nodeType===1){var a=n.tagName==="SCRIPT"?"src":n.tagName==="LINK"?"href":n.tagName==="IMG"?"src":n.tagName==="IFRAME"?"src":null;if(a){var v=n.getAttribute(a),s=u(v);if(s)n.setAttribute(a,s)}else if(n.tagName==="STYLE"&&n.textContent){n.textContent=c(n.textContent)}}return p.call(this,n)}})();</script>`, { target: "head" });
+    String.raw `<script data-agent-native-opaque-preview-auth>(function(){var t=${previewTokenLiteral},o,h;try{var b=new URL(document.baseURI);o=b.origin;h=b.host}catch(_){return}function u(v){try{var a=new URL(String(v),document.baseURI),same=a.origin===o||(h===a.host&&(a.protocol==="ws:"||a.protocol==="wss:"));if(!same||a.searchParams.has("previewToken"))return null;a.searchParams.set("previewToken",t);return a.toString()}catch(_){return null}}function c(v){return String(v).replace(/url\(\s*(["']?)([^"'()]+)\1\s*\)/gi,function(h,q,v){var s=u(v);return s?"url("+q+s+q+")":h})}var f=window.fetch.bind(window);window.fetch=function(i,n){var v=i instanceof Request?i.url:i,s=u(v);return s?f(i instanceof Request?new Request(s,i):s,n):f(i,n)};var x=XMLHttpRequest.prototype.open;XMLHttpRequest.prototype.open=function(m,v){var s=u(v);return x.call(this,m,s||v,...Array.prototype.slice.call(arguments,2))};var e=window.EventSource;if(e){var E=function(v,n){return new e(u(v)||v,n);};E.prototype=e.prototype;window.EventSource=E}var W=window.WebSocket;if(W){var S=function(v,p){var s=u(v);return p===undefined?new W(s||v):new W(s||v,p)};S.prototype=W.prototype;S.CONNECTING=W.CONNECTING;S.OPEN=W.OPEN;S.CLOSING=W.CLOSING;S.CLOSED=W.CLOSED;window.WebSocket=S}function d(n){if(n&&n.nodeType===1){var a=n.tagName==="SCRIPT"?"src":n.tagName==="LINK"?"href":n.tagName==="IMG"?"src":n.tagName==="IFRAME"?"src":null;if(a){var v=n.getAttribute(a),s=u(v);if(s)n.setAttribute(a,s)}else if(n.tagName==="STYLE"&&n.textContent){n.textContent=c(n.textContent)}}return n}var p=Node.prototype.appendChild;Node.prototype.appendChild=function(n){return p.call(this,d(n))};var i=Node.prototype.insertBefore;Node.prototype.insertBefore=function(n,r){return i.call(this,d(n),r)}})();</script>`, { target: "head" });
 }
 function addOpaqueFrameResourceTokens(css, previewToken) {
     const withImportTokens = css.replace(/(@import\s+)(["'])([^"']+)\2/gi, (_full, prefix, quote, resourceUrl) => `${prefix}${quote}${addPreviewTokenToResourceUrl(resourceUrl, previewToken)}${quote}`);
@@ -2107,6 +2158,11 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
     const isValidLiveEditRegistrationCapability = (req, designId) => constantTimeTokenMatches(readHeader(req, "x-agent-native-live-edit-registration-capability"), deriveDesignScopedLiveEditRegistrationCapability(bridgeToken, designId));
     const bridgeInstanceId = crypto.randomBytes(16).toString("hex");
     const previewSessionCookies = new PreviewSessionCookieJar(manifest.devServerUrl);
+    const hmrWebSocketServer = new WebSocketServer({
+        noServer: true,
+        perMessageDeflate: false,
+        handleProtocols: (protocols) => protocols.has("vite-hmr") ? "vite-hmr" : false,
+    });
     const server = http.createServer((req, res) => {
         const requestUrl = new URL(req.url ?? "/", manifest.bridgeUrl);
         const pathname = requestUrl.pathname;
@@ -2326,6 +2382,7 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
                 sendJson(res, 200, {
                     ok: true,
                     pending: pendingVisualEditPayloads.get(designId)?.pending ?? null,
+                    revision: pendingVisualEditRevisionHighWaterMarks.get(designId) ?? 0,
                 });
                 return;
             }
@@ -2406,7 +2463,7 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
                                     : stored === "stale"
                                         ? "stale pending publication revision"
                                         : "conflicting pending publication revision",
-                                revision: existing?.revision,
+                                revision: pendingVisualEditRevisionHighWaterMarks.get(pendingDesignId) ?? 0,
                             });
                             return;
                         }
@@ -2472,7 +2529,7 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
                                 : stored === "stale"
                                     ? "stale pending publication revision"
                                     : "conflicting pending publication revision",
-                            revision: existing?.revision,
+                            revision: pendingVisualEditRevisionHighWaterMarks.get(candidate.designId) ?? 0,
                         });
                         return;
                     }
@@ -2889,6 +2946,16 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
         }
         sendJson(res, 404, { ok: false, error: "not found" });
     });
+    const terminateHmrClients = () => {
+        for (const client of hmrWebSocketServer.clients)
+            client.terminate();
+    };
+    // noServer upgrades are not closed by http.Server.close().
+    const closeHttpServer = server.close.bind(server);
+    server.close = (callback) => {
+        terminateHmrClients();
+        return closeHttpServer(callback);
+    };
     // Vite's proxied /@vite/client derives its HMR socket from the document's
     // bridge origin. Tunnel WebSocket upgrades to the one connected dev-server
     // origin so Fast Refresh remains live inside URL-backed screens. The target
@@ -2903,6 +2970,9 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
             "";
         const browserOrigin = readHeader(req, "origin");
         const sameBridgeOrigin = browserOrigin === new URL(manifest.bridgeUrl).origin;
+        const isViteHmrSocket = readHeader(req, "sec-websocket-protocol")
+            .split(",")
+            .some((protocol) => protocol.trim() === "vite-hmr");
         if (!constantTimeTokenMatches(providedPreviewToken, previewToken)) {
             clientSocket.end("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
             return;
@@ -2921,11 +2991,60 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
         delete upstreamHeaders["x-agent-native-live-edit-capability"];
         delete upstreamHeaders["authorization"];
         delete upstreamHeaders["cookie"];
+        if (isViteHmrSocket) {
+            delete upstreamHeaders["connection"];
+            delete upstreamHeaders["upgrade"];
+            delete upstreamHeaders["sec-websocket-key"];
+            delete upstreamHeaders["sec-websocket-version"];
+            delete upstreamHeaders["sec-websocket-protocol"];
+            delete upstreamHeaders["sec-websocket-extensions"];
+        }
         upstreamHeaders.host = targetUrl.host;
         upstreamHeaders.origin = new URL(manifest.devServerUrl).origin;
         const cookie = mergePreviewCookieHeaders(previewSessionCookies.headerFor(targetUrl.toString()), sameBridgeOrigin ? readHeader(req, "cookie") : "");
         if (cookie)
             upstreamHeaders.cookie = cookie;
+        if (isViteHmrSocket) {
+            const hmrUrl = new URL(targetUrl);
+            hmrUrl.protocol = targetUrl.protocol === "https:" ? "wss:" : "ws:";
+            hmrWebSocketServer.handleUpgrade(req, clientSocket, clientHead, (browserSocket) => {
+                const upstreamSocket = new WebSocket(hmrUrl, "vite-hmr", {
+                    headers: upstreamHeaders,
+                    perMessageDeflate: false,
+                });
+                const queuedMessages = [];
+                browserSocket.on("message", (data, isBinary) => {
+                    if (upstreamSocket.readyState === WebSocket.OPEN) {
+                        upstreamSocket.send(data, { binary: isBinary });
+                    }
+                    else if (upstreamSocket.readyState === WebSocket.CONNECTING) {
+                        queuedMessages.push({ data, isBinary });
+                    }
+                });
+                upstreamSocket.once("open", () => {
+                    for (const message of queuedMessages) {
+                        upstreamSocket.send(message.data, { binary: message.isBinary });
+                    }
+                    queuedMessages.length = 0;
+                });
+                upstreamSocket.on("message", (data, isBinary) => {
+                    const payload = webSocketDataBuffer(data);
+                    const rewritten = isBinary
+                        ? undefined
+                        : rewriteViteHmrUpdate(payload, previewToken);
+                    browserSocket.send(rewritten ?? payload, { binary: isBinary });
+                });
+                browserSocket.once("close", () => upstreamSocket.terminate());
+                upstreamSocket.once("close", () => browserSocket.close());
+                upstreamSocket.on("error", () => {
+                    if (browserSocket.readyState === WebSocket.OPEN) {
+                        browserSocket.close(1011, "Dev server HMR connection failed");
+                    }
+                });
+                browserSocket.on("error", () => upstreamSocket.terminate());
+            });
+            return;
+        }
         const requestImpl = targetUrl.protocol === "https:" ? https : http;
         let upgraded = false;
         const upstreamRequest = requestImpl.request({
@@ -2972,6 +3091,17 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
         });
         upstreamRequest.end();
     });
+    let closePromise;
+    const close = () => {
+        closePromise ??= (async () => {
+            terminateHmrClients();
+            await new Promise((resolve) => hmrWebSocketServer.close(resolve));
+            await new Promise((resolve, reject) => {
+                server.close((error) => (error ? reject(error) : resolve()));
+            });
+        })();
+        return closePromise;
+    };
     await new Promise((resolve, reject) => {
         server.once("error", reject);
         server.listen(new URL(manifest.bridgeUrl).port, "127.0.0.1", () => {
@@ -2984,11 +3114,18 @@ export async function startDesignConnectBridge(manifest, seedOrOptions) {
             await persistBridgeToken(manifest.rootPath, bridgeToken);
         }
         catch (error) {
-            await new Promise((resolve) => server.close(() => resolve()));
+            await close();
             throw error;
         }
     }
-    return { server, manifest, bridgeToken, previewToken, bridgeInstanceId };
+    return {
+        close,
+        server,
+        manifest,
+        bridgeToken,
+        previewToken,
+        bridgeInstanceId,
+    };
 }
 export function resolveAppUrl(explicit) {
     const raw = explicit ||
@@ -3338,7 +3475,10 @@ export async function runDesign(argv) {
     }
     return await new Promise((resolve) => {
         const stop = () => {
-            bridge.server.close(() => resolve(0));
+            void bridge.close().then(() => resolve(0), (error) => {
+                console.error("[design connect] bridge shutdown failed", error);
+                resolve(1);
+            });
         };
         for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
             process.once(signal, stop);

package/dist/client/analytics.js

@@ -1739,7 +1739,27 @@ function emitBrowserTrackingEvent(name, props, options = {}) {
     const authUserId = getTrackingAuthUserId();
     sendAgentNativeAnalytics(name, authUserId ? { ...props, auth_user_id: authUserId } : props);
 }
+// Browser events that are telemetry or already have their own replay marker.
+const REPLAY_UNMARKED_EVENT_NAMES = new Set([
+    "pageview",
+    "session status",
+    "session_status",
+    "action.response",
+    "agent_chat_lifecycle",
+    "session_replay_started",
+    "session replay upload rejected",
+    "session_replay_upload_rejected",
+    AGENT_NATIVE_EXCEPTION_EVENT_NAME,
+]);
+function markTrackedEventInSessionReplay(name) {
+    if (REPLAY_UNMARKED_EVENT_NAMES.has(name))
+        return;
+    _sessionReplayModuleForCapture?.emitSessionReplayAnalyticsEvent?.(name);
+}
 export function trackEvent(name, params) {
+    trackBrowserEvent(name, params, true);
+}
+function trackBrowserEvent(name, params, markInReplay) {
     if (typeof window === "undefined")
         return;
     if (isSyntheticBrowserTraffic())
@@ -1758,10 +1778,13 @@ export function trackEvent(name, params) {
             sendGtag: !gtagNameMatchesCanonical,
         });
     }
+    if (markInReplay)
+        markTrackedEventInSessionReplay(canonical?.name ?? name);
     void recordTrackingEvent(name, props, "client");
     const lifecycle = legacyLifecycleEvent(name, props);
+    // The alias describes the same moment, so it gets no second replay marker.
     if (lifecycle)
-        trackEvent(lifecycle.name, lifecycle.properties);
+        trackBrowserEvent(lifecycle.name, lifecycle.properties, false);
 }
 export function trackAnonymousEvent(name, properties) {
     if (typeof window === "undefined" ||

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

@@ -71,6 +71,7 @@ export interface SessionReplayStartResult {
 export declare const SESSION_REPLAY_CONSOLE_EVENT_TAG = "agent-native.console";
 export declare const SESSION_REPLAY_NETWORK_EVENT_TAG = "agent-native.network";
 export declare const SESSION_REPLAY_AGENT_CHAT_EVENT_TAG = "agent-native.chat";
+export declare const SESSION_REPLAY_ANALYTICS_EVENT_TAG = "agent-native.event";
 export declare function getSessionReplaySamplingScore(sessionId: string, salt?: string): number;
 export declare function shouldSampleSessionReplay(sessionId: string, sampleRate?: number, salt?: string): boolean;
 export declare function flushSessionReplay(reason?: string): Promise<void>;
@@ -88,6 +89,11 @@ export declare function emitSessionReplayException(input: {
     stack?: string;
     url?: string;
 }): void;
+/**
+ * Mark a tracked analytics event on the replay timeline. Only the event name
+ * is recorded; event properties stay out of the replay.
+ */
+export declare function emitSessionReplayAnalyticsEvent(name: string): void;
 export type SessionReplayAgentChatEvent = {
     phase: "surface-mounted" | "run-observed" | "run-stopped";
     surface: string | number;

package/dist/client/session-replay.js

@@ -70,10 +70,13 @@ const SESSION_REPLAY_CLAIM_TIMEOUT_MS = 150;
 export const SESSION_REPLAY_CONSOLE_EVENT_TAG = "agent-native.console";
 export const SESSION_REPLAY_NETWORK_EVENT_TAG = "agent-native.network";
 export const SESSION_REPLAY_AGENT_CHAT_EVENT_TAG = "agent-native.chat";
+export const SESSION_REPLAY_ANALYTICS_EVENT_TAG = "agent-native.event";
 const SESSION_REPLAY_LIFECYCLE_EVENT_TAG = "agent-native.session_replay";
 const DEFAULT_MAX_CONSOLE_EVENTS = 1000;
 const DEFAULT_MAX_NETWORK_EVENTS = 2000;
 const MAX_CONSOLE_MESSAGE_LENGTH = 500;
+const MAX_ANALYTICS_EVENT_NAME_LENGTH = 120;
+const MAX_ANALYTICS_EVENTS_PER_REPLAY = 1000;
 const MAX_CONSOLE_ARGS = 10;
 const MAX_CONSOLE_STACK_LENGTH = 2000;
 const MAX_CONSOLE_SERIALIZE_DEPTH = 4;
@@ -136,6 +139,8 @@ function getState() {
             removeLifecycleListeners: null,
             restoreIframeBridge: null,
             addCustomEvent: null,
+            analyticsEventCount: 0,
+            analyticsEventReplayId: null,
             takeFullSnapshot: null,
             restoreCaptures: null,
             options: null,
@@ -255,11 +260,7 @@ function removeStoredReplaySession(replayId) {
 function getOrCreateReplaySession(sessionId, linkBaseUrl) {
     clearLegacyLocalStorageReplaySession();
     const parsed = readStoredReplaySession();
-    const parsedSequence = typeof parsed?.sequence === "number" &&
-        Number.isFinite(parsed.sequence) &&
-        parsed.sequence >= 0
-        ? Math.floor(parsed.sequence)
-        : 0;
+    const parsedSequence = storedCount(parsed?.sequence);
     if (parsed?.sessionId === sessionId &&
         parsed.replayId &&
         parsedSequence < MAX_REPLAY_CHUNKS_PER_RECORDING - 1) {
@@ -278,6 +279,7 @@ function getOrCreateReplaySession(sessionId, linkBaseUrl) {
             startedAtMs,
             sequence,
             ...(resolvedLinkBaseUrl ? { linkBaseUrl: resolvedLinkBaseUrl } : {}),
+            analyticsEventCount: storedCount(parsed.analyticsEventCount),
             resumed: true,
         };
     }
@@ -295,9 +297,15 @@ function getOrCreateReplaySession(sessionId, linkBaseUrl) {
         startedAtMs,
         sequence: 0,
         ...(linkBaseUrl ? { linkBaseUrl } : {}),
+        analyticsEventCount: 0,
         resumed: false,
     };
 }
+function storedCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? Math.floor(value)
+        : 0;
+}
 function openReplayBroadcastChannel() {
     if (typeof BroadcastChannel === "undefined")
         return null;
@@ -392,6 +400,9 @@ function persistReplaySequence(sessionId, replayId, startedAtMs, sequence, linkB
         ...(linkBaseUrl || existing?.linkBaseUrl
             ? { linkBaseUrl: linkBaseUrl ?? existing?.linkBaseUrl }
             : {}),
+        ...(existing?.replayId === replayId && existing.analyticsEventCount
+            ? { analyticsEventCount: existing.analyticsEventCount }
+            : {}),
     });
 }
 function clampSamplingRate(value) {
@@ -2510,6 +2521,7 @@ async function startSessionReplayRecorder(state, normalized, sessionId, sampled,
                 ...(normalized.linkBaseUrl
                     ? { linkBaseUrl: normalized.linkBaseUrl }
                     : {}),
+                analyticsEventCount: 0,
                 resumed: false,
             };
         }
@@ -2548,6 +2560,11 @@ async function startSessionReplayRecorder(state, normalized, sessionId, sampled,
     state.lastAuthenticatedProperties = replayUserEmail(initialProperties)
         ? { ...initialProperties }
         : null;
+    // A resumed replay keeps its marker count, across page reloads too.
+    if (state.analyticsEventReplayId !== state.replayId) {
+        state.analyticsEventReplayId = state.replayId;
+        state.analyticsEventCount = replaySession.analyticsEventCount;
+    }
     state.active = true;
     try {
         const stopRecorder = rrweb.record({
@@ -2743,6 +2760,31 @@ export function emitSessionReplayException(input) {
         ...(input.url ? { url: input.url } : {}),
     });
 }
+/**
+ * Mark a tracked analytics event on the replay timeline. Only the event name
+ * is recorded; event properties stay out of the replay.
+ */
+export function emitSessionReplayAnalyticsEvent(name) {
+    const state = getState();
+    if (!state.active || !state.addCustomEvent)
+        return;
+    if (state.analyticsEventCount >= MAX_ANALYTICS_EVENTS_PER_REPLAY)
+        return;
+    const bounded = name.trim().slice(0, MAX_ANALYTICS_EVENT_NAME_LENGTH);
+    if (!bounded)
+        return;
+    state.analyticsEventCount += 1;
+    const stored = readStoredReplaySession();
+    if (stored?.replayId === state.replayId) {
+        writeStoredReplaySession({
+            ...stored,
+            analyticsEventCount: state.analyticsEventCount,
+        });
+    }
+    emitReplayCustomEvent(state, SESSION_REPLAY_ANALYTICS_EVENT_TAG, {
+        name: bounded,
+    });
+}
 export function emitSessionReplayAgentChatEvent(input) {
     const state = getState();
     if (!state.active || !state.addCustomEvent)

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

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

package/dist/file-upload/builder.js

@@ -34,6 +34,13 @@ async function assertOk(res, label) {
         throw Object.assign(new Error(`${label} (${res.status}): ${body || res.statusText}`), { status: res.status });
     }
 }
+function confirmedBuilderAuthorizationFailure(error) {
+    const cause = error instanceof Error ? error : new Error(String(error));
+    return Object.assign(new Error(cause.message, { cause }), {
+        status: 401,
+        errorCode: "builder_credentials_rejected",
+    });
+}
 /**
  * Run a Builder asset API call, and on a 401 refresh the OAuth access token
  * once and retry. A token can be revoked or rotated before its stated
@@ -51,10 +58,21 @@ async function withAssetAuthorization(run, held = {}) {
         const refreshed = await assetAuthorization({ forceRefresh: true });
         // The same token again (no refresh token, a key credential) would only
         // repeat the 401; report the original refusal instead.
-        if (refreshed.authorization === auth.authorization)
+        if (refreshed.authorization === auth.authorization) {
+            if (auth.apiKey)
+                throw confirmedBuilderAuthorizationFailure(error);
             throw error;
+        }
         held.auth = refreshed;
-        return run(refreshed);
+        try {
+            return await run(refreshed);
+        }
+        catch (retryError) {
+            if (retryError?.status !== 401) {
+                throw retryError;
+            }
+            throw confirmedBuilderAuthorizationFailure(retryError);
+        }
     }
 }
 async function uploadLargeFileViaSignedUrl(input, held, bareMimeType, bytes) {