@agent-native/core 0.117.2 → 0.118.1

package/corpus/core/src/client/transcription/use-live-transcription.ts

@@ -6,9 +6,9 @@
  * stop when the user hits stop. The accumulated transcript is available
  * immediately — no round-trip to Whisper needed.
  *
- * Higher-quality backends (Groq Whisper, OpenAI Whisper, Deepgram) can
- * refine the result afterward, but this gives users something useful
- * from second zero even without an API key.
+ * Builder can transcribe the original recording afterward if native capture
+ * produces no text, but this gives users something useful from second zero
+ * without a cloud transcription request.
  */
 
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -58,12 +58,21 @@ export function useLiveTranscription(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const recognitionRef = useRef<any>(null);
   const transcriptRef = useRef("");
+  const interimRef = useRef("");
   const stoppedManuallyRef = useRef(false);
   const stopWaiterRef = useRef<((text: string) => void) | null>(null);
   const restartTimerRef = useRef<number | null>(null);
   const networkErrorCountRef = useRef(0);
   const restartDelayRef = useRef(0);
 
+  const currentTranscript = useCallback(
+    () =>
+      [transcriptRef.current.trim(), interimRef.current.trim()]
+        .filter(Boolean)
+        .join(" "),
+    [],
+  );
+
   const supported = !!getSpeechRecognitionCtor();
 
   const start = useCallback(() => {
@@ -89,6 +98,7 @@ export function useLiveTranscription(
     recognition.lang = lang;
     recognitionRef.current = recognition;
     transcriptRef.current = "";
+    interimRef.current = "";
     stoppedManuallyRef.current = false;
     networkErrorCountRef.current = 0;
     restartDelayRef.current = 0;
@@ -107,6 +117,7 @@ export function useLiveTranscription(
           interim += text;
         }
       }
+      interimRef.current = interim;
       setInterimText(interim);
       if (event.results.length > 0) {
         networkErrorCountRef.current = 0;
@@ -167,7 +178,7 @@ export function useLiveTranscription(
       }
       setIsActive(false);
       if (stopWaiterRef.current) {
-        stopWaiterRef.current(transcriptRef.current);
+        stopWaiterRef.current(currentTranscript());
       }
     };
 
@@ -177,14 +188,16 @@ export function useLiveTranscription(
     } catch {
       /* browser may block without user gesture */
     }
-  }, [lang]);
+  }, [currentTranscript, lang]);
 
   const stop = useCallback((): string => {
+    const text = currentTranscript();
     stoppedManuallyRef.current = true;
     if (restartTimerRef.current !== null) {
       window.clearTimeout(restartTimerRef.current);
       restartTimerRef.current = null;
     }
+    interimRef.current = "";
     setInterimText("");
     if (recognitionRef.current) {
       try {
@@ -195,51 +208,57 @@ export function useLiveTranscription(
       recognitionRef.current = null;
     }
     setIsActive(false);
-    return transcriptRef.current;
-  }, []);
+    return text;
+  }, [currentTranscript]);
 
-  const stopAndWait = useCallback((timeoutMs = 1200): Promise<string> => {
-    stoppedManuallyRef.current = true;
-    if (restartTimerRef.current !== null) {
-      window.clearTimeout(restartTimerRef.current);
-      restartTimerRef.current = null;
-    }
-    setInterimText("");
-
-    const recognition = recognitionRef.current;
-    if (!recognition) {
-      setIsActive(false);
-      return Promise.resolve(transcriptRef.current);
-    }
+  const stopAndWait = useCallback(
+    (timeoutMs = 1200): Promise<string> => {
+      stoppedManuallyRef.current = true;
+      if (restartTimerRef.current !== null) {
+        window.clearTimeout(restartTimerRef.current);
+        restartTimerRef.current = null;
+      }
+      setInterimText("");
 
-    return new Promise((resolve) => {
-      let settled = false;
-      const finish = (text: string) => {
-        if (settled) return;
-        settled = true;
-        window.clearTimeout(timeout);
-        if (stopWaiterRef.current === finish) {
-          stopWaiterRef.current = null;
-        }
-        if (recognitionRef.current === recognition) {
-          recognitionRef.current = null;
-        }
+      const recognition = recognitionRef.current;
+      if (!recognition) {
+        const text = currentTranscript();
+        interimRef.current = "";
         setIsActive(false);
-        resolve(text);
-      };
+        return Promise.resolve(text);
+      }
 
-      const timeout = window.setTimeout(() => {
-        finish(transcriptRef.current);
-      }, timeoutMs);
+      return new Promise((resolve) => {
+        let settled = false;
+        const finish = (text: string) => {
+          if (settled) return;
+          settled = true;
+          window.clearTimeout(timeout);
+          if (stopWaiterRef.current === finish) {
+            stopWaiterRef.current = null;
+          }
+          if (recognitionRef.current === recognition) {
+            recognitionRef.current = null;
+          }
+          interimRef.current = "";
+          setIsActive(false);
+          resolve(text);
+        };
 
-      stopWaiterRef.current = finish;
-      try {
-        recognition.stop();
-      } catch {
-        finish(transcriptRef.current);
-      }
-    });
-  }, []);
+        const timeout = window.setTimeout(() => {
+          finish(currentTranscript());
+        }, timeoutMs);
+
+        stopWaiterRef.current = finish;
+        try {
+          recognition.stop();
+        } catch {
+          finish(currentTranscript());
+        }
+      });
+    },
+    [currentTranscript],
+  );
 
   const pause = useCallback(() => {
     if (!recognitionRef.current) return;

package/corpus/core/src/client/use-agent-engine-configured.ts

@@ -6,7 +6,11 @@ import { agentNativePath } from "./api-path.js";
 const PROVIDER_ENV_VAR_SET = new Set(PROVIDER_ENV_VARS);
 
 /** `unknown` until the first check resolves, so callers don't flash the gate. */
-export type AgentEngineConfiguredState = "unknown" | "configured" | "missing";
+export type AgentEngineConfiguredState =
+  | "unknown"
+  | "configured"
+  | "missing"
+  | "unavailable";
 
 export interface UseAgentEngineConfiguredResult {
   /** True once we know nothing can run the agent (no key / Builder / BYOK). */
@@ -30,7 +34,6 @@ export interface UseAgentEngineConfiguredOptions {
 }
 
 const DEFAULT_STATUS_CHECK_TIMEOUT_MS = 2500;
-const UNKNOWN_STATUS_RETRY_MS = 2000;
 
 async function fetchStatusJson(
   path: string,
@@ -108,11 +111,10 @@ export async function fetchAgentEngineConfiguredState(
     fetchStatusJson("/_agent-native/agent-engine/status", timeoutMs),
   ]);
 
-  // All three failed — likely a flaky network; keep the caller in unknown.
-  // Even an explicit missing-key stream event should not pin the composer into
-  // setup without a fresh authoritative status response.
+  // All three failed — surface a retryable unavailable state instead of
+  // leaving the composer in an infinite checking loop.
   if (envKeys == null && builderStatus == null && engineStatus == null) {
-    return "unknown";
+    return "unavailable";
   }
 
   const envKeysKnown = Array.isArray(envKeys);
@@ -138,7 +140,7 @@ export async function fetchAgentEngineConfiguredState(
   if (engineStatusKnown) return "missing";
 
   // Compatibility fallback for older hosts without the canonical route.
-  return envKeysKnown && builderStatusKnown ? "missing" : "unknown";
+  return envKeysKnown && builderStatusKnown ? "missing" : "unavailable";
 }
 
 /**
@@ -146,7 +148,8 @@ export async function fetchAgentEngineConfiguredState(
  * composer and app prompt boxes. Checks the env-key / Builder / BYOK status
  * endpoints on mount, re-checks on `agent-engine:configured-changed`, and folds
  * in the adapter's `agent-chat:missing-api-key` signal. Pass `enabled = false`
- * to short-circuit to configured; flaky requests stay `unknown`.
+ * to short-circuit to configured; unavailable checks can be retried by firing
+ * `agent-engine:configured-changed`.
  */
 export function useAgentEngineConfigured(
   enabled = true,
@@ -156,25 +159,16 @@ export function useAgentEngineConfigured(
 
   useEffect(() => {
     let cancelled = false;
-    let retryId: ReturnType<typeof setTimeout> | undefined;
     // Monotonic call counter: overlapping checks (mount + a
     // `agent-engine:configured-changed` fired right after a key is saved) can
     // resolve out of order; only the latest call may write state, or a slow
     // stale "missing" response would overwrite the fresh "configured" one.
     let requestSeq = 0;
     const check = async (options?: { missingFallback?: boolean }) => {
-      if (retryId !== undefined) {
-        clearTimeout(retryId);
-        retryId = undefined;
-      }
       const seq = ++requestSeq;
       const nextState = await fetchAgentEngineConfiguredState(enabled, options);
       if (cancelled || seq !== requestSeq) return;
-      if (nextState === "unknown") {
-        retryId = setTimeout(() => void check(), UNKNOWN_STATUS_RETRY_MS);
-        return;
-      }
-      setState(nextState);
+      setState(nextState === "unknown" ? "unavailable" : nextState);
     };
     const onConfiguredChanged = () => {
       void check();
@@ -198,7 +192,6 @@ export function useAgentEngineConfigured(
     window.addEventListener("agent-chat:missing-api-key", onMissing);
     return () => {
       cancelled = true;
-      if (retryId !== undefined) clearTimeout(retryId);
       window.removeEventListener(
         "agent-engine:configured-changed",
         onConfiguredChanged,

package/corpus/core/src/client/use-chat-threads.ts

@@ -344,6 +344,24 @@ export function useChatThreads(
   const activeThreadIdRef = useRef(activeThreadId);
   activeThreadIdRef.current = activeThreadId;
 
+  const persistActiveThreadId = useCallback(
+    (id: string) => {
+      try {
+        const threadScope = readKnownThreadScope(id);
+        const targetKey =
+          threadScope === undefined
+            ? activeThreadKey
+            : activeThreadStorageKey(storageKey, threadScope);
+        localStorage.setItem(targetKey, id);
+        localStorage.setItem(
+          activeThreadSeenStorageKey(targetKey),
+          String(Date.now()),
+        );
+      } catch {}
+    },
+    [activeThreadKey, readKnownThreadScope, storageKey],
+  );
+
   // Persist active thread ID — and rehydrate on scope flips. When the user
   // navigates from deck A to deck B, `activeThreadKey` changes; we re-read B's
   // scoped thread only if the currently visible chat is itself scoped to a
@@ -388,6 +406,9 @@ export function useChatThreads(
       setActiveThreadId(nextActiveThreadId);
       return;
     }
+    if (!activeThreadId && !restoreActiveThread && !routeControlsActiveThread) {
+      return;
+    }
     try {
       if (routeControlsActiveThread && !routeThreadId) {
         localStorage.removeItem(activeThreadKey);
@@ -395,14 +416,7 @@ export function useChatThreads(
         return;
       }
       if (activeThreadId) {
-        const threadScope = readKnownThreadScope(activeThreadId);
-        if (threadScope === undefined) return;
-        const targetKey = activeThreadStorageKey(storageKey, threadScope);
-        localStorage.setItem(targetKey, activeThreadId);
-        localStorage.setItem(
-          activeThreadSeenStorageKey(targetKey),
-          String(Date.now()),
-        );
+        persistActiveThreadId(activeThreadId);
       } else {
         localStorage.removeItem(activeThreadKey);
         localStorage.removeItem(activeThreadSeenKey);
@@ -414,7 +428,9 @@ export function useChatThreads(
     activeThreadSeenKey,
     addOptimisticThread,
     autoCreate,
+    persistActiveThreadId,
     readKnownThreadScope,
+    restoreActiveThread,
     routeControlsActiveThread,
     routeThreadId,
     storageKey,
@@ -640,10 +656,11 @@ export function useChatThreads(
       const id = preferredId || createLocalThreadId();
       newlyCreatedRef.current.add(id);
       addOptimisticThread(id, scopeRef.current ?? null);
+      persistActiveThreadId(id);
       setActiveThreadId(id);
       return Promise.resolve(id);
     },
-    [addOptimisticThread],
+    [addOptimisticThread, persistActiveThreadId],
   );
 
   useEffect(() => {
@@ -890,9 +907,13 @@ export function useChatThreads(
     [],
   );
 
-  const switchThread = useCallback((id: string) => {
-    setActiveThreadId(id);
-  }, []);
+  const switchThread = useCallback(
+    (id: string) => {
+      persistActiveThreadId(id);
+      setActiveThreadId(id);
+    },
+    [persistActiveThreadId],
+  );
 
   const removeThread = useCallback(
     async (id: string) => {

package/corpus/core/src/deploy/build.ts

@@ -1805,7 +1805,8 @@ async function buildCloudflarePages() {
   // fails: context-xray token counts fall back to char/4 estimates and the
   // OG image route falls back to SVG.
   const heavyClientExternals = CLOUDFLARE_WORKER_ESBUILD_EXTERNALS.filter(
-    (p) => !Object.hasOwn(CLOUDFLARE_WORKER_STUB_MODULES, p),
+    (p) =>
+      !Object.prototype.hasOwnProperty.call(CLOUDFLARE_WORKER_STUB_MODULES, p),
   ).map((p) => `--external:${p}`);
 
   execFileSync(

package/corpus/core/src/guards/db-tool-scoping.ts

@@ -103,7 +103,7 @@ export function scanDbToolScoping(options: DbToolScopingOptions): GuardResult {
     const tables = extractTableCalls(contents);
     for (const table of tables) {
       if (hasRawDbScope(table.body)) continue;
-      if (Object.hasOwn(denylist, table.sqlName)) {
+      if (Object.prototype.hasOwnProperty.call(denylist, table.sqlName)) {
         seenAllowed.add(table.sqlName);
         continue;
       }

package/corpus/core/src/integrations/adapters/slack.ts

@@ -45,6 +45,17 @@ const SLACK_IDENTITY_CACHE_TTL_MS = 10 * 60 * 1_000;
 // API blip must not fail-close a sender's identity (and DMs) for 10 minutes.
 const SLACK_IDENTITY_NEGATIVE_CACHE_TTL_MS = 30 * 1_000;
 const SLACK_IDENTITY_CACHE_MAX_ENTRIES = 1_000;
+const SLACK_TOKEN_IDENTITY_CACHE_TTL_MS = 10 * 60 * 1_000;
+const SLACK_TOKEN_IDENTITY_NEGATIVE_CACHE_TTL_MS = 30 * 1_000;
+
+type SlackTokenIdentity = {
+  teamId: string | null;
+  appId: string | null;
+  valid: boolean;
+  expiresAt: number;
+};
+
+const slackTokenIdentityCache = new Map<string, SlackTokenIdentity>();
 
 interface SlackUserIdentity {
   email: string | null;
@@ -116,8 +127,7 @@ export function slackAdapter(
 ): PlatformAdapter {
   const resolveBotToken = async (incoming: IncomingMessage) =>
     (await options.resolveBotToken?.(incoming)) ??
-    (await resolveManagedSlackBotToken(incoming)) ??
-    (await resolveSecret("SLACK_BOT_TOKEN")) ??
+    (await resolveSlackBotTokenForIncoming(incoming)) ??
     undefined;
 
   return {
@@ -713,6 +723,19 @@ function parseAllowlistEnv(name: string): Set<string> | null {
   return new Set(values);
 }
 
+export async function resolveSlackBotTokenForIncoming(
+  incoming: IncomingMessage,
+): Promise<string | undefined> {
+  const managedToken = await resolveManagedSlackBotToken(incoming);
+  if (managedToken) return managedToken;
+
+  const legacyToken = await resolveSecret("SLACK_BOT_TOKEN");
+  if (!legacyToken) return undefined;
+  return (await isSlackTokenForIncoming(legacyToken, incoming))
+    ? legacyToken
+    : undefined;
+}
+
 async function resolveManagedSlackBotToken(
   incoming: IncomingMessage,
 ): Promise<string | undefined> {
@@ -736,13 +759,13 @@ async function resolveManagedSlackBotToken(
           slackInstallationKey({ teamId, enterpriseId, apiAppId }),
         )
       : null;
-    if (!installation && teamId) {
+    if (!installation && !apiAppId && teamId) {
       installation = await getActiveIntegrationInstallationForTenant(
         "slack",
         teamId,
       );
     }
-    if (!installation && enterpriseId) {
+    if (!installation && !apiAppId && enterpriseId) {
       installation = await getActiveIntegrationInstallationForTenant(
         "slack",
         enterpriseId,
@@ -757,6 +780,62 @@ async function resolveManagedSlackBotToken(
   }
 }
 
+async function isSlackTokenForIncoming(
+  token: string,
+  incoming: IncomingMessage,
+): Promise<boolean> {
+  const teamId = slackIdentityValue(incoming.platformContext.teamId);
+  const apiAppId = slackIdentityValue(incoming.platformContext.apiAppId);
+  if (!teamId && !apiAppId) return true;
+
+  const cached = slackTokenIdentityCache.get(token);
+  if (cached && cached.expiresAt > Date.now()) {
+    return (
+      cached.valid &&
+      (!teamId || cached.teamId === teamId) &&
+      (!apiAppId || cached.appId === apiAppId)
+    );
+  }
+
+  const auth = await slackJson(token, "auth.test", {});
+  const authTeamId = slackIdentityValue(auth?.team_id);
+  const botId = slackIdentityValue(auth?.bot_id);
+  let appId: string | null = null;
+  let valid = !!auth;
+
+  if (valid && apiAppId) {
+    const bot = botId
+      ? await slackJson(token, "bots.info", { bot: botId })
+      : null;
+    appId = slackIdentityValue(bot?.bot?.app_id);
+    valid = !!appId;
+  }
+
+  const identity: SlackTokenIdentity = {
+    teamId: authTeamId,
+    appId,
+    valid,
+    expiresAt:
+      Date.now() +
+      (valid
+        ? SLACK_TOKEN_IDENTITY_CACHE_TTL_MS
+        : SLACK_TOKEN_IDENTITY_NEGATIVE_CACHE_TTL_MS),
+  };
+  slackTokenIdentityCache.set(token, identity);
+
+  return (
+    valid &&
+    (!teamId || identity.teamId === teamId) &&
+    (!apiAppId || identity.appId === apiAppId)
+  );
+}
+
+function slackIdentityValue(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized && normalized !== "unknown" ? normalized : null;
+}
+
 let _missingAllowlistWarned = false;
 
 /**
@@ -1079,7 +1158,7 @@ async function resolveSlackThreadPermalink(
   if (typeof channelId !== "string" || typeof threadTs !== "string") {
     return undefined;
   }
-  const token = resolvedToken ?? (await resolveSecret("SLACK_BOT_TOKEN"));
+  const token = resolvedToken;
   if (!token) return undefined;
 
   try {

package/corpus/core/src/integrations/index.ts

@@ -114,7 +114,11 @@ export type {
 } from "./remote-types.js";
 
 // Adapters
-export { slackAdapter, type SlackAdapterOptions } from "./adapters/slack.js";
+export {
+  resolveSlackBotTokenForIncoming,
+  slackAdapter,
+  type SlackAdapterOptions,
+} from "./adapters/slack.js";
 export { telegramAdapter } from "./adapters/telegram.js";
 export { whatsappAdapter } from "./adapters/whatsapp.js";
 export { discordAdapter } from "./adapters/discord.js";

package/corpus/core/src/localization/default-messages.ts

@@ -32,6 +32,10 @@ const messages = {
     openTeamSettings: "Open team settings",
     openResourceSettings: "Open resource settings",
     backHome: "Back to home",
+    mcpConnectionsTitle: "MCP connections",
+    mcpConnectionsDescription:
+      "Connect remote MCP servers so the agent can use their tools.",
+    openMcpConnections: "Manage MCP connections",
     profileTitle: "Account",
     profileDescription: "Your name, profile photo, and signed-in identity.",
     profileLoading: "Loading...",
@@ -332,6 +336,7 @@ const messages = {
     addOwnKeys: "Add your own keys",
     configureProviderKeys: "Configure Anthropic, OpenAI, or another provider",
     checkingAiConnection: "Checking AI connection...",
+    connectionUnavailable: "Unable to check AI connection. Click to retry.",
     voiceMode: {
       entryButtonLabel: "Use microphone",
       promptTitle: "Use your voice",
@@ -801,7 +806,7 @@ const messages = {
     connected: "Connected",
     configure: "Configure",
     connect: "Connect",
-    connectWithOAuth: "Connect with OAuth",
+    connectWithOAuth: "Connect",
     useApiToken: "Use API token",
     connectSuggestion: "Connect {{name}} to use it in chat",
     connectSuggestionWithApiToken:

package/corpus/core/src/mcp-client/oauth-routes.ts

@@ -4,10 +4,11 @@ import type { OAuthClientInformationMixed } from "@modelcontextprotocol/sdk/shar
 import {
   deleteCookie,
   defineEventHandler,
+  getChunkedCookie,
   getCookie,
   getMethod,
   getQuery,
-  setCookie,
+  setChunkedCookie,
   setResponseStatus,
   type H3Event,
 } from "h3";
@@ -32,6 +33,9 @@ import {
 
 const FLOW_COOKIE = "an_mcp_oauth_flow";
 const FLOW_TTL_SECONDS = 10 * 60;
+const FLOW_COOKIE_CHUNK_SIZE = 2_800;
+const FLOW_COOKIE_MAX_CHUNKS = 8;
+const CHUNKED_COOKIE_PREFIX = "__chunked__";
 
 export interface McpOAuthFlow {
   name: string;
@@ -54,6 +58,20 @@ export interface McpOAuthRoutesOptions {
   reconfigure: () => Promise<void>;
 }
 
+export function redirectWithStagedCookies(
+  event: H3Event,
+  location: string,
+): Response {
+  const headers = new Headers({
+    Location: location,
+    "Cache-Control": "no-store",
+  });
+  for (const cookie of event.res?.headers?.getSetCookie?.() ?? []) {
+    headers.append("set-cookie", cookie);
+  }
+  return new Response(null, { status: 302, headers });
+}
+
 export function mountMcpOAuthRoutes(
   nitroApp: any,
   options: McpOAuthRoutesOptions,
@@ -175,14 +193,8 @@ async function handleMcpOAuthStart(
       ...(safeReturnUrl ? { returnUrl: safeReturnUrl } : {}),
       expiresAt: Date.now() + FLOW_TTL_SECONDS * 1_000,
     };
-    setCookie(event, FLOW_COOKIE, encryptSecretValue(JSON.stringify(flow)), {
-      httpOnly: true,
-      secure: redirectUri.startsWith("https://"),
-      sameSite: "lax",
-      path: "/",
-      maxAge: FLOW_TTL_SECONDS,
-    });
-    return Response.redirect(started.authorizationUrl.href, 302);
+    setMcpOAuthFlowCookie(event, flow, redirectUri.startsWith("https://"));
+    return redirectWithStagedCookies(event, started.authorizationUrl.href);
   } catch {
     setResponseStatus(event, 400);
     return {
@@ -203,8 +215,8 @@ async function handleMcpOAuthCallback(
   const code = text(query.code);
   const state = text(query.state);
   const providerError = text(query.error);
-  const flow = readFlow(event);
-  deleteCookie(event, FLOW_COOKIE, { path: "/" });
+  const flow = readMcpOAuthFlowCookie(event);
+  clearMcpOAuthFlowCookies(event);
   if (providerError || !code || !state) {
     setResponseStatus(event, 400);
     return { error: "MCP OAuth authorization was not completed." };
@@ -254,15 +266,43 @@ async function handleMcpOAuthCallback(
     const returnPath =
       flow.returnUrl ??
       `/settings/connections?connected=mcp-${encodeURIComponent(flow.name)}`;
-    return Response.redirect(getAppUrl(event, returnPath), 302);
+    return redirectWithStagedCookies(event, getAppUrl(event, returnPath));
   } catch {
     setResponseStatus(event, 400);
     return { error: "MCP OAuth authorization could not be completed." };
   }
 }
 
-function readFlow(event: H3Event): McpOAuthFlow | null {
-  const encrypted = getCookie(event, FLOW_COOKIE);
+export function setMcpOAuthFlowCookie(
+  event: H3Event,
+  flow: McpOAuthFlow,
+  secure: boolean,
+): void {
+  const encrypted = encryptSecretValue(JSON.stringify(flow));
+  const chunkCount = Math.ceil(encrypted.length / FLOW_COOKIE_CHUNK_SIZE);
+  if (chunkCount > FLOW_COOKIE_MAX_CHUNKS) {
+    throw new Error("MCP OAuth flow state exceeds the cookie size limit.");
+  }
+  setChunkedCookie(event, FLOW_COOKIE, encrypted, {
+    httpOnly: true,
+    secure,
+    sameSite: "lax",
+    path: "/",
+    maxAge: FLOW_TTL_SECONDS,
+    chunkMaxLength: FLOW_COOKIE_CHUNK_SIZE,
+  });
+}
+
+export function readMcpOAuthFlowCookie(event: H3Event): McpOAuthFlow | null {
+  const primaryCookie = getCookie(event, FLOW_COOKIE);
+  if (!primaryCookie) return null;
+  if (primaryCookie.startsWith(CHUNKED_COOKIE_PREFIX)) {
+    const rawCount = primaryCookie.slice(CHUNKED_COOKIE_PREFIX.length);
+    if (!/^\d+$/.test(rawCount)) return null;
+    const chunkCount = Number(rawCount);
+    if (chunkCount < 2 || chunkCount > FLOW_COOKIE_MAX_CHUNKS) return null;
+  }
+  const encrypted = getChunkedCookie(event, FLOW_COOKIE);
   if (!encrypted) return null;
   try {
     const parsed = JSON.parse(decryptSecretValue(encrypted)) as McpOAuthFlow;
@@ -272,6 +312,13 @@ function readFlow(event: H3Event): McpOAuthFlow | null {
   }
 }
 
+export function clearMcpOAuthFlowCookies(event: H3Event): void {
+  deleteCookie(event, FLOW_COOKIE, { path: "/" });
+  for (let index = 1; index <= FLOW_COOKIE_MAX_CHUNKS; index += 1) {
+    deleteCookie(event, `${FLOW_COOKIE}.${index}`, { path: "/" });
+  }
+}
+
 export function isValidMcpOAuthFlow(
   flow: McpOAuthFlow,
   email: string,