@agent-native/core 0.175.2-nightly-20260826150235 → 0.175.3

package/dist/client/hooks/index.js

@@ -10,5 +10,6 @@ export { createAgentNativeQueryClient } from "../create-query-client.js";
 export { AppProviders } from "../app-providers.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";
 export { usePinchZoom } from "../use-pinch-zoom.js";
+export { isPinchZoomDelta, normalizeWheelDeltaPx, resolveZoomGestureDevice, MAX_PINCH_DELTA_PX, ZOOM_GESTURE_IDLE_RESET_MS, } from "../zoom-gesture.js";
 export { useAvatarUrl, uploadAvatar, invalidateAvatarCache, } from "../use-avatar.js";
 export { usePollLoop, } from "../use-poll-loop.js";

package/dist/client/use-pinch-zoom.js

@@ -1,4 +1,5 @@
 import { useEffect, useRef } from "react";
+import { clampZoomFactor, normalizeWheelDeltaPx, resolveZoomGestureDevice, zoomFactorForWheelDelta, } from "./zoom-gesture.js";
 /**
  * Pinch-to-zoom for canvas-style editors. Wires the trackpad pinch / Cmd+scroll
  * wheel gesture and 2-pointer touchscreen pinch onto a scrolling container.
@@ -46,6 +47,7 @@ export function usePinchZoom({ containerRef, zoom, setZoom, min = 25, max = 400,
         let simScrollLeft = 0;
         let simScrollTop = 0;
         let rafId = null;
+        let gestureDevice = null;
         const flush = () => {
             rafId = null;
             if (pendingZoom === null)
@@ -68,13 +70,23 @@ export function usePinchZoom({ containerRef, zoom, setZoom, min = 25, max = 400,
         const handleWheel = (e) => {
             if (!(e.ctrlKey || e.metaKey))
                 return;
-            e.preventDefault();
+            // Chrome sends non-cancelable wheel events during a fling; cancelling one
+            // is a no-op that logs an Intervention per event and still scrolls.
+            if (e.cancelable)
+                e.preventDefault();
+            gestureDevice = resolveZoomGestureDevice({
+                deltaY: e.deltaY,
+                deltaMode: e.deltaMode,
+                ctrlKey: e.ctrlKey,
+                metaKey: e.metaKey,
+                atMs: e.timeStamp,
+                previous: gestureDevice,
+            });
             // Use the latest not-yet-applied zoom (if a flush is pending) so rapid
             // wheel events within the same frame compound correctly instead of
             // each computing off the last-committed React state.
             const currentZoom = pendingZoom ?? zoomRef.current;
-            const clampedDelta = Math.max(-50, Math.min(50, e.deltaY));
-            const factor = Math.exp(-clampedDelta * 0.01);
+            const factor = clampZoomFactor(zoomFactorForWheelDelta(normalizeWheelDeltaPx(e.deltaY, e.deltaMode), gestureDevice.pinch));
             const nextZoom = clamp(currentZoom * factor);
             if (nextZoom === currentZoom)
                 return;
@@ -137,7 +149,8 @@ export function usePinchZoom({ containerRef, zoom, setZoom, min = 25, max = 400,
                     pendingZoom = nextZoom;
                     scheduleFlush();
                 }
-                e.preventDefault();
+                if (e.cancelable)
+                    e.preventDefault();
             }
         };
         const handlePointerEnd = (e) => {

package/dist/client/zoom-gesture.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Wheel/pinch → zoom-factor conversion, shared by every zoomable canvas.
+ *
+ * A mouse wheel and a trackpad pinch arrive as the same event type, their
+ * deltas overlap, and the sensitivity each needs differs by roughly 8x — so a
+ * surface that re-implements either half gets the split wrong the same way.
+ */
+/**
+ * Largest |deltaY| finger separation produces; above it every device is a
+ * wheel. macOS reports an accelerated mouse wheel as large FRACTIONAL deltas,
+ * so fractionality alone cannot separate the two.
+ */
+export declare const MAX_PINCH_DELTA_PX = 40;
+/**
+ * A ctrl/meta wheel run with a longer gap than this starts a new gesture and
+ * the device is classified again.
+ */
+export declare const ZOOM_GESTURE_IDLE_RESET_MS = 150;
+/** Which curve a zoom gesture's deltas run through, latched for its duration. */
+export type ZoomGestureDevice = {
+    pinch: boolean;
+    lastEventAtMs: number;
+};
+/**
+ * Whether a delta is small enough to be finger separation. Magnitude only —
+ * `resolveZoomGestureDevice` owns the modifier and delta-mode part of the
+ * decision, and is what callers should ask.
+ */
+export declare function isPinchZoomDelta(deltaY: number): boolean;
+/**
+ * Latch the input device for a zoom gesture: one delta cannot identify a device
+ * (macOS ramps an accelerated wheel up from pinch-sized values), so this only
+ * ever loosens pinch → wheel, and re-decides after an idle gap.
+ */
+export declare function resolveZoomGestureDevice(args: {
+    deltaY: number;
+    deltaMode: number;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    atMs: number;
+    previous: ZoomGestureDevice | null;
+}): ZoomGestureDevice;
+/** One mouse-wheel detent in `deltaMode === 0` pixels (Chrome/Safari). */
+export declare const MOUSE_WHEEL_NOTCH_PX = 100;
+/** Zoom multiplier for one full mouse-wheel notch, matching Figma's feel. */
+export declare const ZOOM_STEP_PER_NOTCH = 1.1;
+/** Multiplier exponent per pixel of trackpad pinch delta. */
+export declare const PINCH_ZOOM_SENSITIVITY = 0.0075;
+/** Ceiling on a single frame's zoom change, in either direction. */
+export declare const MAX_ZOOM_FACTOR_PER_FRAME = 1.6;
+/** Pixels one `DOM_DELTA_LINE` step stands for. */
+export declare const WHEEL_LINE_HEIGHT_PX = 16;
+/** Pixels one `DOM_DELTA_PAGE` step stands for. */
+export declare const WHEEL_PAGE_HEIGHT_PX = 800;
+/**
+ * Convert a delta to pixels. The curves below are calibrated in pixels, so a
+ * Firefox line-mode tick of 3 is a full notch, not 3px of travel. Classify
+ * with the RAW delta and its real mode — normalising first would push a line
+ * tick into the pinch band.
+ */
+export declare function normalizeWheelDeltaPx(delta: number, deltaMode: number): number;
+/** Unclamped zoom multiplier for a wheel/pinch delta. Negative delta (scroll
+ *  up / pinch open) zooms in, matching the browser's wheel convention. */
+export declare function zoomFactorForWheelDelta(deltaY: number, pinch: boolean): number;
+/** Bounds one frame's zoom change symmetrically in multiplicative space, so
+ *  zooming in and back out by the same clamped amount is a round trip. */
+export declare function clampZoomFactor(factor: number): number;
+/**
+ * Fold one event into a frame's accumulated zoom. Both curves are exponential
+ * in the delta, so multiplying per-event factors equals summing same-curve
+ * deltas — and unlike a delta sum it stays exact when a frame catches two
+ * curves, instead of forcing the accumulator to discard one of them.
+ */
+export declare function accumulateZoomFactor(pendingFactor: number, deltaY: number, pinch: boolean): number;

package/dist/client/zoom-gesture.js

@@ -0,0 +1,100 @@
+/**
+ * Wheel/pinch → zoom-factor conversion, shared by every zoomable canvas.
+ *
+ * A mouse wheel and a trackpad pinch arrive as the same event type, their
+ * deltas overlap, and the sensitivity each needs differs by roughly 8x — so a
+ * surface that re-implements either half gets the split wrong the same way.
+ */
+/**
+ * Largest |deltaY| finger separation produces; above it every device is a
+ * wheel. macOS reports an accelerated mouse wheel as large FRACTIONAL deltas,
+ * so fractionality alone cannot separate the two.
+ */
+export const MAX_PINCH_DELTA_PX = 40;
+/**
+ * A ctrl/meta wheel run with a longer gap than this starts a new gesture and
+ * the device is classified again.
+ */
+export const ZOOM_GESTURE_IDLE_RESET_MS = 150;
+/**
+ * Whether a delta is small enough to be finger separation. Magnitude only —
+ * `resolveZoomGestureDevice` owns the modifier and delta-mode part of the
+ * decision, and is what callers should ask.
+ */
+export function isPinchZoomDelta(deltaY) {
+    if (!Number.isFinite(deltaY))
+        return false;
+    return Math.abs(deltaY) < MAX_PINCH_DELTA_PX;
+}
+/**
+ * Latch the input device for a zoom gesture: one delta cannot identify a device
+ * (macOS ramps an accelerated wheel up from pinch-sized values), so this only
+ * ever loosens pinch → wheel, and re-decides after an idle gap.
+ */
+export function resolveZoomGestureDevice(args) {
+    const { deltaY, deltaMode, ctrlKey, metaKey, atMs, previous } = args;
+    const at = Number.isFinite(atMs) ? atMs : 0;
+    // Line/page modes are always discrete wheels. A held Cmd means the user
+    // reached for a modifier, so the wheel is whatever device they are holding —
+    // only the browser's synthetic ctrl+wheel can be a trackpad pinch.
+    const looksLikePinch = deltaMode === 0 && ctrlKey && !metaKey && isPinchZoomDelta(deltaY);
+    const continuesGesture = previous !== null &&
+        Number.isFinite(previous.lastEventAtMs) &&
+        at - previous.lastEventAtMs <= ZOOM_GESTURE_IDLE_RESET_MS;
+    if (!continuesGesture)
+        return { pinch: looksLikePinch, lastEventAtMs: at };
+    return { pinch: previous.pinch && looksLikePinch, lastEventAtMs: at };
+}
+/** One mouse-wheel detent in `deltaMode === 0` pixels (Chrome/Safari). */
+export const MOUSE_WHEEL_NOTCH_PX = 100;
+/** Zoom multiplier for one full mouse-wheel notch, matching Figma's feel. */
+export const ZOOM_STEP_PER_NOTCH = 1.1;
+/** Multiplier exponent per pixel of trackpad pinch delta. */
+export const PINCH_ZOOM_SENSITIVITY = 0.0075;
+/** Ceiling on a single frame's zoom change, in either direction. */
+export const MAX_ZOOM_FACTOR_PER_FRAME = 1.6;
+/** Pixels one `DOM_DELTA_LINE` step stands for. */
+export const WHEEL_LINE_HEIGHT_PX = 16;
+/** Pixels one `DOM_DELTA_PAGE` step stands for. */
+export const WHEEL_PAGE_HEIGHT_PX = 800;
+/**
+ * Convert a delta to pixels. The curves below are calibrated in pixels, so a
+ * Firefox line-mode tick of 3 is a full notch, not 3px of travel. Classify
+ * with the RAW delta and its real mode — normalising first would push a line
+ * tick into the pinch band.
+ */
+export function normalizeWheelDeltaPx(delta, deltaMode) {
+    if (!Number.isFinite(delta))
+        return 0;
+    if (deltaMode === 1)
+        return delta * WHEEL_LINE_HEIGHT_PX;
+    if (deltaMode === 2)
+        return delta * WHEEL_PAGE_HEIGHT_PX;
+    return delta;
+}
+/** Unclamped zoom multiplier for a wheel/pinch delta. Negative delta (scroll
+ *  up / pinch open) zooms in, matching the browser's wheel convention. */
+export function zoomFactorForWheelDelta(deltaY, pinch) {
+    if (!Number.isFinite(deltaY) || deltaY === 0)
+        return 1;
+    return pinch
+        ? Math.exp(-deltaY * PINCH_ZOOM_SENSITIVITY)
+        : Math.pow(ZOOM_STEP_PER_NOTCH, -deltaY / MOUSE_WHEEL_NOTCH_PX);
+}
+/** Bounds one frame's zoom change symmetrically in multiplicative space, so
+ *  zooming in and back out by the same clamped amount is a round trip. */
+export function clampZoomFactor(factor) {
+    if (!Number.isFinite(factor) || factor <= 0)
+        return 1;
+    return Math.min(MAX_ZOOM_FACTOR_PER_FRAME, Math.max(1 / MAX_ZOOM_FACTOR_PER_FRAME, factor));
+}
+/**
+ * Fold one event into a frame's accumulated zoom. Both curves are exponential
+ * in the delta, so multiplying per-event factors equals summing same-curve
+ * deltas — and unlike a delta sum it stays exact when a frame catches two
+ * curves, instead of forcing the accumulator to discard one of them.
+ */
+export function accumulateZoomFactor(pendingFactor, deltaY, pinch) {
+    const base = Number.isFinite(pendingFactor) && pendingFactor > 0 ? pendingFactor : 1;
+    return base * zoomFactorForWheelDelta(deltaY, pinch);
+}

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 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

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/observability/routes.d.ts

@@ -41,16 +41,16 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
+    error?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-    error?: undefined;
     ok?: undefined;
 } | {
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
-    error?: undefined;
     ok?: undefined;
 } | {
     summary?: undefined;
@@ -59,9 +59,9 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     error: any;
     ok?: undefined;
 } | {
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     ok: boolean;
-    error?: undefined;
 }>>;

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -76,8 +76,9 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     }>>;
 }, z.core.$strip>>, {
     id?: undefined;
+    provider?: undefined;
     deleted?: undefined;
-    found?: undefined;
+    message?: undefined;
     providers: {
         id: string;
         label: string;
@@ -88,46 +89,45 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         updatedAt: number;
     }[];
     count: number;
-    provider?: undefined;
+    found?: undefined;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
-    id?: undefined;
     count?: undefined;
+    id?: undefined;
     deleted?: undefined;
+    message?: undefined;
     providers?: undefined;
     found: boolean;
     provider: import("../custom-registry.js").CustomProviderConfig;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
     count?: undefined;
+    provider?: undefined;
     deleted?: undefined;
+    message?: undefined;
     providers?: undefined;
-    provider?: undefined;
     found: boolean;
     id: string;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
     count?: undefined;
-    found?: undefined;
-    providers?: undefined;
     provider?: undefined;
+    message?: undefined;
+    providers?: undefined;
+    found?: undefined;
     deleted: boolean;
     id: string;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
     count?: undefined;
+    provider?: undefined;
     deleted?: undefined;
-    found?: undefined;
     providers?: undefined;
-    provider?: undefined;
+    found?: undefined;
     registered: boolean;
     id: string;
     label: string;

package/dist/provider-api/actions/provider-api.d.ts

@@ -311,11 +311,8 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         notes?: string | undefined;
         scope?: "org" | "user" | undefined;
     }, {
-        message?: undefined;
-        id?: undefined;
-        provider?: undefined;
         deleted?: undefined;
-        found?: undefined;
+        id?: undefined;
         providers: {
             id: string;
             label: string;
@@ -326,44 +323,47 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
             updatedAt: number;
         }[];
         count: number;
+        provider?: undefined;
+        found?: undefined;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
-        id?: undefined;
+    } | {
         deleted?: undefined;
+        id?: undefined;
         providers?: undefined;
         count?: undefined;
         found: boolean;
         provider: import("../custom-registry.js").CustomProviderConfig;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
-        provider?: undefined;
+    } | {
         deleted?: undefined;
         providers?: undefined;
         count?: undefined;
+        provider?: undefined;
         found: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
-        provider?: undefined;
-        found?: undefined;
+    } | {
         providers?: undefined;
         count?: undefined;
+        provider?: undefined;
+        found?: undefined;
         deleted: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
+        message?: undefined;
     } | {
-        provider?: undefined;
         deleted?: undefined;
-        found?: undefined;
         providers?: undefined;
         count?: undefined;
+        provider?: undefined;
+        found?: undefined;
         registered: boolean;
         id: string;
         label: string;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -34,10 +34,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
-    error?: undefined;
 }>>;
 export {};

package/dist/server/builder-browser.d.ts

@@ -54,9 +54,10 @@ export declare function isBuilderConnectCallbackUrlAllowed(candidate: string, ev
  * `getAppBasePath()` + `BUILDER_CALLBACK_PATH`. Intentionally ignores any
  * `?redirect_uri=` query override — connect always returns to this app's own
  * callback. Validated with `isBuilderConnectCallbackUrlAllowed` (Railway-safe,
- * no fixed domain allowlist).
+ * no fixed domain allowlist). When state is provided, bind it into the exact
+ * registered callback URI because Builder can omit top-level OAuth state.
  */
-export declare function resolveBuilderConnectCallbackUrl(event: H3Event): string | null;
+export declare function resolveBuilderConnectCallbackUrl(event: H3Event, state?: string): string | null;
 export declare function isSafeBuilderRelayTargetOrigin(value: string): boolean;
 export declare function isTrustedBuilderRelayTargetOrigin(value: string): boolean;
 /**
@@ -109,21 +110,22 @@ export declare function verifyBuilderRelayRequest(input: {
     body: BuilderRelayRequestBody;
 } | null;
 /**
- * Query-param name carrying the signed CSRF state on the connect→callback
- * round-trip. Prefixed with `_an_` to avoid collisions if Builder ever
- * adds standard OAuth `state` support to cli-auth. Builder preserves
- * the path/query of `redirect_url` verbatim when redirecting back, so
- * we embed `_an_state=…` inside the redirect_url query string at
- * connect time and read it back on the callback.
+ * Query-param name carrying the signed CSRF state on the legacy
+ * connect→callback round-trip. Prefixed with `_an_` to avoid collisions if
+ * Builder ever adds standard OAuth `state` support to cli-auth.
  */
 export declare const BUILDER_STATE_PARAM = "_an_state";
 export declare const BUILDER_CONNECT_PARAM = "_an_connect";
+export declare const BUILDER_CONNECT_STATE_COOKIE = "an_builder_connect_state";
 export declare const BUILDER_CONNECT_OWNER_COOKIE = "an_builder_connect_owner";
 export declare const BUILDER_SIGNUP_SOURCE_PARAM = "signupSource";
 export declare const BUILDER_AGENT_NATIVE_FLOW_PARAM = "agentNativeFlow";
 export declare const BUILDER_AGENT_NATIVE_CONNECT_SOURCE_PARAM = "agentNativeConnectSource";
 export declare const BUILDER_AGENT_NATIVE_APP_PARAM = "agentNativeApp";
 export declare const BUILDER_AGENT_NATIVE_TEMPLATE_PARAM = "agentNativeTemplate";
+export declare function appendBuilderConnectStateCookie(value: string | null | undefined, state: string): string;
+export declare function removeBuilderConnectStateCookie(value: string | null | undefined, state: string): string;
+export declare function resolveBuilderConnectCallbackState(queryState: string | null, cookieState: string | null | undefined): string | null;
 export interface BuilderConnectTrackingParams {
     signupSource?: string;
     agentNativeFlow?: string;
@@ -240,11 +242,9 @@ export declare function resolveIsBuilderBranchingEnabled(): Promise<boolean>;
 export declare const BUILDER_OPENER_PARAM = "_an_opener";
 /**
  * Build the Builder cli-auth URL for the connect popup. When a signed
- * `state` token is supplied it is embedded inside the `redirect_url`
- * query string so it survives Builder's redirect verbatim — Builder
- * preserves the redirect_url's existing query when appending p-key /
- * api-key / etc., so we don't depend on Builder echoing a top-level
- * `state` parameter (it doesn't).
+ * `state` token is supplied it is embedded inside the `redirect_url` query
+ * string. The connect route also stores it in an HttpOnly cookie because
+ * Builder may strip the callback query while appending its response params.
  *
  * Status responses can surface this URL directly; the legacy
  * `/_agent-native/builder/connect` trampoline still calls this helper for

package/dist/server/builder-browser.js

@@ -109,15 +109,17 @@ export function isBuilderConnectCallbackUrlAllowed(candidate, event) {
  * `getAppBasePath()` + `BUILDER_CALLBACK_PATH`. Intentionally ignores any
  * `?redirect_uri=` query override — connect always returns to this app's own
  * callback. Validated with `isBuilderConnectCallbackUrlAllowed` (Railway-safe,
- * no fixed domain allowlist).
+ * no fixed domain allowlist). When state is provided, bind it into the exact
+ * registered callback URI because Builder can omit top-level OAuth state.
  */
-export function resolveBuilderConnectCallbackUrl(event) {
-    const withBase = `${getOrigin(event)}${getAppBasePath()}${BUILDER_CALLBACK_PATH}`;
+export function resolveBuilderConnectCallbackUrl(event, state) {
+    const stateSuffix = state ? `?state=${encodeURIComponent(state)}` : "";
+    const withBase = `${getOrigin(event)}${getAppBasePath()}${BUILDER_CALLBACK_PATH}${stateSuffix}`;
     if (isBuilderConnectCallbackUrlAllowed(withBase, event))
         return withBase;
     // Match google-oauth default-redirect behavior when the request is not under
     // APP_BASE_PATH: fall back to the root `/_agent-native/...` callback.
-    const root = `${getOrigin(event)}${BUILDER_CALLBACK_PATH}`;
+    const root = `${getOrigin(event)}${BUILDER_CALLBACK_PATH}${stateSuffix}`;
     if (root !== withBase && isBuilderConnectCallbackUrlAllowed(root, event)) {
         return root;
     }
@@ -404,21 +406,52 @@ function escapeHtml(value) {
     });
 }
 /**
- * Query-param name carrying the signed CSRF state on the connect→callback
- * round-trip. Prefixed with `_an_` to avoid collisions if Builder ever
- * adds standard OAuth `state` support to cli-auth. Builder preserves
- * the path/query of `redirect_url` verbatim when redirecting back, so
- * we embed `_an_state=…` inside the redirect_url query string at
- * connect time and read it back on the callback.
+ * Query-param name carrying the signed CSRF state on the legacy
+ * connect→callback round-trip. Prefixed with `_an_` to avoid collisions if
+ * Builder ever adds standard OAuth `state` support to cli-auth.
  */
 export const BUILDER_STATE_PARAM = "_an_state";
 export const BUILDER_CONNECT_PARAM = "_an_connect";
+export const BUILDER_CONNECT_STATE_COOKIE = "an_builder_connect_state";
 export const BUILDER_CONNECT_OWNER_COOKIE = "an_builder_connect_owner";
 export const BUILDER_SIGNUP_SOURCE_PARAM = "signupSource";
 export const BUILDER_AGENT_NATIVE_FLOW_PARAM = "agentNativeFlow";
 export const BUILDER_AGENT_NATIVE_CONNECT_SOURCE_PARAM = "agentNativeConnectSource";
 export const BUILDER_AGENT_NATIVE_APP_PARAM = "agentNativeApp";
 export const BUILDER_AGENT_NATIVE_TEMPLATE_PARAM = "agentNativeTemplate";
+const BUILDER_CONNECT_STATE_COOKIE_MAX_ENTRIES = 4;
+function parseBuilderConnectStateCookie(value) {
+    if (!value)
+        return [];
+    const states = value.split(",");
+    if (states.length > BUILDER_CONNECT_STATE_COOKIE_MAX_ENTRIES ||
+        states.some((state) => !isSignedBuilderConnectState(state))) {
+        return null;
+    }
+    return [...new Set(states)];
+}
+export function appendBuilderConnectStateCookie(value, state) {
+    const states = parseBuilderConnectStateCookie(value) ?? [];
+    return [...states.filter((candidate) => candidate !== state), state]
+        .slice(-BUILDER_CONNECT_STATE_COOKIE_MAX_ENTRIES)
+        .join(",");
+}
+export function removeBuilderConnectStateCookie(value, state) {
+    return (parseBuilderConnectStateCookie(value) ?? [])
+        .filter((candidate) => candidate !== state)
+        .join(",");
+}
+export function resolveBuilderConnectCallbackState(queryState, cookieState) {
+    const cookieStates = parseBuilderConnectStateCookie(cookieState);
+    if (cookieState && !cookieStates)
+        return null;
+    if (queryState !== null) {
+        if (cookieStates?.length && !cookieStates.includes(queryState))
+            return null;
+        return queryState;
+    }
+    return cookieStates?.length === 1 ? cookieStates[0] : null;
+}
 const BUILDER_STATE_TTL_MS = 10 * 60 * 1000;
 const BUILDER_SIGNUP_SOURCE = "agent-native";
 function cleanTrackingParam(value) {
@@ -764,11 +797,9 @@ function isBuilderOpenerOriginSafe(value) {
 }
 /**
  * Build the Builder cli-auth URL for the connect popup. When a signed
- * `state` token is supplied it is embedded inside the `redirect_url`
- * query string so it survives Builder's redirect verbatim — Builder
- * preserves the redirect_url's existing query when appending p-key /
- * api-key / etc., so we don't depend on Builder echoing a top-level
- * `state` parameter (it doesn't).
+ * `state` token is supplied it is embedded inside the `redirect_url` query
+ * string. The connect route also stores it in an HttpOnly cookie because
+ * Builder may strip the callback query while appending its response params.
  *
  * Status responses can surface this URL directly; the legacy
  * `/_agent-native/builder/connect` trampoline still calls this helper for

package/dist/server/builder-oauth.d.ts

@@ -1,3 +1,4 @@
+import { type McpOAuthCredentialBundle } from "../mcp-client/oauth-client.js";
 export declare const BUILDER_OAUTH_ISSUER = "https://mcp.builder.io";
 export declare const BUILDER_OAUTH_RESOURCE = "https://api.builder.io";
 export declare const BUILDER_OAUTH_SCOPE = "builder:ai:invoke";
@@ -26,6 +27,17 @@ export declare function startBuilderOAuthAuthorization(input: {
     authorizationUrl: string;
     pending: BuilderOAuthPendingFlow;
 }>;
+export declare function exchangeBuilderOAuthAuthorization(input: {
+    ownerEmail: string;
+    code: string;
+    iss?: string;
+    pending: BuilderOAuthPendingFlow;
+}): Promise<McpOAuthCredentialBundle>;
+export declare function saveBuilderOAuthCredentials(input: {
+    ownerEmail: string;
+    orgId?: string;
+    credentials: McpOAuthCredentialBundle;
+}): Promise<void>;
 export declare function finishBuilderOAuthAuthorization(input: {
     ownerEmail: string;
     orgId?: string;

package/dist/server/builder-oauth.js

@@ -133,7 +133,7 @@ export async function startBuilderOAuthAuthorization(input) {
         },
     };
 }
-export async function finishBuilderOAuthAuthorization(input) {
+export async function exchangeBuilderOAuthAuthorization(input) {
     validateMcpOAuthCallbackIssuer(input.pending.discoveryState, input.iss);
     const result = await finishMcpOAuthAuthorization({
         serverUrl: BUILDER_OAUTH_RESOURCE,
@@ -148,11 +148,22 @@ export async function finishBuilderOAuthAuthorization(input) {
     if (!isBuilderCredential(result.credentials)) {
         throw new Error("Builder OAuth exchange returned credentials for another resource");
     }
+    return withRecordedScopes(result.credentials);
+}
+export async function saveBuilderOAuthCredentials(input) {
     await saveMcpOAuthCredentials({
         ...(input.orgId
             ? orgOwnerOptions(input.orgId)
             : await ownerOptions(input.ownerEmail)),
-        credentials: withRecordedScopes(result.credentials),
+        credentials: input.credentials,
+    });
+}
+export async function finishBuilderOAuthAuthorization(input) {
+    const credentials = await exchangeBuilderOAuthAuthorization(input);
+    await saveBuilderOAuthCredentials({
+        ownerEmail: input.ownerEmail,
+        orgId: input.orgId,
+        credentials,
     });
 }
 export async function markBuilderOAuthReconnectRequired(ownerEmail) {