@mcpstack/agent-sdk 1.0.0-pr.16.7572c080abaa.13.1

package/dist/react/index.mjs

@@ -0,0 +1,4700 @@
+// src/react-app/index.tsx
+import { createContext, useContext, useEffect as useEffect3, useMemo as useMemo3, useRef as useRef3 } from "react";
+
+// src/framework/useAppAgentBinding.tsx
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore
+} from "react";
+
+// src/core/sse-client.ts
+function* parseEventBlocks(input) {
+  const normalized = input.replace(/\r\n/g, "\n");
+  const eventBlocks = normalized.split("\n\n");
+  for (const eventBlock of eventBlocks) {
+    if (!eventBlock.trim()) continue;
+    let eventType = "";
+    const dataLines = [];
+    for (const line of eventBlock.split("\n")) {
+      if (line.startsWith("event: ")) {
+        eventType = line.slice("event: ".length);
+      } else if (line.startsWith("data: ")) {
+        dataLines.push(line.slice("data: ".length));
+      } else if (line === "data:") {
+        dataLines.push("");
+      }
+    }
+    if (!eventType || dataLines.length === 0) {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(dataLines.join("\n"));
+      yield { type: eventType, data: parsed };
+    } catch {
+    }
+  }
+}
+async function* parseSseStream(response, signal) {
+  const reader = response.body?.getReader();
+  if (!reader) {
+    const text = await response.text().catch(() => "");
+    yield* parseEventBlocks(text);
+    return;
+  }
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      if (signal?.aborted) break;
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const normalized = buffer.replace(/\r\n/g, "\n");
+      const events = normalized.split("\n\n");
+      buffer = events.pop() ?? "";
+      for (const eventBlock of events) {
+        yield* parseEventBlocks(eventBlock);
+      }
+    }
+    if (buffer.trim()) {
+      yield* parseEventBlocks(buffer);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/core/auth/registration.ts
+var REGISTRATION_STORAGE_PREFIX = "mcpstack_oauth_registration_";
+function getStorage(storage) {
+  if (storage) {
+    return storage;
+  }
+  try {
+    return typeof localStorage === "undefined" ? null : localStorage;
+  } catch {
+    return null;
+  }
+}
+function encodeCacheKey(raw) {
+  return btoa(raw).replace(/[^a-zA-Z0-9]/g, "");
+}
+function getPreferredRegistrationPreference(authConfig) {
+  return authConfig?.registrationPreference ?? "auto";
+}
+function getEffectiveCallbackUrl(authConfig, fallbackCallbackUrl) {
+  const configuredCallbackUrl = authConfig?.callbackUrl?.trim();
+  if (!configuredCallbackUrl) {
+    return fallbackCallbackUrl;
+  }
+  if (isNativeCallbackUrl(fallbackCallbackUrl) && !isNativeCallbackUrl(configuredCallbackUrl)) {
+    return fallbackCallbackUrl;
+  }
+  return configuredCallbackUrl;
+}
+function buildRegistrationCacheKey(authConfig, callbackUrl, requestedMode) {
+  const raw = [
+    authConfig.authorizationServerUrl ?? "",
+    authConfig.authorizationServerMetadataUrl ?? "",
+    authConfig.resource ?? "",
+    callbackUrl,
+    requestedMode
+  ].join("|");
+  return encodeCacheKey(raw);
+}
+function buildTokenCacheKey(authConfig, mcpServerUrl) {
+  if (!authConfig) {
+    return encodeCacheKey(`legacy|${mcpServerUrl}`);
+  }
+  const callbackUrl = authConfig.callbackUrl ?? "";
+  const clientMode = authConfig.clientMode ?? "manual";
+  const raw = [
+    authConfig.authorizationServerUrl ?? mcpServerUrl,
+    authConfig.resource ?? "",
+    callbackUrl,
+    clientMode
+  ].join("|");
+  return encodeCacheKey(raw);
+}
+function loadStoredRegistration(cacheKey, storage) {
+  const targetStorage = getStorage(storage);
+  if (!targetStorage) return null;
+  try {
+    const raw = targetStorage.getItem(`${REGISTRATION_STORAGE_PREFIX}${cacheKey}`);
+    if (!raw) return null;
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function saveStoredRegistration(registration, storage) {
+  const targetStorage = getStorage(storage);
+  if (!targetStorage) return;
+  try {
+    targetStorage.setItem(
+      `${REGISTRATION_STORAGE_PREFIX}${registration.key}`,
+      JSON.stringify(registration)
+    );
+  } catch {
+  }
+}
+function clearStoredRegistration(cacheKey, storage) {
+  const targetStorage = getStorage(storage);
+  if (!targetStorage) return;
+  try {
+    targetStorage.removeItem(`${REGISTRATION_STORAGE_PREFIX}${cacheKey}`);
+  } catch {
+  }
+}
+function applyResolvedRegistration(authConfig, registration) {
+  return {
+    ...authConfig,
+    callbackUrl: registration.callbackUrl,
+    clientId: registration.clientId ?? authConfig.clientId,
+    clientMode: registration.mode,
+    resource: registration.resource ?? authConfig.resource,
+    authorizationServerUrl: registration.authorizationServerUrl ?? authConfig.authorizationServerUrl,
+    authorizationServerMetadataUrl: registration.authorizationServerMetadataUrl ?? authConfig.authorizationServerMetadataUrl,
+    registrationEndpoint: registration.registrationEndpoint ?? authConfig.registrationEndpoint
+  };
+}
+function createResolvedRegistration(authConfig, mode, callbackUrl, clientId, clientMetadataUrl) {
+  return {
+    cacheKey: buildRegistrationCacheKey(authConfig, callbackUrl, mode),
+    mode,
+    clientId,
+    callbackUrl,
+    resource: authConfig.resource,
+    authorizationServerUrl: authConfig.authorizationServerUrl,
+    authorizationServerMetadataUrl: authConfig.authorizationServerMetadataUrl,
+    registrationEndpoint: authConfig.registrationEndpoint,
+    clientMetadataUrl
+  };
+}
+function shouldAttemptMode(preferred, candidate) {
+  return preferred === "auto" || preferred === candidate;
+}
+function isLoopbackHost(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+}
+function isNativeCallbackUrl(callbackUrl) {
+  try {
+    const url = new URL(callbackUrl);
+    return url.protocol !== "http:" && url.protocol !== "https:";
+  } catch {
+    return !callbackUrl.startsWith("http://") && !callbackUrl.startsWith("https://");
+  }
+}
+function inferApplicationType(callbackUrl) {
+  try {
+    const url = new URL(callbackUrl);
+    if (url.protocol === "http:" || url.protocol === "https:") {
+      return isLoopbackHost(url.hostname) ? "native" : "web";
+    }
+    return "native";
+  } catch {
+    return "native";
+  }
+}
+async function registerPublicClient(authConfig, options) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const callbackUrl = options.callbackUrl;
+  const registration = createResolvedRegistration(authConfig, "dcr", callbackUrl);
+  if (!authConfig.registrationEndpoint) {
+    throw new Error("Dynamic client registration is not available for this server.");
+  }
+  const existing = loadStoredRegistration(registration.cacheKey, options.storage);
+  if (existing?.clientId) {
+    return {
+      ...registration,
+      clientId: existing.clientId
+    };
+  }
+  const requestBody = {
+    client_name: options.clientName ?? "MCP Stack MCP Client",
+    application_type: inferApplicationType(callbackUrl),
+    redirect_uris: [callbackUrl],
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    token_endpoint_auth_method: "none",
+    scope: authConfig.scopes?.join(" "),
+    client_uri: options.clientUri
+  };
+  const response = await fetchImpl(authConfig.registrationEndpoint, {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(requestBody)
+  });
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => "Dynamic client registration failed.");
+    throw new Error(`Dynamic client registration failed (${response.status}): ${errorText}`);
+  }
+  const payload = await response.json();
+  if (!payload.client_id) {
+    throw new Error("Dynamic client registration response did not include a client_id.");
+  }
+  saveStoredRegistration({
+    key: registration.cacheKey,
+    mode: "dcr",
+    authorizationServerUrl: authConfig.authorizationServerUrl ?? "",
+    authorizationServerMetadataUrl: authConfig.authorizationServerMetadataUrl,
+    registrationEndpoint: authConfig.registrationEndpoint,
+    clientId: payload.client_id,
+    callbackUrl,
+    resource: authConfig.resource,
+    createdAt: Date.now(),
+    updatedAt: Date.now()
+  }, options.storage);
+  return {
+    ...registration,
+    clientId: payload.client_id
+  };
+}
+async function resolveOAuthRegistration(authConfig, options) {
+  const callbackUrl = getEffectiveCallbackUrl(authConfig, options.callbackUrl);
+  const preferred = getPreferredRegistrationPreference(authConfig);
+  const preregClientId = authConfig.clientId?.trim();
+  if (preregClientId && shouldAttemptMode(preferred, "preregistered")) {
+    return createResolvedRegistration(
+      authConfig,
+      "preregistered",
+      callbackUrl,
+      preregClientId
+    );
+  }
+  if (authConfig.clientIdMetadataDocumentSupported && options.oauthClientMetadataUrl && shouldAttemptMode(preferred, "cimd")) {
+    return createResolvedRegistration(
+      authConfig,
+      "cimd",
+      callbackUrl,
+      options.oauthClientMetadataUrl,
+      options.oauthClientMetadataUrl
+    );
+  }
+  if (authConfig.registrationEndpoint && shouldAttemptMode(preferred, "dcr")) {
+    return registerPublicClient(authConfig, {
+      ...options,
+      callbackUrl
+    });
+  }
+  return createResolvedRegistration(
+    authConfig,
+    preregClientId ? "preregistered" : "manual",
+    callbackUrl,
+    preregClientId
+  );
+}
+
+// src/core/auth-storage.ts
+var LEGACY_OAUTH_TOKEN_STORAGE_PREFIX = "mcpstack_oauth_";
+var SCOPED_OAUTH_TOKEN_STORAGE_PREFIX = "mcpstack_oauth_session_";
+function hashAuthSessionKey(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36);
+}
+function normalizeAuthSessionKey(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const normalized = value.trim();
+  return normalized || null;
+}
+function resolveExplicitAuthSessionKey(config) {
+  return normalizeAuthSessionKey(config.authSessionKey);
+}
+function buildScopedOAuthTokenStoragePrefix(authSessionKey) {
+  const normalizedSessionKey = normalizeAuthSessionKey(authSessionKey);
+  if (!normalizedSessionKey) {
+    return LEGACY_OAUTH_TOKEN_STORAGE_PREFIX;
+  }
+  return `${SCOPED_OAUTH_TOKEN_STORAGE_PREFIX}${hashAuthSessionKey(normalizedSessionKey)}_`;
+}
+function buildScopedOAuthTokenStorageKey(cacheKey, authSessionKey) {
+  return `${buildScopedOAuthTokenStoragePrefix(authSessionKey)}${cacheKey}`;
+}
+
+// src/core/EmcyAgent.ts
+var DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
+var DEFAULT_LOCAL_PUBLIC_APP_PORT = "3100";
+var DEFAULT_OAUTH_CALLBACK_URL = "https://mcpstack.com/oauth/callback";
+var DEFAULT_OAUTH_CLIENT_METADATA_URL = "https://mcpstack.com/.well-known/oauth-client-metadata.json";
+var DEFAULT_AUDIO_TURN_DETECTION = {
+  enabled: true,
+  autoSubmit: true,
+  silenceDurationMs: 850,
+  minSpeechDurationMs: 180,
+  noSpeechTimeoutMs: 12e3,
+  speechThreshold: 0.012,
+  noiseMultiplier: 2.4
+};
+var AUDIO_ACTIVITY_EMIT_INTERVAL_MS = 120;
+var MIN_AUDIO_LEVEL_DELTA_FOR_STATE = 0.03;
+function isLocalhostHost(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+function getDefaultOAuthHelperOrigin(agentServiceUrl) {
+  if (!agentServiceUrl) {
+    return DEFAULT_OAUTH_CALLBACK_URL.replace(/\/oauth\/callback$/, "");
+  }
+  try {
+    const url = new URL(agentServiceUrl);
+    if (isLocalhostHost(url.hostname)) {
+      return `${url.protocol}//${url.hostname}:${DEFAULT_LOCAL_PUBLIC_APP_PORT}`;
+    }
+  } catch {
+  }
+  return DEFAULT_OAUTH_CALLBACK_URL.replace(/\/oauth\/callback$/, "");
+}
+function getDefaultOAuthCallbackUrl(agentServiceUrl) {
+  return `${getDefaultOAuthHelperOrigin(agentServiceUrl)}/oauth/callback`;
+}
+function getDefaultOAuthClientMetadataUrl(agentServiceUrl) {
+  return `${getDefaultOAuthHelperOrigin(agentServiceUrl)}/.well-known/oauth-client-metadata.json`;
+}
+function buildEmbeddedExchangeUrl(mcpServerUrl) {
+  const url = new URL(mcpServerUrl);
+  if (/\/mcp\/?$/i.test(url.pathname)) {
+    url.pathname = url.pathname.replace(/\/mcp\/?$/i, "/embedded/exchange");
+  } else {
+    url.pathname = `${url.pathname.replace(/\/$/, "")}/embedded/exchange`;
+  }
+  return url.toString();
+}
+function normalizeOAuthTokenResponse(payload, authConfig) {
+  const accessToken = typeof payload.accessToken === "string" ? payload.accessToken : typeof payload.access_token === "string" ? payload.access_token : "";
+  if (!accessToken) {
+    return void 0;
+  }
+  return {
+    accessToken,
+    refreshToken: typeof payload.refreshToken === "string" ? payload.refreshToken : typeof payload.refresh_token === "string" ? payload.refresh_token : void 0,
+    expiresIn: typeof payload.expiresIn === "number" ? payload.expiresIn : typeof payload.expires_in === "number" ? payload.expires_in : void 0,
+    tokenType: typeof payload.tokenType === "string" ? payload.tokenType : typeof payload.token_type === "string" ? payload.token_type : "Bearer",
+    resolvedAuthConfig: authConfig
+  };
+}
+function createAppTokenAuthHandler(agentId, auth) {
+  return async (mcpServerUrl, authConfig) => {
+    const appToken = await auth.getToken();
+    const trimmedToken = appToken?.trim();
+    if (!trimmedToken) {
+      return void 0;
+    }
+    const headers = {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${trimmedToken}`
+    };
+    if (auth.appId?.trim()) {
+      headers["x-mcpstack-embedded-app-id"] = auth.appId.trim();
+    }
+    const body = {
+      agentId,
+      resource: authConfig.resource ?? mcpServerUrl,
+      scopes: authConfig.scopes
+    };
+    if (auth.appId?.trim()) {
+      body.appId = auth.appId.trim();
+    }
+    const response = await fetch(buildEmbeddedExchangeUrl(mcpServerUrl), {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+      const description = typeof payload?.error_description === "string" ? payload.error_description : typeof payload?.error === "string" ? payload.error : `App token exchange failed (${response.status}).`;
+      throw new Error(description);
+    }
+    return normalizeOAuthTokenResponse(payload ?? {}, authConfig);
+  };
+}
+function extractErrorMessage(payload) {
+  if (typeof payload === "string") {
+    const message = payload.trim();
+    return message || null;
+  }
+  if (!payload || typeof payload !== "object") {
+    return null;
+  }
+  const record = payload;
+  for (const key of ["error", "message", "detail"]) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+async function getResponseErrorMessage(response) {
+  const fallback = `HTTP ${response.status}`;
+  try {
+    const payload = await response.clone().json();
+    const message = extractErrorMessage(payload);
+    if (message) {
+      return message;
+    }
+  } catch {
+  }
+  const text = await response.text().catch(() => "");
+  return text.trim() || fallback;
+}
+function parameterToJsonSchema(parameter) {
+  const schema = {
+    type: parameter.type
+  };
+  if (parameter.description) {
+    schema.description = parameter.description;
+  }
+  if (parameter.enum) {
+    schema.enum = parameter.enum;
+  }
+  if (parameter.type === "array") {
+    schema.items = parameter.items ? parameterToJsonSchema(parameter.items) : { type: "string" };
+  }
+  if (parameter.type === "object" && parameter.properties) {
+    const properties = {};
+    const required = [];
+    for (const [key, child] of Object.entries(parameter.properties)) {
+      properties[key] = parameterToJsonSchema(child);
+      if (child.required) required.push(key);
+    }
+    schema.properties = properties;
+    schema.required = required;
+  }
+  if (parameter.additionalProperties !== void 0) {
+    schema.additionalProperties = typeof parameter.additionalProperties === "boolean" ? parameter.additionalProperties : parameterToJsonSchema(parameter.additionalProperties);
+  }
+  return schema;
+}
+function parametersToJsonSchema(params) {
+  const properties = {};
+  const required = [];
+  for (const [key, p] of Object.entries(params)) {
+    properties[key] = parameterToJsonSchema(p);
+    if (p.required) required.push(key);
+  }
+  return { type: "object", properties, required };
+}
+var McpStackAgent = class {
+  constructor(config) {
+    this.agentConfig = null;
+    this.budgetSnapshot = null;
+    this.conversationId = null;
+    this.messages = [];
+    this.historyCursor = null;
+    this.hasOlderMessages = false;
+    this.isLoadingHistory = false;
+    this.abortController = null;
+    this.isLoading = false;
+    this.listeners = /* @__PURE__ */ new Map();
+    /** Per-server MCP session tracking */
+    this.mcpSessions = /* @__PURE__ */ new Map();
+    /** OAuth tokens per MCP server URL (standalone mode only) */
+    this.oauthTokens = /* @__PURE__ */ new Map();
+    /** Servers explicitly disconnected by the user and awaiting manual re-auth */
+    this.manuallySignedOutServers = /* @__PURE__ */ new Set();
+    this.audioState = {
+      status: "idle",
+      isSupported: false,
+      isEnabled: false,
+      transcript: "",
+      partialTranscript: "",
+      error: null
+    };
+    this.audioStream = null;
+    this.audioContext = null;
+    this.audioSource = null;
+    this.audioProcessor = null;
+    this.audioSilentGain = null;
+    this.audioSocket = null;
+    this.audioSessionTimer = null;
+    this.audioSessionStopRequested = false;
+    this.audioFinalTranscript = "";
+    this.audioTurnState = null;
+    const appTokenAuthHandler = config.auth?.mode === "app-token" ? createAppTokenAuthHandler(config.agentId, config.auth) : void 0;
+    this.config = {
+      ...config,
+      agentServiceUrl: config.agentServiceUrl ?? "https://api.mcpstack.com",
+      oauthCallbackUrl: config.oauthCallbackUrl ?? getDefaultOAuthCallbackUrl(config.agentServiceUrl),
+      oauthClientMetadataUrl: config.oauthClientMetadataUrl ?? getDefaultOAuthClientMetadataUrl(config.agentServiceUrl),
+      onAuthRequired: config.onAuthRequired ?? appTokenAuthHandler
+    };
+    this.audioState = this.buildAudioState({ status: "idle" });
+  }
+  async resolveAuthToken() {
+    if (this.config.getAuthToken) {
+      const token = await this.config.getAuthToken();
+      if (token) return token;
+    }
+    return this.config.apiKey;
+  }
+  /** Initialize: fetch agent config (tools, widget settings, MCP servers) */
+  async init() {
+    const token = await this.resolveAuthToken();
+    const response = await fetch(
+      `${this.config.agentServiceUrl}/api/v1/agents/${this.config.agentId}/config`,
+      {
+        headers: {
+          Authorization: `Bearer ${token}`
+        }
+      }
+    );
+    if (!response.ok) {
+      throw new Error(await getResponseErrorMessage(response));
+    }
+    this.agentConfig = await response.json();
+    this.audioState = this.buildAudioState({ status: "idle" });
+    this.emit("audio_state", this.audioState);
+    await this.refreshBudgetSnapshot().catch(() => void 0);
+    if (this.agentConfig?.mcpServers?.length) {
+      await Promise.all(
+        this.agentConfig.mcpServers.map(async (server) => {
+          server.authConfig = await this.resolveServerAuthConfig(server.url, server.authConfig ?? null);
+        })
+      );
+    }
+    if (this.agentConfig?.mcpServers) {
+      for (const server of this.agentConfig.mcpServers) {
+        if (!this.mcpSessions.has(server.url)) {
+          let authStatus;
+          if (server.authConfig?.authType === "oauth2") {
+            authStatus = server.authStatus === "connected" || this.hasValidOAuthToken(server.url) ? "connected" : "needs_auth";
+          } else {
+            authStatus = server.authStatus || "connected";
+          }
+          this.mcpSessions.set(server.url, { sessionId: null, authStatus });
+        }
+      }
+    }
+    if (this.config.initialConversationId) {
+      await this.loadConversation(this.config.initialConversationId);
+    }
+    return this.agentConfig;
+  }
+  /** Get current MCP server auth statuses */
+  getMcpServers() {
+    if (!this.agentConfig?.mcpServers) return [];
+    return this.agentConfig.mcpServers.map((server) => ({
+      url: server.url,
+      name: server.name,
+      authStatus: this.mcpSessions.get(server.url)?.authStatus ?? server.authStatus ?? "connected",
+      canSignOut: (server.authConfig?.authType ?? "none") !== "none"
+    }));
+  }
+  /** Send a message and process the full orchestration loop (including tool calls) */
+  async sendMessage(message) {
+    if (!this.agentConfig) {
+      await this.init();
+    }
+    this.isLoading = true;
+    this.emit("loading", true);
+    const userMsg = {
+      id: crypto.randomUUID(),
+      role: "user",
+      content: message,
+      timestamp: /* @__PURE__ */ new Date()
+    };
+    this.messages.push(userMsg);
+    this.emit("message", userMsg);
+    try {
+      await this.runChatLoop(message);
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : "Unknown error";
+      this.emit("error", { code: "sdk_error", message: errorMsg });
+    } finally {
+      this.isLoading = false;
+      this.emit("loading", false);
+      this.emit("thinking", false);
+    }
+  }
+  /** Start a new conversation */
+  newConversation() {
+    this.conversationId = null;
+    this.messages = [];
+    this.historyCursor = null;
+    this.hasOlderMessages = false;
+    this.isLoadingHistory = false;
+  }
+  /** Cancel the current in-flight request */
+  cancel() {
+    this.abortController?.abort();
+    this.abortController = null;
+  }
+  /** Get all messages in the current conversation */
+  getMessages() {
+    return [...this.messages];
+  }
+  /** Get the current conversation ID */
+  getConversationId() {
+    return this.conversationId;
+  }
+  getHasOlderMessages() {
+    return this.hasOlderMessages;
+  }
+  getIsLoadingHistory() {
+    return this.isLoadingHistory;
+  }
+  /** Get the loaded agent config */
+  getAgentConfig() {
+    return this.agentConfig;
+  }
+  getAudioInputState() {
+    return { ...this.audioState };
+  }
+  async startVoiceInput() {
+    if (!this.agentConfig) {
+      await this.init();
+    }
+    if (!this.isAudioInputSupported()) {
+      this.setAudioState({
+        status: "error",
+        error: {
+          code: "unsupported_browser",
+          message: "Microphone input is not supported in this browser."
+        }
+      });
+      return;
+    }
+    if (!this.isAudioInputEnabled()) {
+      this.setAudioState({
+        status: "error",
+        error: {
+          code: "audio_not_enabled",
+          message: "Microphone input is not enabled for this agent."
+        }
+      });
+      return;
+    }
+    if (this.audioState.status === "requesting_permission" || this.audioState.status === "connecting" || this.audioState.status === "listening" || this.audioState.status === "transcribing") {
+      return;
+    }
+    this.audioSessionStopRequested = false;
+    this.audioFinalTranscript = "";
+    this.audioTurnState = null;
+    this.setAudioState({
+      status: "requesting_permission",
+      transcript: "",
+      partialTranscript: "",
+      error: null,
+      sessionId: null,
+      conversationId: this.conversationId,
+      inputLevel: 0,
+      isSpeaking: false,
+      speechMs: 0,
+      silenceMs: 0,
+      autoSubmitEnabled: this.getAudioTurnDetectionConfig().enabled && this.getAudioTurnDetectionConfig().autoSubmit
+    });
+    let stream = null;
+    try {
+      stream = await navigator.mediaDevices.getUserMedia({
+        audio: {
+          channelCount: 1,
+          echoCancellation: true,
+          noiseSuppression: true,
+          autoGainControl: true
+        }
+      });
+    } catch (error) {
+      this.setAudioState({
+        status: "error",
+        error: {
+          code: "microphone_permission_denied",
+          message: error instanceof Error ? error.message : "Microphone permission was denied."
+        }
+      });
+      return;
+    }
+    try {
+      this.audioStream = stream;
+      this.setAudioState({ status: "connecting" });
+      const session = await this.createRealtimeTranscriptionSession();
+      this.conversationId = session.conversationId;
+      this.setAudioState({
+        sessionId: session.sessionId,
+        conversationId: session.conversationId,
+        maxSessionSeconds: session.maxSessionSeconds
+      });
+      const socket = await this.openAudioSocket(session.webSocketUrl);
+      this.audioSocket = socket;
+      this.bindAudioSocket(socket);
+      await this.startAudioCapture(stream, socket);
+      const maxSessionMs = Math.max(1, session.maxSessionSeconds) * 1e3;
+      this.audioSessionTimer = setTimeout(() => {
+        void this.commitVoiceInput();
+      }, maxSessionMs);
+      this.setAudioState({ status: "listening" });
+    } catch (error) {
+      this.cleanupAudioCapture();
+      this.setAudioState({
+        status: "error",
+        error: {
+          code: this.extractErrorCode(error) ?? "audio_start_failed",
+          message: error instanceof Error ? error.message : "Could not start microphone input."
+        }
+      });
+    }
+  }
+  async stopVoiceInput() {
+    await this.commitVoiceInput();
+  }
+  cancelVoiceInput() {
+    this.audioSessionStopRequested = true;
+    this.cleanupAudioCapture();
+    this.audioTurnState = null;
+    this.setAudioState({
+      status: "idle",
+      transcript: "",
+      partialTranscript: "",
+      error: null,
+      sessionId: null,
+      inputLevel: 0,
+      isSpeaking: false,
+      speechMs: 0,
+      silenceMs: 0
+    });
+  }
+  async loadConversation(conversationId, pageSize = this.config.conversationHistoryPageSize ?? 50) {
+    this.isLoadingHistory = true;
+    try {
+      const page = await this.fetchConversationMessages(conversationId, void 0, pageSize);
+      this.applyConversationPage(page, false);
+      return page;
+    } finally {
+      this.isLoadingHistory = false;
+    }
+  }
+  async loadOlderMessages(pageSize = this.config.conversationHistoryPageSize ?? 50) {
+    if (!this.conversationId || !this.historyCursor || !this.hasOlderMessages) {
+      return null;
+    }
+    this.isLoadingHistory = true;
+    try {
+      const page = await this.fetchConversationMessages(this.conversationId, this.historyCursor, pageSize);
+      this.applyConversationPage(page, true);
+      return page;
+    } finally {
+      this.isLoadingHistory = false;
+    }
+  }
+  async submitFeedback(input) {
+    if (!this.conversationId) {
+      throw new Error("No active conversation to rate.");
+    }
+    const token = await this.resolveAuthToken();
+    const response = await fetch(
+      `${this.config.agentServiceUrl}/api/v1/chat/conversations/${encodeURIComponent(this.conversationId)}/feedback`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`
+        },
+        body: JSON.stringify(input)
+      }
+    );
+    if (!response.ok) {
+      throw new Error(await getResponseErrorMessage(response));
+    }
+    return await response.json();
+  }
+  /** Convert client tools to the API schema format. */
+  clientToolsToSchemas() {
+    if (!this.config.clientTools) return [];
+    return Object.entries(this.config.clientTools).map(([name, def]) => ({
+      name,
+      description: def.description,
+      inputSchema: parametersToJsonSchema(def.parameters),
+      selection: def.selection
+    }));
+  }
+  resolveExternalUserId() {
+    const hostIdentity = this.config.embeddedAuth?.hostIdentity;
+    return this.config.externalUserId ?? hostIdentity?.subject ?? hostIdentity?.email ?? void 0;
+  }
+  buildExternalUserContext() {
+    const hostIdentity = this.config.embeddedAuth?.hostIdentity;
+    const id = this.resolveExternalUserId();
+    const externalUser = {};
+    if (id) externalUser.id = id;
+    if (hostIdentity?.email) externalUser.email = hostIdentity.email;
+    if (hostIdentity?.displayName) externalUser.displayName = hostIdentity.displayName;
+    if (hostIdentity?.avatarUrl) externalUser.avatarUrl = hostIdentity.avatarUrl;
+    if (hostIdentity?.organizationId) externalUser.organizationId = hostIdentity.organizationId;
+    return Object.keys(externalUser).length > 0 ? externalUser : void 0;
+  }
+  /** Latest runtime budget snapshot for the current SDK identity. */
+  getBudgetSnapshot() {
+    return this.budgetSnapshot;
+  }
+  /** Refresh the current SDK identity's budget snapshot from the API. */
+  async refreshBudgetSnapshot() {
+    const token = await this.resolveAuthToken();
+    const params = new URLSearchParams();
+    const externalUserId = this.resolveExternalUserId();
+    if (externalUserId) {
+      params.set("externalUserId", externalUserId);
+    }
+    const query = params.toString();
+    const response = await fetch(
+      `${this.config.agentServiceUrl}/api/v1/agents/${this.config.agentId}/budget${query ? `?${query}` : ""}`,
+      {
+        headers: {
+          Authorization: `Bearer ${token}`
+        }
+      }
+    );
+    if (!response.ok) {
+      throw new Error(await getResponseErrorMessage(response));
+    }
+    this.budgetSnapshot = await response.json();
+    this.emit("budget_snapshot", this.budgetSnapshot);
+    return this.budgetSnapshot;
+  }
+  /** Whether a request is currently in flight */
+  getIsLoading() {
+    return this.isLoading;
+  }
+  /** Update the per-turn app context sent with each chat request. */
+  setAppContext(context) {
+    this.config = {
+      ...this.config,
+      context
+    };
+  }
+  /** Update the client tools exposed to the agent without recreating the session. */
+  setClientTools(clientTools) {
+    this.config = {
+      ...this.config,
+      clientTools
+    };
+  }
+  /**
+   * Proactively authenticate with an MCP server before sending a message.
+   * If a token response is provided directly, it is stored immediately.
+   * Otherwise, this uses the configured OAuth flow and verifies via MCP init.
+   *
+   * @param mcpServerUrl - The MCP server URL to authenticate with
+   * @param tokenResponse - Optional: provide token response directly (from OAuth popup)
+   */
+  async authenticate(mcpServerUrl, tokenResponse) {
+    const wasManuallySignedOut = this.manuallySignedOutServers.delete(mcpServerUrl);
+    try {
+      if (tokenResponse?.accessToken) {
+        if (tokenResponse.resolvedAuthConfig) {
+          this.updateServerAuthConfig(mcpServerUrl, tokenResponse.resolvedAuthConfig);
+        }
+        this.storeOAuthToken(mcpServerUrl, tokenResponse);
+        this.updateMcpAuthStatus(mcpServerUrl, "connected");
+        return true;
+      }
+      const token = await this.resolveToken(mcpServerUrl);
+      if (!token) {
+        if (wasManuallySignedOut) {
+          this.manuallySignedOutServers.add(mcpServerUrl);
+        }
+        return false;
+      }
+      this.updateMcpAuthStatus(mcpServerUrl, "connected");
+      try {
+        await this.initMcpSession(mcpServerUrl);
+        return true;
+      } catch {
+        return true;
+      }
+    } catch {
+      if (wasManuallySignedOut) {
+        this.manuallySignedOutServers.add(mcpServerUrl);
+      }
+      this.updateMcpAuthStatus(mcpServerUrl, "needs_auth");
+      return false;
+    }
+  }
+  /** Disconnect from an MCP server and require explicit re-authentication before reuse. */
+  async signOutMcpServer(mcpServerUrl) {
+    this.manuallySignedOutServers.add(mcpServerUrl);
+    await this.closeMcpSession(mcpServerUrl);
+    this.clearOAuthToken(mcpServerUrl);
+    this.updateMcpAuthStatus(mcpServerUrl, "needs_auth");
+  }
+  /** Get the auth config for an MCP server (from agent config) */
+  getServerAuthConfig(mcpServerUrl) {
+    const server = this.agentConfig?.mcpServers?.find((s) => s.url === mcpServerUrl);
+    return server?.authConfig ?? null;
+  }
+  getOAuthCallbackUrl() {
+    return this.config.oauthCallbackUrl ?? DEFAULT_OAUTH_CALLBACK_URL;
+  }
+  getOAuthClientMetadataUrl() {
+    return this.config.oauthClientMetadataUrl ?? DEFAULT_OAUTH_CLIENT_METADATA_URL;
+  }
+  getDefaultAuthRequiredHandler() {
+    return this.config.auth?.mode === "app-token" ? createAppTokenAuthHandler(this.config.agentId, this.config.auth) : void 0;
+  }
+  setOnAuthRequired(onAuthRequired) {
+    this.config = {
+      ...this.config,
+      onAuthRequired: onAuthRequired ?? this.getDefaultAuthRequiredHandler()
+    };
+  }
+  isAudioInputSupported() {
+    const audioContextCtor = this.getAudioContextConstructor();
+    return typeof navigator !== "undefined" && Boolean(navigator.mediaDevices?.getUserMedia) && typeof WebSocket !== "undefined" && Boolean(audioContextCtor) && typeof crypto !== "undefined";
+  }
+  isAudioInputEnabled() {
+    const capabilities = this.agentConfig?.modelConfig?.capabilities;
+    return Boolean(
+      this.agentConfig?.audio?.inputEnabled && (capabilities?.audioInput ?? capabilities?.realtimeAudioInput)
+    );
+  }
+  isAudioAutoSubmitEnabled() {
+    const turnDetection = this.getAudioTurnDetectionConfig();
+    return turnDetection.enabled && turnDetection.autoSubmit;
+  }
+  getAudioTurnDetectionConfig() {
+    const override = this.config.audioInput?.turnDetection ?? {};
+    return {
+      enabled: override.enabled ?? DEFAULT_AUDIO_TURN_DETECTION.enabled,
+      autoSubmit: override.autoSubmit ?? DEFAULT_AUDIO_TURN_DETECTION.autoSubmit,
+      silenceDurationMs: this.clampNumber(
+        override.silenceDurationMs,
+        250,
+        3e3,
+        DEFAULT_AUDIO_TURN_DETECTION.silenceDurationMs
+      ),
+      minSpeechDurationMs: this.clampNumber(
+        override.minSpeechDurationMs,
+        80,
+        1e3,
+        DEFAULT_AUDIO_TURN_DETECTION.minSpeechDurationMs
+      ),
+      noSpeechTimeoutMs: this.clampNumber(
+        override.noSpeechTimeoutMs,
+        0,
+        6e4,
+        DEFAULT_AUDIO_TURN_DETECTION.noSpeechTimeoutMs
+      ),
+      speechThreshold: this.clampNumber(
+        override.speechThreshold,
+        2e-3,
+        0.2,
+        DEFAULT_AUDIO_TURN_DETECTION.speechThreshold
+      ),
+      noiseMultiplier: this.clampNumber(
+        override.noiseMultiplier,
+        1.2,
+        8,
+        DEFAULT_AUDIO_TURN_DETECTION.noiseMultiplier
+      )
+    };
+  }
+  clampNumber(value, min, max, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      return fallback;
+    }
+    return Math.min(max, Math.max(min, value));
+  }
+  buildAudioState(patch) {
+    const hasPatch = (key) => Object.prototype.hasOwnProperty.call(patch, key);
+    return {
+      status: patch.status ?? this.audioState.status,
+      isSupported: this.isAudioInputSupported(),
+      isEnabled: this.isAudioInputEnabled(),
+      transcript: patch.transcript ?? this.audioState.transcript,
+      partialTranscript: patch.partialTranscript ?? this.audioState.partialTranscript,
+      error: hasPatch("error") ? patch.error ?? null : this.audioState.error,
+      sessionId: hasPatch("sessionId") ? patch.sessionId ?? null : this.audioState.sessionId ?? null,
+      conversationId: hasPatch("conversationId") ? patch.conversationId ?? null : this.audioState.conversationId ?? this.conversationId,
+      maxSessionSeconds: hasPatch("maxSessionSeconds") ? patch.maxSessionSeconds ?? null : this.audioState.maxSessionSeconds ?? this.agentConfig?.audio?.maxSessionSeconds ?? null,
+      inputLevel: hasPatch("inputLevel") ? patch.inputLevel ?? 0 : this.audioState.inputLevel ?? 0,
+      isSpeaking: hasPatch("isSpeaking") ? patch.isSpeaking ?? false : this.audioState.isSpeaking ?? false,
+      speechMs: hasPatch("speechMs") ? patch.speechMs ?? 0 : this.audioState.speechMs ?? 0,
+      silenceMs: hasPatch("silenceMs") ? patch.silenceMs ?? 0 : this.audioState.silenceMs ?? 0,
+      autoSubmitEnabled: hasPatch("autoSubmitEnabled") ? patch.autoSubmitEnabled ?? false : this.audioState.autoSubmitEnabled ?? this.isAudioAutoSubmitEnabled()
+    };
+  }
+  setAudioState(patch) {
+    this.audioState = this.buildAudioState(patch);
+    this.emit("audio_state", this.audioState);
+  }
+  getAudioContextConstructor() {
+    if (typeof window === "undefined") {
+      return null;
+    }
+    return window.AudioContext ?? window.webkitAudioContext ?? null;
+  }
+  async createRealtimeTranscriptionSession() {
+    const token = await this.resolveAuthToken();
+    const externalUser = this.buildExternalUserContext();
+    const response = await fetch(
+      `${this.config.agentServiceUrl}/api/v1/agents/${encodeURIComponent(this.config.agentId)}/realtime/transcription-sessions`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`
+        },
+        body: JSON.stringify({
+          conversationId: this.conversationId,
+          externalUserId: this.resolveExternalUserId(),
+          externalUser
+        })
+      }
+    );
+    if (!response.ok) {
+      throw await this.buildApiError(response);
+    }
+    return await response.json();
+  }
+  async buildApiError(response) {
+    let code = null;
+    let message = null;
+    try {
+      const payload = await response.clone().json();
+      if (payload && typeof payload === "object") {
+        const record = payload;
+        code = typeof record.code === "string" ? record.code : null;
+        message = extractErrorMessage(payload);
+      }
+    } catch {
+    }
+    const error = new Error(message ?? await getResponseErrorMessage(response));
+    if (code) {
+      error.code = code;
+    }
+    return error;
+  }
+  async openAudioSocket(url) {
+    return new Promise((resolve, reject) => {
+      const socket = new WebSocket(this.normalizeAudioSocketUrl(url));
+      const cleanup = () => {
+        socket.removeEventListener("open", handleOpen);
+        socket.removeEventListener("error", handleError);
+      };
+      const handleOpen = () => {
+        cleanup();
+        resolve(socket);
+      };
+      const handleError = () => {
+        cleanup();
+        reject(new Error("Could not connect to the realtime microphone service."));
+      };
+      socket.addEventListener("open", handleOpen);
+      socket.addEventListener("error", handleError);
+    });
+  }
+  normalizeAudioSocketUrl(url) {
+    if (typeof window === "undefined") {
+      return url;
+    }
+    try {
+      const parsed = new URL(url, window.location.href);
+      if (window.location.protocol === "https:" && parsed.protocol === "ws:") {
+        parsed.protocol = "wss:";
+      }
+      return parsed.toString();
+    } catch {
+      return url;
+    }
+  }
+  bindAudioSocket(socket) {
+    socket.addEventListener("message", (event) => {
+      void this.handleAudioSocketMessage(event);
+    });
+    socket.addEventListener("close", () => {
+      if (this.audioSocket !== socket) {
+        return;
+      }
+      this.audioSocket = null;
+      this.clearAudioSessionTimer();
+      if (this.audioState.status === "listening" || this.audioState.status === "transcribing" || this.audioState.status === "connecting") {
+        this.cleanupAudioCapture(false);
+        this.audioTurnState = null;
+        this.setAudioState({
+          status: "idle",
+          inputLevel: 0,
+          isSpeaking: false,
+          speechMs: 0,
+          silenceMs: 0
+        });
+      }
+    });
+    socket.addEventListener("error", () => {
+      if (this.audioSocket !== socket) {
+        return;
+      }
+      this.cleanupAudioCapture();
+      this.audioTurnState = null;
+      this.setAudioState({
+        status: "error",
+        error: {
+          code: "audio_socket_error",
+          message: "The realtime microphone connection failed."
+        },
+        inputLevel: 0,
+        isSpeaking: false,
+        speechMs: 0,
+        silenceMs: 0
+      });
+    });
+  }
+  async handleAudioSocketMessage(event) {
+    const raw = typeof event.data === "string" ? event.data : event.data instanceof Blob ? await event.data.text() : "";
+    if (!raw) {
+      return;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    const type = typeof payload.type === "string" ? payload.type : "";
+    if (type === "transcript_delta") {
+      const text = typeof payload.text === "string" ? payload.text : "";
+      if (!text) {
+        return;
+      }
+      this.audioFinalTranscript += text;
+      this.setAudioState({
+        partialTranscript: this.audioFinalTranscript,
+        transcript: this.audioFinalTranscript
+      });
+      this.emit("audio_transcript_delta", {
+        text,
+        transcript: this.audioFinalTranscript,
+        isFinal: false
+      });
+      return;
+    }
+    if (type === "transcript_final") {
+      const finalText = (typeof payload.text === "string" && payload.text.trim() ? payload.text : this.audioFinalTranscript).trim();
+      this.cleanupAudioCapture();
+      this.audioTurnState = null;
+      if (!finalText) {
+        this.setAudioState({
+          status: "idle",
+          transcript: "",
+          partialTranscript: "",
+          inputLevel: 0,
+          isSpeaking: false,
+          speechMs: 0,
+          silenceMs: 0
+        });
+        return;
+      }
+      this.setAudioState({
+        status: "sending",
+        transcript: finalText,
+        partialTranscript: "",
+        error: null,
+        inputLevel: 0,
+        isSpeaking: false
+      });
+      this.emit("audio_transcript_final", {
+        text: finalText,
+        transcript: finalText,
+        conversationId: this.conversationId ?? ""
+      });
+      await this.sendMessage(finalText);
+      this.setAudioState({
+        status: "idle",
+        transcript: finalText,
+        partialTranscript: "",
+        sessionId: null,
+        inputLevel: 0,
+        isSpeaking: false,
+        speechMs: 0,
+        silenceMs: 0
+      });
+      return;
+    }
+    if (type === "error") {
+      const code = typeof payload.code === "string" ? payload.code : "audio_error";
+      const message = typeof payload.message === "string" ? payload.message : "Microphone input failed.";
+      this.cleanupAudioCapture();
+      this.audioTurnState = null;
+      this.setAudioState({
+        status: "error",
+        error: { code, message },
+        inputLevel: 0,
+        isSpeaking: false,
+        speechMs: 0,
+        silenceMs: 0
+      });
+    }
+  }
+  async commitVoiceInput() {
+    if (this.audioSessionStopRequested || this.audioState.status !== "listening" && this.audioState.status !== "connecting") {
+      return;
+    }
+    this.audioSessionStopRequested = true;
+    this.cleanupAudioCapture(false);
+    if (this.audioSocket?.readyState === WebSocket.OPEN) {
+      this.audioSocket.send(JSON.stringify({ type: "audio.commit" }));
+      this.setAudioState({
+        status: "transcribing",
+        inputLevel: 0,
+        isSpeaking: false,
+        silenceMs: this.audioTurnState?.silenceMs ?? this.audioState.silenceMs ?? 0,
+        speechMs: this.audioTurnState?.speechMs ?? this.audioState.speechMs ?? 0
+      });
+      return;
+    }
+    this.audioTurnState = null;
+    this.setAudioState({
+      status: "idle",
+      inputLevel: 0,
+      isSpeaking: false,
+      speechMs: 0,
+      silenceMs: 0
+    });
+  }
+  stopVoiceInputWithoutTranscript(message) {
+    this.audioSessionStopRequested = true;
+    this.cleanupAudioCapture();
+    this.audioTurnState = null;
+    this.setAudioState({
+      status: "idle",
+      transcript: "",
+      partialTranscript: "",
+      sessionId: null,
+      inputLevel: 0,
+      isSpeaking: false,
+      speechMs: 0,
+      silenceMs: 0,
+      error: {
+        code: "no_speech_detected",
+        message
+      }
+    });
+  }
+  createAudioTurnState(nowMs) {
+    return {
+      startedAtMs: nowMs,
+      lastFrameAtMs: nowMs,
+      speechStartedAtMs: null,
+      lastSpeechAtMs: null,
+      speechMs: 0,
+      silenceMs: 0,
+      noiseFloor: DEFAULT_AUDIO_TURN_DETECTION.speechThreshold / 2,
+      isSpeaking: false,
+      autoCommitted: false,
+      lastActivityEmitMs: 0
+    };
+  }
+  analyzeAudioFrame(input, durationMs) {
+    if (input.length === 0) {
+      return { rms: 0, peak: 0, inputLevel: 0, durationMs };
+    }
+    let sumSquares = 0;
+    let peak = 0;
+    for (let index = 0; index < input.length; index += 1) {
+      const sample = input[index];
+      const abs = Math.abs(sample);
+      sumSquares += sample * sample;
+      if (abs > peak) {
+        peak = abs;
+      }
+    }
+    const rms = Math.sqrt(sumSquares / input.length);
+    return {
+      rms,
+      peak,
+      inputLevel: Math.min(1, rms * 14),
+      durationMs
+    };
+  }
+  processAudioTurnActivity(activity, nowMs) {
+    const config = this.getAudioTurnDetectionConfig();
+    if (!config.enabled) {
+      this.emitAudioActivity(activity, nowMs, false, 0, 0, DEFAULT_AUDIO_TURN_DETECTION.speechThreshold / 2);
+      return;
+    }
+    const state = this.audioTurnState ?? this.createAudioTurnState(nowMs);
+    this.audioTurnState = state;
+    const frameGapMs = Math.max(1, nowMs - state.lastFrameAtMs);
+    const frameDurationMs = Math.max(activity.durationMs, frameGapMs);
+    state.lastFrameAtMs = nowMs;
+    const adaptiveThreshold = Math.max(
+      config.speechThreshold,
+      Math.min(0.08, state.noiseFloor * config.noiseMultiplier)
+    );
+    const peakThreshold = Math.max(adaptiveThreshold * 2.2, config.speechThreshold * 2.5);
+    const speechCandidate = activity.rms >= adaptiveThreshold || activity.rms >= adaptiveThreshold * 0.72 && activity.peak >= peakThreshold;
+    if (speechCandidate) {
+      if (state.speechStartedAtMs === null) {
+        state.speechStartedAtMs = nowMs;
+        state.speechMs = 0;
+      }
+      state.lastSpeechAtMs = nowMs;
+      state.speechMs += frameDurationMs;
+      state.silenceMs = 0;
+      state.isSpeaking = true;
+    } else {
+      state.noiseFloor = this.updateNoiseFloor(state.noiseFloor, activity.rms);
+      state.isSpeaking = false;
+      if (state.lastSpeechAtMs !== null) {
+        state.silenceMs = nowMs - state.lastSpeechAtMs;
+      }
+    }
+    if (state.speechStartedAtMs !== null && state.speechMs < config.minSpeechDurationMs && state.silenceMs >= config.silenceDurationMs) {
+      state.speechStartedAtMs = null;
+      state.lastSpeechAtMs = null;
+      state.speechMs = 0;
+      state.silenceMs = 0;
+    }
+    this.emitAudioActivity(
+      activity,
+      nowMs,
+      state.isSpeaking,
+      state.speechMs,
+      state.silenceMs,
+      state.noiseFloor
+    );
+    const noSpeechElapsedMs = nowMs - state.startedAtMs;
+    if (config.noSpeechTimeoutMs > 0 && state.speechStartedAtMs === null && noSpeechElapsedMs >= config.noSpeechTimeoutMs && !state.autoCommitted) {
+      state.autoCommitted = true;
+      this.stopVoiceInputWithoutTranscript("No speech was detected. Try again when you are ready to speak.");
+      return;
+    }
+    if (config.autoSubmit && state.speechStartedAtMs !== null && state.speechMs >= config.minSpeechDurationMs && state.silenceMs >= config.silenceDurationMs && !state.autoCommitted) {
+      state.autoCommitted = true;
+      void this.commitVoiceInput();
+    }
+  }
+  updateNoiseFloor(currentNoiseFloor, rms) {
+    const sample = Math.max(15e-4, Math.min(0.08, rms));
+    const smoothing = sample > currentNoiseFloor ? 0.02 : 0.12;
+    return currentNoiseFloor * (1 - smoothing) + sample * smoothing;
+  }
+  emitAudioActivity(activity, nowMs, isSpeaking, speechMs, silenceMs, noiseFloor) {
+    const state = this.audioTurnState;
+    const shouldEmitState = !state || nowMs - state.lastActivityEmitMs >= AUDIO_ACTIVITY_EMIT_INTERVAL_MS || isSpeaking !== this.audioState.isSpeaking || Math.abs(activity.inputLevel - (this.audioState.inputLevel ?? 0)) >= MIN_AUDIO_LEVEL_DELTA_FOR_STATE;
+    if (!shouldEmitState) {
+      return;
+    }
+    if (state) {
+      state.lastActivityEmitMs = nowMs;
+    }
+    const roundedLevel = Number(activity.inputLevel.toFixed(3));
+    const roundedNoiseFloor = Number(noiseFloor.toFixed(5));
+    this.setAudioState({
+      inputLevel: roundedLevel,
+      isSpeaking,
+      speechMs: Math.round(speechMs),
+      silenceMs: Math.round(silenceMs),
+      autoSubmitEnabled: this.isAudioAutoSubmitEnabled()
+    });
+    this.emit("audio_activity", {
+      inputLevel: roundedLevel,
+      noiseFloor: roundedNoiseFloor,
+      isSpeaking,
+      speechMs: Math.round(speechMs),
+      silenceMs: Math.round(silenceMs)
+    });
+  }
+  async startAudioCapture(stream, socket) {
+    const AudioContextCtor = this.getAudioContextConstructor();
+    if (!AudioContextCtor) {
+      throw new Error("Audio capture is not available in this browser.");
+    }
+    const context = new AudioContextCtor();
+    if (context.state === "suspended") {
+      await context.resume();
+    }
+    const source = context.createMediaStreamSource(stream);
+    const processor = context.createScriptProcessor(4096, 1, 1);
+    const silentGain = context.createGain();
+    silentGain.gain.value = 0;
+    this.audioTurnState = this.createAudioTurnState(performance.now());
+    processor.onaudioprocess = (event) => {
+      if (this.audioSessionStopRequested || socket.readyState !== WebSocket.OPEN || this.audioState.status !== "listening") {
+        return;
+      }
+      const input = event.inputBuffer.getChannelData(0);
+      const durationMs = input.length / context.sampleRate * 1e3;
+      this.processAudioTurnActivity(
+        this.analyzeAudioFrame(input, durationMs),
+        performance.now()
+      );
+      if (this.audioSessionStopRequested) {
+        return;
+      }
+      const resampled = this.resampleToPcm16(input, context.sampleRate, 24e3);
+      if (resampled.length === 0) {
+        return;
+      }
+      socket.send(JSON.stringify({
+        type: "audio.append",
+        audio: this.pcm16ToBase64(resampled)
+      }));
+    };
+    source.connect(processor);
+    processor.connect(silentGain);
+    silentGain.connect(context.destination);
+    this.audioContext = context;
+    this.audioSource = source;
+    this.audioProcessor = processor;
+    this.audioSilentGain = silentGain;
+  }
+  resampleToPcm16(input, inputSampleRate, outputSampleRate) {
+    if (inputSampleRate === outputSampleRate) {
+      return this.floatToPcm16(input);
+    }
+    const ratio = inputSampleRate / outputSampleRate;
+    const outputLength = Math.floor(input.length / ratio);
+    const output = new Float32Array(outputLength);
+    for (let index = 0; index < outputLength; index += 1) {
+      const inputIndex = index * ratio;
+      const lower = Math.floor(inputIndex);
+      const upper = Math.min(lower + 1, input.length - 1);
+      const weight = inputIndex - lower;
+      output[index] = input[lower] * (1 - weight) + input[upper] * weight;
+    }
+    return this.floatToPcm16(output);
+  }
+  floatToPcm16(input) {
+    const output = new Int16Array(input.length);
+    for (let index = 0; index < input.length; index += 1) {
+      const sample = Math.max(-1, Math.min(1, input[index]));
+      output[index] = sample < 0 ? sample * 32768 : sample * 32767;
+    }
+    return output;
+  }
+  pcm16ToBase64(input) {
+    const bytes = new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+    let binary = "";
+    const chunkSize = 32768;
+    for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+      const chunk = bytes.subarray(offset, offset + chunkSize);
+      binary += String.fromCharCode(...chunk);
+    }
+    return btoa(binary);
+  }
+  cleanupAudioCapture(closeSocket = true) {
+    this.clearAudioSessionTimer();
+    this.audioProcessor?.disconnect();
+    this.audioSource?.disconnect();
+    this.audioSilentGain?.disconnect();
+    this.audioProcessor = null;
+    this.audioSource = null;
+    this.audioSilentGain = null;
+    if (this.audioContext) {
+      void this.audioContext.close().catch(() => void 0);
+      this.audioContext = null;
+    }
+    this.audioStream?.getTracks().forEach((track) => track.stop());
+    this.audioStream = null;
+    if (closeSocket && this.audioSocket) {
+      const socket = this.audioSocket;
+      this.audioSocket = null;
+      if (socket.readyState === WebSocket.OPEN) {
+        socket.send(JSON.stringify({ type: "audio.close" }));
+        socket.close();
+      } else if (socket.readyState === WebSocket.CONNECTING) {
+        socket.close();
+      }
+    }
+  }
+  clearAudioSessionTimer() {
+    if (!this.audioSessionTimer) {
+      return;
+    }
+    clearTimeout(this.audioSessionTimer);
+    this.audioSessionTimer = null;
+  }
+  extractErrorCode(error) {
+    if (error && typeof error === "object" && "code" in error) {
+      const code = error.code;
+      return typeof code === "string" ? code : null;
+    }
+    return null;
+  }
+  getPersistentStorage() {
+    return this.config.storage ?? null;
+  }
+  async resolveOAuthClientRegistration(authConfig) {
+    if (!authConfig || authConfig.authType !== "oauth2") {
+      return authConfig ?? null;
+    }
+    const registration = await resolveOAuthRegistration(authConfig, {
+      callbackUrl: this.getOAuthCallbackUrl(),
+      oauthClientMetadataUrl: this.config.oauthClientMetadataUrl,
+      clientName: "MCP Stack MCP Client",
+      clientUri: "https://mcpstack.com",
+      storage: this.getPersistentStorage()
+    });
+    return applyResolvedRegistration(authConfig, registration);
+  }
+  /** Subscribe to events */
+  on(event, handler) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(handler);
+  }
+  /** Unsubscribe from events */
+  off(event, handler) {
+    this.listeners.get(event)?.delete(handler);
+  }
+  // ================================================================
+  // Private methods
+  // ================================================================
+  buildProtectedResourceMetadataCandidates(mcpServerUrl) {
+    const url = new URL(mcpServerUrl);
+    const candidates = /* @__PURE__ */ new Set();
+    const normalizedPath = url.pathname.endsWith("/") ? url.pathname.slice(0, -1) : url.pathname;
+    if (!normalizedPath || normalizedPath === "/") {
+      candidates.add(`${url.origin}/.well-known/oauth-protected-resource`);
+      return [...candidates];
+    }
+    candidates.add(`${url.origin}/.well-known/oauth-protected-resource${normalizedPath}`);
+    candidates.add(`${url.origin}${normalizedPath}/.well-known/oauth-protected-resource`);
+    candidates.add(`${url.origin}/.well-known/oauth-protected-resource`);
+    return [...candidates];
+  }
+  hasSameOrigin(left, right) {
+    try {
+      const leftUrl = new URL(left);
+      const rightUrl = new URL(right);
+      return leftUrl.origin === rightUrl.origin;
+    } catch {
+      return false;
+    }
+  }
+  extractQuotedHeaderValue(header, key) {
+    const match = header.match(new RegExp(`${key}="([^"]+)"`, "i"));
+    return match?.[1] ?? null;
+  }
+  buildAuthorizationServerMetadataCandidates(issuerOrMetadataUrl) {
+    const candidates = /* @__PURE__ */ new Set();
+    if (issuerOrMetadataUrl.includes("/.well-known/oauth-authorization-server") || issuerOrMetadataUrl.includes("/.well-known/openid-configuration")) {
+      candidates.add(issuerOrMetadataUrl);
+      return [...candidates];
+    }
+    const url = new URL(issuerOrMetadataUrl);
+    const normalizedPath = url.pathname.endsWith("/") ? url.pathname.slice(0, -1) : url.pathname;
+    if (!normalizedPath || normalizedPath === "/") {
+      candidates.add(`${url.origin}/.well-known/oauth-authorization-server`);
+      candidates.add(`${url.origin}/.well-known/openid-configuration`);
+      return [...candidates];
+    }
+    candidates.add(`${url.origin}/.well-known/oauth-authorization-server${normalizedPath}`);
+    candidates.add(`${url.origin}/.well-known/openid-configuration${normalizedPath}`);
+    candidates.add(`${url.origin}${normalizedPath}/.well-known/openid-configuration`);
+    return [...candidates];
+  }
+  hasExplicitManualOverride(manualConfig, field) {
+    return manualConfig?.manualOverrides?.includes(field) ?? false;
+  }
+  pickAuthConfigValue(field, manualConfig, manualValue, discoveredValue) {
+    if (this.hasExplicitManualOverride(manualConfig, field) && manualValue != null) {
+      return manualValue;
+    }
+    return discoveredValue ?? manualValue;
+  }
+  pickAuthConfigArrayValue(field, manualConfig, manualValue, discoveredValue) {
+    if (this.hasExplicitManualOverride(manualConfig, field) && manualValue?.length) {
+      return manualValue;
+    }
+    if (discoveredValue?.length) {
+      return discoveredValue;
+    }
+    return manualValue?.length ? manualValue : void 0;
+  }
+  mergeAuthConfigs(manualConfig, discoveredConfig) {
+    if (!manualConfig && !discoveredConfig) return null;
+    const manualOverrides = new Set(manualConfig?.manualOverrides ?? []);
+    const authorizationEndpoint = this.pickAuthConfigValue(
+      "authorizationEndpoint",
+      manualConfig,
+      manualConfig?.authorizationEndpoint ?? manualConfig?.loginUrl,
+      discoveredConfig?.authorizationEndpoint ?? discoveredConfig?.loginUrl
+    );
+    const tokenEndpoint = this.pickAuthConfigValue(
+      "tokenEndpoint",
+      manualConfig,
+      manualConfig?.tokenEndpoint ?? manualConfig?.tokenUrl,
+      discoveredConfig?.tokenEndpoint ?? discoveredConfig?.tokenUrl
+    );
+    const callbackUrl = this.pickAuthConfigValue(
+      "callbackUrl",
+      manualConfig,
+      manualConfig?.callbackUrl,
+      discoveredConfig?.callbackUrl
+    ) ?? this.getOAuthCallbackUrl();
+    const merged = {
+      authType: manualConfig?.authType ?? discoveredConfig?.authType ?? "oauth2",
+      issuer: discoveredConfig?.issuer ?? manualConfig?.issuer,
+      authorizationServerUrl: this.pickAuthConfigValue(
+        "authorizationServerUrl",
+        manualConfig,
+        manualConfig?.authorizationServerUrl,
+        discoveredConfig?.authorizationServerUrl
+      ),
+      authorizationServerMetadataUrl: this.pickAuthConfigValue(
+        "authorizationServerMetadataUrl",
+        manualConfig,
+        manualConfig?.authorizationServerMetadataUrl,
+        discoveredConfig?.authorizationServerMetadataUrl
+      ),
+      authorizationEndpoint,
+      loginUrl: authorizationEndpoint,
+      tokenEndpoint,
+      tokenUrl: tokenEndpoint,
+      registrationEndpoint: this.pickAuthConfigValue(
+        "registrationEndpoint",
+        manualConfig,
+        manualConfig?.registrationEndpoint,
+        discoveredConfig?.registrationEndpoint
+      ),
+      clientId: this.pickAuthConfigValue(
+        "clientId",
+        manualConfig,
+        manualConfig?.clientId,
+        discoveredConfig?.clientId
+      ),
+      scopes: this.pickAuthConfigArrayValue(
+        "scopes",
+        manualConfig,
+        manualConfig?.scopes,
+        discoveredConfig?.scopes
+      ),
+      resource: this.pickAuthConfigValue(
+        "resource",
+        manualConfig,
+        manualConfig?.resource,
+        discoveredConfig?.resource
+      ),
+      callbackUrl,
+      protectedResourceMetadataUrl: discoveredConfig?.protectedResourceMetadataUrl ?? manualConfig?.protectedResourceMetadataUrl,
+      clientIdMetadataDocumentSupported: discoveredConfig?.clientIdMetadataDocumentSupported ?? manualConfig?.clientIdMetadataDocumentSupported,
+      resourceParameterSupported: discoveredConfig?.resourceParameterSupported ?? manualConfig?.resourceParameterSupported,
+      registrationPreference: manualConfig?.registrationPreference ?? discoveredConfig?.registrationPreference ?? "auto",
+      clientMode: discoveredConfig?.clientMode ?? manualConfig?.clientMode,
+      authRecipe: manualConfig?.authRecipe ?? discoveredConfig?.authRecipe,
+      manualOverrides: manualOverrides.size ? [...manualOverrides] : void 0,
+      discovered: discoveredConfig?.discovered ?? false
+    };
+    return merged;
+  }
+  async discoverAuthConfig(mcpServerUrl, manualConfig) {
+    let protectedResourceUrl = null;
+    let protectedResource = null;
+    const protectedResourceCandidates = /* @__PURE__ */ new Set();
+    if (manualConfig?.protectedResourceMetadataUrl) {
+      protectedResourceCandidates.add(manualConfig.protectedResourceMetadataUrl);
+    }
+    for (const candidate of this.buildProtectedResourceMetadataCandidates(mcpServerUrl)) {
+      protectedResourceCandidates.add(candidate);
+    }
+    for (const candidate of protectedResourceCandidates) {
+      try {
+        const response = await fetch(candidate, {
+          method: "GET",
+          headers: { Accept: "application/json" }
+        });
+        if (response.ok) {
+          protectedResource = await response.json();
+          protectedResourceUrl = candidate;
+          break;
+        }
+        const authenticateHeader = response.headers.get("www-authenticate");
+        if (authenticateHeader) {
+          const resourceMetadataUrl = this.extractQuotedHeaderValue(authenticateHeader, "resource_metadata");
+          if (resourceMetadataUrl && this.hasSameOrigin(candidate, resourceMetadataUrl)) {
+            const metadataResponse = await fetch(resourceMetadataUrl, {
+              method: "GET",
+              headers: { Accept: "application/json" }
+            });
+            if (metadataResponse.ok) {
+              protectedResource = await metadataResponse.json();
+              protectedResourceUrl = resourceMetadataUrl;
+              break;
+            }
+          }
+        }
+      } catch {
+      }
+    }
+    const authServerUrl = protectedResource?.authorization_servers?.[0] ?? protectedResource?.authorization_server ?? manualConfig?.authorizationServerUrl;
+    try {
+      let metadata = null;
+      let metadataUrl = manualConfig?.authorizationServerMetadataUrl ?? null;
+      const metadataCandidates = /* @__PURE__ */ new Set();
+      if (manualConfig?.authorizationServerMetadataUrl) {
+        metadataCandidates.add(manualConfig.authorizationServerMetadataUrl);
+      }
+      if (authServerUrl) {
+        for (const candidate of this.buildAuthorizationServerMetadataCandidates(authServerUrl)) {
+          metadataCandidates.add(candidate);
+        }
+      }
+      for (const candidate of metadataCandidates) {
+        try {
+          const response = await fetch(candidate, {
+            method: "GET",
+            headers: { Accept: "application/json" }
+          });
+          if (response.ok) {
+            metadata = await response.json();
+            metadataUrl = candidate;
+            break;
+          }
+        } catch {
+        }
+      }
+      if (!metadata && !protectedResource && !manualConfig) {
+        return null;
+      }
+      return {
+        authType: "oauth2",
+        issuer: metadata?.issuer ?? authServerUrl ?? manualConfig?.issuer,
+        authorizationServerUrl: authServerUrl ?? manualConfig?.authorizationServerUrl,
+        authorizationServerMetadataUrl: metadataUrl ?? void 0,
+        authorizationEndpoint: metadata?.authorization_endpoint ?? manualConfig?.authorizationEndpoint ?? manualConfig?.loginUrl,
+        loginUrl: metadata?.authorization_endpoint ?? manualConfig?.loginUrl ?? manualConfig?.authorizationEndpoint,
+        tokenEndpoint: metadata?.token_endpoint ?? manualConfig?.tokenEndpoint ?? manualConfig?.tokenUrl,
+        tokenUrl: metadata?.token_endpoint ?? manualConfig?.tokenUrl ?? manualConfig?.tokenEndpoint,
+        registrationEndpoint: metadata?.registration_endpoint ?? manualConfig?.registrationEndpoint,
+        clientId: manualConfig?.clientId,
+        scopes: protectedResource?.scopes_supported?.length ? protectedResource.scopes_supported : metadata?.scopes_supported ?? manualConfig?.scopes,
+        resource: protectedResource?.resource ?? manualConfig?.resource,
+        callbackUrl: getEffectiveCallbackUrl(manualConfig, this.getOAuthCallbackUrl()),
+        protectedResourceMetadataUrl: protectedResourceUrl ?? manualConfig?.protectedResourceMetadataUrl,
+        clientIdMetadataDocumentSupported: metadata?.client_id_metadata_document_supported ?? manualConfig?.clientIdMetadataDocumentSupported,
+        resourceParameterSupported: metadata?.resource_parameter_supported ?? manualConfig?.resourceParameterSupported,
+        registrationPreference: manualConfig?.registrationPreference ?? "auto",
+        authRecipe: manualConfig?.authRecipe,
+        discovered: Boolean(protectedResource || metadata)
+      };
+    } catch {
+      return manualConfig ? {
+        ...manualConfig,
+        callbackUrl: getEffectiveCallbackUrl(manualConfig, this.getOAuthCallbackUrl()),
+        protectedResourceMetadataUrl: protectedResourceUrl ?? manualConfig.protectedResourceMetadataUrl,
+        resource: protectedResource?.resource ?? manualConfig.resource,
+        scopes: protectedResource?.scopes_supported?.length ? protectedResource.scopes_supported : manualConfig.scopes,
+        discovered: Boolean(protectedResource)
+      } : null;
+    }
+  }
+  async resolveServerAuthConfig(mcpServerUrl, manualConfig) {
+    const discoveredConfig = await this.discoverAuthConfig(mcpServerUrl, manualConfig);
+    return this.mergeAuthConfigs(manualConfig, discoveredConfig);
+  }
+  async ensureServerAuthConfig(mcpServerUrl) {
+    const server = this.agentConfig?.mcpServers?.find((item) => item.url === mcpServerUrl);
+    if (!server) {
+      return null;
+    }
+    if (server.authConfig && (server.authConfig.authType !== "oauth2" || server.authConfig.discovered || !!server.authConfig.authorizationEndpoint || !!server.authConfig.tokenEndpoint || !!server.authConfig.tokenUrl || !!server.authConfig.registrationEndpoint || !!server.authConfig.resource)) {
+      return server.authConfig;
+    }
+    server.authConfig = await this.resolveServerAuthConfig(mcpServerUrl, server.authConfig ?? null);
+    return server.authConfig;
+  }
+  updateServerAuthConfig(mcpServerUrl, authConfig) {
+    const server = this.agentConfig?.mcpServers?.find((item) => item.url === mcpServerUrl);
+    if (server) {
+      server.authConfig = authConfig;
+    }
+  }
+  emit(event, data) {
+    this.listeners.get(event)?.forEach((handler) => handler(data));
+  }
+  // ================================================================
+  // OAuth Token Storage (standalone mode only)
+  // ================================================================
+  /** Generate the legacy token cache suffix used before auth-aware keying. */
+  hashUrl(url) {
+    return btoa(url).replace(/[^a-zA-Z0-9]/g, "").slice(0, 32);
+  }
+  getLegacyTokenStorageKey(mcpServerUrl) {
+    return buildScopedOAuthTokenStorageKey(this.hashUrl(mcpServerUrl));
+  }
+  getAuthSessionKey() {
+    return resolveExplicitAuthSessionKey(this.config);
+  }
+  getTokenStorageKey(mcpServerUrl, authConfig) {
+    return buildScopedOAuthTokenStorageKey(
+      buildTokenCacheKey(authConfig, mcpServerUrl),
+      this.getAuthSessionKey()
+    );
+  }
+  getTokenStorageCandidates(mcpServerUrl) {
+    const currentAuthConfig = this.getServerAuthConfig(mcpServerUrl);
+    const hasExplicitAuthSessionKey = this.getAuthSessionKey() !== null;
+    if (!currentAuthConfig) {
+      return hasExplicitAuthSessionKey ? [{
+        storageKey: this.getTokenStorageKey(mcpServerUrl, null),
+        authConfig: null
+      }] : [{
+        storageKey: this.getLegacyTokenStorageKey(mcpServerUrl),
+        authConfig: null
+      }];
+    }
+    const callbackUrl = getEffectiveCallbackUrl(currentAuthConfig, this.getOAuthCallbackUrl());
+    const candidates = [currentAuthConfig];
+    if (currentAuthConfig.authType === "oauth2") {
+      candidates.push({
+        ...currentAuthConfig,
+        clientMode: "manual",
+        callbackUrl
+      });
+      if (currentAuthConfig.clientId) {
+        candidates.push({
+          ...currentAuthConfig,
+          clientMode: "preregistered",
+          callbackUrl
+        });
+      }
+      if (currentAuthConfig.clientIdMetadataDocumentSupported && this.config.oauthClientMetadataUrl) {
+        candidates.push({
+          ...currentAuthConfig,
+          clientId: this.config.oauthClientMetadataUrl,
+          clientMode: "cimd",
+          callbackUrl
+        });
+      }
+      if (currentAuthConfig.registrationEndpoint) {
+        const cacheKey = buildRegistrationCacheKey(currentAuthConfig, callbackUrl, "dcr");
+        const storedRegistration = loadStoredRegistration(cacheKey, this.getPersistentStorage());
+        if (storedRegistration?.clientId) {
+          candidates.push(applyResolvedRegistration(currentAuthConfig, {
+            cacheKey,
+            mode: "dcr",
+            clientId: storedRegistration.clientId,
+            callbackUrl,
+            resource: currentAuthConfig.resource,
+            authorizationServerUrl: currentAuthConfig.authorizationServerUrl,
+            authorizationServerMetadataUrl: currentAuthConfig.authorizationServerMetadataUrl,
+            registrationEndpoint: currentAuthConfig.registrationEndpoint
+          }));
+        }
+      }
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const resolved = candidates.map((candidate) => ({
+      storageKey: this.getTokenStorageKey(mcpServerUrl, candidate),
+      authConfig: candidate
+    })).filter((candidate) => {
+      if (seen.has(candidate.storageKey)) return false;
+      seen.add(candidate.storageKey);
+      return true;
+    });
+    if (!hasExplicitAuthSessionKey) {
+      resolved.push({
+        storageKey: this.getLegacyTokenStorageKey(mcpServerUrl),
+        authConfig: currentAuthConfig
+      });
+    }
+    return resolved;
+  }
+  /** Load OAuth token from memory/persistent storage using auth-aware cache keying. */
+  loadOAuthToken(mcpServerUrl) {
+    for (const candidate of this.getTokenStorageCandidates(mcpServerUrl)) {
+      const cached = this.oauthTokens.get(candidate.storageKey);
+      if (cached) {
+        if (candidate.authConfig) {
+          this.updateServerAuthConfig(mcpServerUrl, candidate.authConfig);
+        }
+        return cached;
+      }
+    }
+    try {
+      const storage = this.getPersistentStorage() ?? (typeof localStorage !== "undefined" ? localStorage : null);
+      if (storage) {
+        for (const candidate of this.getTokenStorageCandidates(mcpServerUrl)) {
+          const stored = storage.getItem(candidate.storageKey);
+          if (stored) {
+            const data = JSON.parse(stored);
+            if (data.accessToken && data.expiresAt) {
+              this.oauthTokens.set(candidate.storageKey, data);
+              if (candidate.authConfig) {
+                this.updateServerAuthConfig(mcpServerUrl, candidate.authConfig);
+              }
+              return data;
+            }
+          }
+        }
+      }
+    } catch {
+    }
+    return null;
+  }
+  /** Check if we have a valid (non-expired) OAuth token */
+  hasValidOAuthToken(mcpServerUrl) {
+    const token = this.loadOAuthToken(mcpServerUrl);
+    if (!token) return false;
+    return token.expiresAt > Date.now() || !!token.refreshToken;
+  }
+  /** Store OAuth token to memory and persistent storage */
+  storeOAuthToken(mcpServerUrl, tokenResponse) {
+    const resolvedAuthConfig = tokenResponse.resolvedAuthConfig ?? this.getServerAuthConfig(mcpServerUrl);
+    const storageKey = this.getTokenStorageKey(mcpServerUrl, resolvedAuthConfig);
+    const expiresIn = tokenResponse.expiresIn ?? 3600;
+    const expiresAt = Date.now() + expiresIn * 1e3 - 60 * 1e3;
+    const data = {
+      accessToken: tokenResponse.accessToken,
+      refreshToken: tokenResponse.refreshToken,
+      expiresAt
+    };
+    this.oauthTokens.set(storageKey, data);
+    try {
+      const storage = this.getPersistentStorage() ?? (typeof localStorage !== "undefined" ? localStorage : null);
+      if (storage) {
+        storage.setItem(storageKey, JSON.stringify(data));
+      }
+    } catch {
+    }
+  }
+  /** Clear OAuth token from memory and persistent storage */
+  clearOAuthToken(mcpServerUrl) {
+    for (const candidate of this.getTokenStorageCandidates(mcpServerUrl)) {
+      this.oauthTokens.delete(candidate.storageKey);
+    }
+    try {
+      const storage = this.getPersistentStorage() ?? (typeof localStorage !== "undefined" ? localStorage : null);
+      if (storage) {
+        for (const candidate of this.getTokenStorageCandidates(mcpServerUrl)) {
+          storage.removeItem(candidate.storageKey);
+        }
+      }
+    } catch {
+    }
+  }
+  /** Refresh OAuth token using refresh token */
+  async refreshOAuthToken(mcpServerUrl, refreshToken) {
+    const authConfig = await this.ensureServerAuthConfig(mcpServerUrl);
+    const tokenUrl = authConfig?.tokenEndpoint ?? authConfig?.tokenUrl;
+    if (!tokenUrl) return void 0;
+    try {
+      const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken
+      });
+      if (authConfig?.clientId) body.set("client_id", authConfig.clientId);
+      if (authConfig?.resource) body.set("resource", authConfig.resource);
+      const response = await fetch(tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body
+      });
+      if (response.ok) {
+        const data = await response.json();
+        if (data.access_token) {
+          const tokenResponse = {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token ?? refreshToken,
+            expiresIn: data.expires_in,
+            resolvedAuthConfig: authConfig ?? void 0
+          };
+          this.storeOAuthToken(mcpServerUrl, tokenResponse);
+          return data.access_token;
+        }
+      }
+    } catch {
+    }
+    return void 0;
+  }
+  // ================================================================
+  // Token Resolution
+  // ================================================================
+  /**
+   * Resolve the auth token for an MCP server.
+   * - OAuth mode: Checks stored token, refreshes if expired, triggers auth if needed
+   */
+  async resolveToken(mcpServerUrl) {
+    if (this.manuallySignedOutServers.has(mcpServerUrl)) {
+      return void 0;
+    }
+    const authConfig = await this.ensureServerAuthConfig(mcpServerUrl);
+    const stored = this.loadOAuthToken(mcpServerUrl);
+    if (stored) {
+      if (stored.expiresAt > Date.now()) {
+        return stored.accessToken;
+      }
+      if (stored.refreshToken) {
+        const refreshed = await this.refreshOAuthToken(mcpServerUrl, stored.refreshToken);
+        if (refreshed) return refreshed;
+      }
+      this.clearOAuthToken(mcpServerUrl);
+    }
+    if (this.config.onAuthRequired) {
+      if (authConfig) {
+        const isBuiltInPopupAuth = this.config.onAuthRequired.__mcpStackBuiltinPopupAuth === true;
+        const isAppTokenAuth = this.config.auth?.mode === "app-token";
+        const authConfigForHandler = authConfig.authType === "oauth2" && !isBuiltInPopupAuth && !isAppTokenAuth ? await this.resolveOAuthClientRegistration(authConfig) : authConfig;
+        if (authConfigForHandler) {
+          this.updateServerAuthConfig(mcpServerUrl, authConfigForHandler);
+        }
+        const tokenResponse = await this.config.onAuthRequired(
+          mcpServerUrl,
+          authConfigForHandler ?? authConfig
+        );
+        if (tokenResponse?.accessToken) {
+          if (tokenResponse.resolvedAuthConfig) {
+            this.updateServerAuthConfig(mcpServerUrl, tokenResponse.resolvedAuthConfig);
+          }
+          this.storeOAuthToken(mcpServerUrl, tokenResponse);
+          return tokenResponse.accessToken;
+        }
+      }
+    }
+    return void 0;
+  }
+  // ================================================================
+  // Chat Loop
+  // ================================================================
+  /**
+   * The core orchestration loop:
+   * 1. Send message to chat API
+   * 2. Stream response
+   * 3. If tool_call → execute tool via MCP → send result → continue
+   * 4. If message_end → done
+   */
+  async runChatLoop(message) {
+    this.abortController = new AbortController();
+    this.emit("thinking", true);
+    const chatBody = {
+      agentId: this.config.agentId,
+      conversationId: this.conversationId,
+      message,
+      externalUserId: this.resolveExternalUserId(),
+      context: this.config.context
+    };
+    const externalUser = this.buildExternalUserContext();
+    if (externalUser) {
+      chatBody.externalUser = externalUser;
+    }
+    const clientToolSchemas = this.clientToolsToSchemas();
+    if (clientToolSchemas.length > 0) {
+      chatBody.clientTools = clientToolSchemas;
+    }
+    let response = await this.callChatApi(chatBody, "chat");
+    while (true) {
+      const result = await this.processSseStream(response);
+      if (result.type === "message_end") {
+        break;
+      }
+      if (result.type === "tool_call") {
+        const toolCall = result.data;
+        const startTime = Date.now();
+        try {
+          const toolResult = await this.executeTool(toolCall);
+          const duration = Date.now() - startTime;
+          const toolCallMsg = this.messages.find(
+            (m) => m.role === "tool_call" && m.toolCallId === toolCall.toolCallId
+          );
+          if (toolCallMsg) {
+            toolCallMsg.toolCallStatus = "completed";
+            toolCallMsg.toolCallDuration = duration;
+            toolCallMsg.toolResult = typeof toolResult === "string" ? toolResult : JSON.stringify(toolResult);
+          }
+          this.emit("tool_result", { toolCallId: toolCall.toolCallId, result: toolResult, duration });
+          const toolResultMsg = {
+            id: crypto.randomUUID(),
+            role: "tool_result",
+            content: typeof toolResult === "string" ? toolResult : JSON.stringify(toolResult),
+            toolCallId: toolCall.toolCallId,
+            toolName: toolCall.toolName,
+            timestamp: /* @__PURE__ */ new Date()
+          };
+          this.messages.push(toolResultMsg);
+          this.emit("thinking", true);
+          const toolResultBody = {
+            conversationId: this.conversationId,
+            toolCallId: toolCall.toolCallId,
+            result: toolResult,
+            durationMs: duration,
+            context: this.config.context
+          };
+          const clientToolSchemas2 = this.clientToolsToSchemas();
+          if (clientToolSchemas2.length > 0) {
+            toolResultBody.clientTools = clientToolSchemas2;
+          }
+          response = await this.callChatApi(toolResultBody, "chat/tool-result");
+        } catch (err) {
+          const duration = Date.now() - startTime;
+          const errorMsg = err instanceof Error ? err.message : "Tool execution failed";
+          const toolCallMsg = this.messages.find(
+            (m) => m.role === "tool_call" && m.toolCallId === toolCall.toolCallId
+          );
+          if (toolCallMsg) {
+            toolCallMsg.toolCallStatus = "error";
+            toolCallMsg.toolCallDuration = duration;
+            toolCallMsg.toolError = errorMsg;
+          }
+          this.emit("tool_error", { toolCallId: toolCall.toolCallId, error: errorMsg, duration });
+          const errorResult = `Error: ${errorMsg}`;
+          const toolResultMsg = {
+            id: crypto.randomUUID(),
+            role: "tool_result",
+            content: errorResult,
+            toolCallId: toolCall.toolCallId,
+            toolName: toolCall.toolName,
+            timestamp: /* @__PURE__ */ new Date()
+          };
+          this.messages.push(toolResultMsg);
+          this.emit("thinking", true);
+          try {
+            const toolResultBody = {
+              conversationId: this.conversationId,
+              toolCallId: toolCall.toolCallId,
+              result: errorResult,
+              isError: true,
+              durationMs: duration,
+              context: this.config.context
+            };
+            const clientToolSchemas2 = this.clientToolsToSchemas();
+            if (clientToolSchemas2.length > 0) {
+              toolResultBody.clientTools = clientToolSchemas2;
+            }
+            response = await this.callChatApi(toolResultBody, "chat/tool-result");
+          } catch {
+            this.emit("error", { code: "tool_error", message: errorMsg });
+            break;
+          }
+        }
+      }
+      if (result.type === "error") {
+        break;
+      }
+    }
+  }
+  async callChatApi(body, endpoint) {
+    const token = await this.resolveAuthToken();
+    const response = await fetch(
+      `${this.config.agentServiceUrl}/api/v1/${endpoint}`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`
+        },
+        body: JSON.stringify(body),
+        signal: this.abortController?.signal
+      }
+    );
+    if (!response.ok) {
+      throw new Error(await getResponseErrorMessage(response));
+    }
+    return response;
+  }
+  async fetchConversationMessages(conversationId, cursor, pageSize = 50) {
+    const token = await this.resolveAuthToken();
+    const params = new URLSearchParams();
+    params.set("pageSize", String(pageSize));
+    if (cursor) {
+      params.set("cursor", cursor);
+    }
+    const response = await fetch(
+      `${this.config.agentServiceUrl}/api/v1/chat/conversations/${encodeURIComponent(conversationId)}/messages?${params.toString()}`,
+      {
+        headers: {
+          Authorization: `Bearer ${token}`
+        }
+      }
+    );
+    if (!response.ok) {
+      throw new Error(await getResponseErrorMessage(response));
+    }
+    return await response.json();
+  }
+  applyConversationPage(page, prepend) {
+    const mappedMessages = page.messages.map((message) => this.mapReplayMessage(message));
+    this.conversationId = page.conversationId;
+    this.historyCursor = page.nextCursor ?? null;
+    this.hasOlderMessages = page.hasNextPage;
+    this.messages = prepend ? [...mappedMessages, ...this.messages] : mappedMessages;
+  }
+  mapReplayMessage(message) {
+    const timestamp = new Date(message.createdAt);
+    return {
+      id: message.id,
+      role: message.role,
+      content: message.content ?? "",
+      toolName: message.toolName ?? void 0,
+      toolLabel: message.toolLabel ?? void 0,
+      toolCallId: message.toolCallId ?? void 0,
+      timestamp,
+      toolCallStatus: message.toolCallStatus ?? void 0,
+      toolCallStartTime: message.toolCallDurationMs != null ? timestamp.getTime() - message.toolCallDurationMs : void 0,
+      toolCallDuration: message.toolCallDurationMs ?? void 0,
+      toolResult: message.toolResultJson ?? void 0,
+      toolError: message.toolError ?? void 0,
+      errorCode: message.errorCode ?? void 0,
+      metadataJson: message.metadataJson ?? null
+    };
+  }
+  /**
+   * Process an SSE stream from the chat API.
+   * Returns when the stream ends (either message_end or tool_call).
+   */
+  async processSseStream(response) {
+    let assistantContent = "";
+    let lastToolCall = null;
+    let emittedThinkingFalse = false;
+    for await (const event of parseSseStream(response, this.abortController?.signal)) {
+      switch (event.type) {
+        case "message_start": {
+          const data = event.data;
+          this.conversationId = data.conversationId;
+          break;
+        }
+        case "content_delta": {
+          const data = event.data;
+          if (!emittedThinkingFalse) {
+            this.emit("thinking", false);
+            emittedThinkingFalse = true;
+          }
+          assistantContent += data.text;
+          this.emit("content_delta", data);
+          break;
+        }
+        case "tool_call": {
+          const data = event.data;
+          if (!emittedThinkingFalse) {
+            this.emit("thinking", false);
+            emittedThinkingFalse = true;
+          }
+          lastToolCall = data;
+          const toolCallMsg = {
+            id: crypto.randomUUID(),
+            role: "tool_call",
+            content: `Calling ${data.toolLabel ?? data.toolName}...`,
+            toolName: data.toolName,
+            toolLabel: data.toolLabel,
+            toolCallId: data.toolCallId,
+            timestamp: /* @__PURE__ */ new Date(),
+            toolCallStatus: "calling",
+            toolCallStartTime: Date.now()
+          };
+          this.messages.push(toolCallMsg);
+          this.emit("tool_call", data);
+          break;
+        }
+        case "message_end": {
+          const data = event.data;
+          if (assistantContent) {
+            const assistantMsg = {
+              id: crypto.randomUUID(),
+              role: "assistant",
+              content: assistantContent,
+              timestamp: /* @__PURE__ */ new Date()
+            };
+            this.messages.push(assistantMsg);
+            this.emit("message", assistantMsg);
+          }
+          this.emit("message_end", data);
+          return { type: "message_end", data };
+        }
+        case "budget_snapshot": {
+          const data = event.data;
+          this.budgetSnapshot = data;
+          this.emit("budget_snapshot", data);
+          break;
+        }
+        case "error": {
+          const data = event.data;
+          if (data.budget) {
+            this.budgetSnapshot = data.budget;
+            this.emit("budget_snapshot", data.budget);
+          }
+          const errorMsg = {
+            id: crypto.randomUUID(),
+            role: "error",
+            content: data.message,
+            timestamp: /* @__PURE__ */ new Date(),
+            errorCode: data.code
+          };
+          this.messages.push(errorMsg);
+          this.emit("message", errorMsg);
+          this.emit("error", data);
+          return { type: "error", data };
+        }
+      }
+    }
+    if (lastToolCall) {
+      if (assistantContent) {
+        const assistantMsg = {
+          id: crypto.randomUUID(),
+          role: "assistant",
+          content: assistantContent,
+          timestamp: /* @__PURE__ */ new Date()
+        };
+        this.messages.push(assistantMsg);
+        this.emit("message", assistantMsg);
+      }
+      return { type: "tool_call", data: lastToolCall };
+    }
+    if (assistantContent) {
+      const assistantMsg = {
+        id: crypto.randomUUID(),
+        role: "assistant",
+        content: assistantContent,
+        timestamp: /* @__PURE__ */ new Date()
+      };
+      this.messages.push(assistantMsg);
+      this.emit("message", assistantMsg);
+    }
+    return { type: "message_end" };
+  }
+  // ================================================================
+  // MCP Session Management
+  // ================================================================
+  /** Build headers for MCP server requests */
+  getMcpHeaders(mcpServerUrl) {
+    const headers = {
+      "Content-Type": "application/json",
+      "Accept": "application/json, text/event-stream"
+    };
+    const session = this.mcpSessions.get(mcpServerUrl);
+    if (session?.sessionId) {
+      headers["Mcp-Session-Id"] = session.sessionId;
+    }
+    return headers;
+  }
+  /** Best-effort MCP session teardown so reconnect starts cleanly after sign-out. */
+  async closeMcpSession(mcpServerUrl) {
+    const session = this.mcpSessions.get(mcpServerUrl);
+    if (!session?.sessionId) return;
+    const headers = {
+      "Accept": "application/json, text/event-stream",
+      "Mcp-Session-Id": session.sessionId
+    };
+    const storedToken = this.loadOAuthToken(mcpServerUrl);
+    if (storedToken?.accessToken) {
+      headers["Authorization"] = `Bearer ${storedToken.accessToken}`;
+    }
+    try {
+      await fetch(mcpServerUrl, {
+        method: "DELETE",
+        headers,
+        credentials: this.config.useCookies ? "include" : "omit"
+      });
+    } catch {
+    }
+    this.mcpSessions.set(mcpServerUrl, {
+      sessionId: null,
+      authStatus: session.authStatus
+    });
+  }
+  /** Initialize the MCP session for a specific server (required before tools/call) */
+  async initMcpSession(mcpServerUrl) {
+    const session = this.mcpSessions.get(mcpServerUrl);
+    if (session?.sessionId) return;
+    const headers = this.getMcpHeaders(mcpServerUrl);
+    await this.ensureServerAuthConfig(mcpServerUrl);
+    const token = await this.resolveToken(mcpServerUrl);
+    if (token) headers["Authorization"] = `Bearer ${token}`;
+    const initPayload = JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: DEFAULT_MCP_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "mcpstack-agent-sdk", version: "0.1.0" }
+      }
+    });
+    const initResponse = await fetch(mcpServerUrl, {
+      method: "POST",
+      headers,
+      credentials: this.config.useCookies ? "include" : "omit",
+      body: initPayload
+    });
+    if (initResponse.status === 401) {
+      this.clearOAuthToken(mcpServerUrl);
+      this.updateMcpAuthStatus(mcpServerUrl, "needs_auth");
+      const freshToken = await this.resolveToken(mcpServerUrl);
+      if (freshToken) {
+        headers["Authorization"] = `Bearer ${freshToken}`;
+        const retryResponse = await fetch(mcpServerUrl, {
+          method: "POST",
+          headers,
+          credentials: this.config.useCookies ? "include" : "omit",
+          body: initPayload
+        });
+        if (retryResponse.ok) {
+          const sessionId2 = retryResponse.headers.get("mcp-session-id");
+          this.mcpSessions.set(mcpServerUrl, { sessionId: sessionId2, authStatus: "connected" });
+          this.updateMcpAuthStatus(mcpServerUrl, "connected");
+          await retryResponse.text().catch(() => {
+          });
+          const notifyHeaders2 = this.getMcpHeaders(mcpServerUrl);
+          notifyHeaders2["Authorization"] = `Bearer ${freshToken}`;
+          await fetch(mcpServerUrl, {
+            method: "POST",
+            headers: notifyHeaders2,
+            credentials: this.config.useCookies ? "include" : "omit",
+            body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })
+          });
+          return;
+        }
+      }
+      throw new Error("MCP initialization failed (401): Authentication required");
+    }
+    if (!initResponse.ok) {
+      const errorText = await initResponse.text().catch(() => "MCP init error");
+      throw new Error(`MCP initialization failed (${initResponse.status}): ${errorText}`);
+    }
+    const sessionId = initResponse.headers.get("mcp-session-id");
+    this.mcpSessions.set(mcpServerUrl, { sessionId, authStatus: "connected" });
+    this.updateMcpAuthStatus(mcpServerUrl, "connected");
+    await initResponse.text().catch(() => {
+    });
+    const notifyHeaders = this.getMcpHeaders(mcpServerUrl);
+    if (token) notifyHeaders["Authorization"] = `Bearer ${token}`;
+    await fetch(mcpServerUrl, {
+      method: "POST",
+      headers: notifyHeaders,
+      credentials: this.config.useCookies ? "include" : "omit",
+      body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })
+    });
+  }
+  /** Update auth status for an MCP server and emit event */
+  updateMcpAuthStatus(mcpServerUrl, authStatus) {
+    const session = this.mcpSessions.get(mcpServerUrl);
+    if (session) {
+      session.authStatus = authStatus;
+    } else {
+      this.mcpSessions.set(mcpServerUrl, { sessionId: null, authStatus });
+    }
+    const serverInfo = this.agentConfig?.mcpServers?.find((s) => s.url === mcpServerUrl);
+    this.emit("mcp_auth_status", {
+      mcpServerUrl,
+      mcpServerName: serverInfo?.name ?? mcpServerUrl,
+      authStatus
+    });
+  }
+  /** Parse a JSON-RPC response from either JSON or SSE format */
+  async parseMcpResponse(response) {
+    const contentType = (response.headers.get("content-type") || "").toLowerCase();
+    if (contentType.includes("text/event-stream")) {
+      const text = await response.text();
+      const lines = text.split("\n");
+      let jsonData = "";
+      for (const line of lines) {
+        if (line.startsWith("data: ")) {
+          jsonData += line.slice(6);
+        }
+      }
+      if (!jsonData) {
+        throw new Error("No data received from MCP server SSE response");
+      }
+      return JSON.parse(jsonData);
+    }
+    return response.json();
+  }
+  // ================================================================
+  // Tool Execution
+  // ================================================================
+  async executeTool(toolCall) {
+    const isClientTool = toolCall.source === "client" || !toolCall.mcpServerUrl;
+    if (isClientTool && this.config.clientTools) {
+      const def = this.config.clientTools[toolCall.toolName];
+      if (def) {
+        const result2 = await def.execute(toolCall.arguments ?? {});
+        return result2;
+      }
+      throw new Error(`Unknown client tool: ${toolCall.toolName}`);
+    }
+    const mcpServerUrl = toolCall.mcpServerUrl || this.agentConfig?.mcpServerUrl;
+    if (!mcpServerUrl) {
+      throw new Error("No MCP server URL for tool call");
+    }
+    await this.initMcpSession(mcpServerUrl);
+    const token = await this.resolveToken(mcpServerUrl);
+    const headers = this.getMcpHeaders(mcpServerUrl);
+    if (token) headers["Authorization"] = `Bearer ${token}`;
+    const toolCallBody = JSON.stringify({
+      jsonrpc: "2.0",
+      id: 2,
+      method: "tools/call",
+      params: { name: toolCall.toolName, arguments: toolCall.arguments }
+    });
+    let response = await fetch(mcpServerUrl, {
+      method: "POST",
+      headers,
+      credentials: this.config.useCookies ? "include" : "omit",
+      body: toolCallBody,
+      signal: this.abortController?.signal
+    });
+    const session = this.mcpSessions.get(mcpServerUrl);
+    if (response.status === 404 && session?.sessionId) {
+      this.mcpSessions.set(mcpServerUrl, { ...session, sessionId: null });
+      await this.initMcpSession(mcpServerUrl);
+      const retryHeaders = this.getMcpHeaders(mcpServerUrl);
+      if (token) retryHeaders["Authorization"] = `Bearer ${token}`;
+      response = await fetch(mcpServerUrl, {
+        method: "POST",
+        headers: retryHeaders,
+        credentials: this.config.useCookies ? "include" : "omit",
+        body: toolCallBody,
+        signal: this.abortController?.signal
+      });
+    }
+    if (response.status === 401) {
+      this.clearOAuthToken(mcpServerUrl);
+      this.updateMcpAuthStatus(mcpServerUrl, "needs_auth");
+      const freshToken = await this.resolveToken(mcpServerUrl);
+      if (freshToken) {
+        const authHeaders = this.getMcpHeaders(mcpServerUrl);
+        authHeaders["Authorization"] = `Bearer ${freshToken}`;
+        response = await fetch(mcpServerUrl, {
+          method: "POST",
+          headers: authHeaders,
+          credentials: this.config.useCookies ? "include" : "omit",
+          body: toolCallBody,
+          signal: this.abortController?.signal
+        });
+        if (response.ok) {
+          this.updateMcpAuthStatus(mcpServerUrl, "connected");
+        }
+      }
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => "Authentication required");
+        throw new Error(`Tool execution failed (401): ${errorText}`);
+      }
+    }
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "MCP server error");
+      throw new Error(`Tool execution failed (${response.status}): ${errorText}`);
+    }
+    const currentSession = this.mcpSessions.get(mcpServerUrl);
+    if (currentSession?.authStatus === "needs_auth") {
+      this.updateMcpAuthStatus(mcpServerUrl, "connected");
+    }
+    const result = await this.parseMcpResponse(response);
+    if (result.error) {
+      throw new Error(`MCP error (${result.error.code}): ${result.error.message}`);
+    }
+    if (result.result?.content) {
+      const textContent = result.result.content.filter((c) => c.type === "text").map((c) => c.text).join("\n");
+      return textContent || result.result;
+    }
+    return result.result ?? result;
+  }
+};
+
+// src/app/types.ts
+var APP_AGENT_APPROVAL_ACTION = "requestApproval";
+var APP_AGENT_INPUT_ACTION = "requestInput";
+
+// src/app/presentation.ts
+function isAssistantMessage(message) {
+  return message.role === "assistant";
+}
+function isUserMessage(message) {
+  return message.role === "user";
+}
+function isErrorMessage(message) {
+  return message.role === "error";
+}
+function isToolCallMessage(message) {
+  return message.role === "tool_call";
+}
+function deriveVisibleMessages(messages) {
+  return messages.filter(
+    (message) => isAssistantMessage(message) || isUserMessage(message) || isErrorMessage(message) || isToolCallMessage(message)
+  );
+}
+function deriveConversationMessages(messages) {
+  return messages.filter(
+    (message) => isUserMessage(message) || isAssistantMessage(message) || isErrorMessage(message)
+  );
+}
+function deriveToolMessages(messages) {
+  return messages.filter(isToolCallMessage);
+}
+function getLatestAssistantMessage(messages) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message && isAssistantMessage(message)) {
+      return message;
+    }
+  }
+  return null;
+}
+function getLatestUserMessage(messages) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message && isUserMessage(message)) {
+      return message;
+    }
+  }
+  return null;
+}
+function getLatestToolMessage(messages) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message && isToolCallMessage(message)) {
+      return message;
+    }
+  }
+  return null;
+}
+function createInlinePendingTurnState(prompt, messages) {
+  return {
+    prompt,
+    baselineAssistantId: getLatestAssistantMessage(messages)?.id ?? null,
+    baselineToolCount: deriveToolMessages(messages).length
+  };
+}
+function applyUserMessageOverrides(messages, overrides) {
+  return messages.map(
+    (message) => message.role === "user" && overrides[message.id] ? { ...message, content: overrides[message.id] } : message
+  );
+}
+function buildRenderedNodes(messages) {
+  const nodes = [];
+  let toolBuffer = [];
+  const flushTools = (id) => {
+    if (toolBuffer.length > 0) {
+      nodes.push({ kind: "tools", id: `tools-${id}`, tools: toolBuffer });
+      toolBuffer = [];
+    }
+  };
+  messages.forEach((message) => {
+    if (isToolCallMessage(message)) {
+      toolBuffer.push(message);
+      return;
+    }
+    if (message.role === "tool_result") {
+      return;
+    }
+    flushTools(message.id);
+    if (message.role === "user") {
+      nodes.push({ kind: "user", id: message.id, content: message.content });
+      return;
+    }
+    if (message.role === "assistant") {
+      nodes.push({ kind: "assistant", id: message.id, content: message.content });
+    }
+  });
+  if (toolBuffer.length > 0) {
+    nodes.push({ kind: "tools", id: "tools-tail", tools: toolBuffer });
+  }
+  return nodes;
+}
+function deriveConversationStatusLabel(options) {
+  const {
+    isReady,
+    isLoading,
+    isThinking,
+    streamingContent,
+    hasError = false,
+    hasIssue = false,
+    hasAttention = false,
+    readyLabel = "Ready",
+    loadingLabel = "Working\u2026",
+    thinkingLabel = "Thinking\u2026",
+    streamingLabel = "Responding\u2026",
+    attentionLabel = "Needs auth",
+    issueLabel = "Needs attention",
+    reconnectingLabel = "Reconnecting\u2026",
+    connectingLabel = "Connecting\u2026"
+  } = options;
+  if (isReady) {
+    if (isLoading) {
+      return loadingLabel;
+    }
+    if (isThinking) {
+      return thinkingLabel;
+    }
+    if (streamingContent && streamingContent.length > 0) {
+      return streamingLabel;
+    }
+    if (hasAttention) {
+      return attentionLabel;
+    }
+    if (hasIssue || hasError) {
+      return issueLabel;
+    }
+    return readyLabel;
+  }
+  return hasIssue || hasError ? reconnectingLabel : connectingLabel;
+}
+function deriveLastTurnSummary(messages) {
+  const lastUser = getLatestUserMessage(messages);
+  if (!lastUser) {
+    return null;
+  }
+  const lastUserIndex = messages.findIndex((message) => message.id === lastUser.id);
+  if (lastUserIndex < 0) {
+    return null;
+  }
+  const after = messages.slice(lastUserIndex + 1);
+  const tools = deriveToolMessages(after);
+  const lastToolEndedAt = tools.map((tool) => (tool.toolCallDuration ?? 0) + (tool.timestamp ? tool.timestamp.getTime() : 0)).reduce((max, value) => max === null || value > max ? value : max, null);
+  const userStartedAt = lastUser.timestamp ? lastUser.timestamp.getTime() : null;
+  return {
+    prompt: lastUser.content.trim(),
+    toolsUsed: tools.length,
+    durationMs: lastToolEndedAt && userStartedAt ? Math.max(0, lastToolEndedAt - userStartedAt) : null
+  };
+}
+function deriveInlineFeedState(options) {
+  const {
+    pendingTurn,
+    toolMessages,
+    latestAssistantMessage,
+    streamingContent = "",
+    isLoading,
+    isThinking,
+    maxRecentTools = 4
+  } = options;
+  const startIndex = pendingTurn ? Math.max(
+    pendingTurn.baselineToolCount,
+    toolMessages.length - maxRecentTools
+  ) : Math.max(toolMessages.length - maxRecentTools, 0);
+  const recentTools = toolMessages.slice(startIndex);
+  const hasFreshAssistantReply = Boolean(
+    latestAssistantMessage && (!pendingTurn || latestAssistantMessage.id !== pendingTurn.baselineAssistantId)
+  );
+  const previewText = streamingContent || (hasFreshAssistantReply ? latestAssistantMessage.content : null);
+  const waitingForActivity = Boolean(pendingTurn) && recentTools.length === 0 && !streamingContent && (isLoading || isThinking);
+  const isActive = Boolean(isLoading || isThinking || streamingContent.length > 0);
+  return {
+    isActive,
+    pendingPrompt: pendingTurn?.prompt ?? null,
+    recentTools,
+    previewText,
+    waitingForActivity
+  };
+}
+
+// src/app/oauth.ts
+function normalizeOptionalValue(value) {
+  if (!value) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function isGatewayAuthorizeUrl(authorizationEndpoint) {
+  try {
+    const url = new URL(authorizationEndpoint);
+    return /\/api\/v1\/gateway\/[^/]+\/authorize$/i.test(url.pathname);
+  } catch {
+    return false;
+  }
+}
+function base64UrlEncode(bytes) {
+  return btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function randomToken(length) {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+async function createCodeChallenge(verifier) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(verifier);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return base64UrlEncode(new Uint8Array(hash));
+}
+function createPlatformAuthHandler(options) {
+  return async (_mcpServerUrl, authConfig) => {
+    if (!options.platform.auth) {
+      return void 0;
+    }
+    const authorizationEndpoint = authConfig.authorizationEndpoint ?? authConfig.loginUrl;
+    const tokenEndpoint = authConfig.tokenEndpoint ?? authConfig.tokenUrl;
+    const clientId = authConfig.clientId;
+    const redirectUri = authConfig.callbackUrl ?? options.oauthCallbackUrl;
+    if (!authorizationEndpoint || !tokenEndpoint || !clientId || !redirectUri) {
+      return void 0;
+    }
+    const verifier = await randomToken(48);
+    const state = await randomToken(24);
+    const challenge = await createCodeChallenge(verifier);
+    const authorizeUrl = new URL(authorizationEndpoint);
+    authorizeUrl.searchParams.set("response_type", "code");
+    authorizeUrl.searchParams.set("client_id", clientId);
+    authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+    authorizeUrl.searchParams.set("state", state);
+    authorizeUrl.searchParams.set("code_challenge", challenge);
+    authorizeUrl.searchParams.set("code_challenge_method", "S256");
+    if (authConfig.scopes?.length) {
+      authorizeUrl.searchParams.set("scope", authConfig.scopes.join(" "));
+    }
+    if (authConfig.resource) {
+      authorizeUrl.searchParams.set("resource", authConfig.resource);
+    }
+    if (options.userIdentity && isGatewayAuthorizeUrl(authorizationEndpoint)) {
+      const subject = normalizeOptionalValue(options.userIdentity.subject);
+      const email = normalizeOptionalValue(options.userIdentity.email);
+      const organizationId = normalizeOptionalValue(options.userIdentity.organizationId);
+      const displayName = normalizeOptionalValue(options.userIdentity.displayName);
+      if (subject) {
+        authorizeUrl.searchParams.set("mcpstack_host_subject", subject);
+      }
+      if (email) {
+        authorizeUrl.searchParams.set("mcpstack_host_email", email);
+      }
+      if (organizationId) {
+        authorizeUrl.searchParams.set("mcpstack_host_organization_id", organizationId);
+      }
+      if (displayName) {
+        authorizeUrl.searchParams.set("mcpstack_host_display_name", displayName);
+      }
+      authorizeUrl.searchParams.set("mcpstack_mismatch_policy", "block_with_switch");
+    }
+    const result = await options.platform.auth.openOAuthSession({
+      authorizeUrl: authorizeUrl.toString(),
+      redirectUri,
+      preferEphemeralSession: true
+    });
+    if (result.type !== "success" || !result.url) {
+      return void 0;
+    }
+    const callback = new URL(result.url);
+    const returnedState = callback.searchParams.get("state");
+    const code = callback.searchParams.get("code");
+    if (returnedState !== state || !code) {
+      const errorDescription = callback.searchParams.get("error_description");
+      const errorCode = callback.searchParams.get("error");
+      throw new Error(errorDescription ?? (errorCode ? `OAuth error: ${errorCode}` : "Could not complete OAuth login."));
+    }
+    const tokenResponse = await fetch(tokenEndpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        code,
+        code_verifier: verifier,
+        ...authConfig.resource ? { resource: authConfig.resource } : {}
+      }).toString()
+    });
+    const payload = await tokenResponse.json().catch(() => null);
+    if (!tokenResponse.ok) {
+      throw new Error(
+        payload?.error_description ?? payload?.error ?? `OAuth sign in failed (${tokenResponse.status}).`
+      );
+    }
+    return {
+      accessToken: payload?.access_token ?? payload?.accessToken,
+      refreshToken: payload?.refresh_token ?? payload?.refreshToken,
+      expiresIn: payload?.expires_in ?? payload?.expiresIn,
+      tokenType: payload?.token_type ?? payload?.tokenType,
+      resolvedAuthConfig: { ...authConfig, callbackUrl: redirectUri }
+    };
+  };
+}
+
+// src/app/platform.ts
+function createBrowserKeyValueStore(storage) {
+  const resolvedStorage = storage ?? (() => {
+    try {
+      return typeof localStorage === "undefined" ? null : localStorage;
+    } catch {
+      return null;
+    }
+  })();
+  return {
+    getItem(key) {
+      return resolvedStorage?.getItem(key) ?? null;
+    },
+    setItem(key, value) {
+      resolvedStorage?.setItem(key, value);
+    },
+    removeItem(key) {
+      resolvedStorage?.removeItem(key);
+    }
+  };
+}
+function createBrowserAppAgentPlatform(storage) {
+  return {
+    storage: {
+      durable: createBrowserKeyValueStore(storage)
+    }
+  };
+}
+async function resolveStoreValue(value) {
+  return await Promise.resolve(value);
+}
+
+// src/app/controller.ts
+function createId(prefix) {
+  return `${prefix}_${Date.now()}_${Math.random().toString(16).slice(2, 8)}`;
+}
+function normalizeSteps(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string" && entry.trim().length > 0) : [];
+}
+function normalizeInputFields(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((entry) => {
+    if (!entry || typeof entry !== "object") {
+      return [];
+    }
+    const record = entry;
+    const key = typeof record.key === "string" ? record.key.trim() : "";
+    const label = typeof record.label === "string" ? record.label.trim() : "";
+    const kind = typeof record.kind === "string" ? record.kind : "text";
+    if (!key || !label) {
+      return [];
+    }
+    return [{
+      key,
+      label,
+      kind: kind === "textarea" || kind === "number" || kind === "select" || kind === "boolean" ? kind : "text",
+      required: Boolean(record.required),
+      placeholder: typeof record.placeholder === "string" ? record.placeholder : void 0,
+      options: Array.isArray(record.options) ? record.options.flatMap((option) => {
+        if (!option || typeof option !== "object") {
+          return [];
+        }
+        const optionRecord = option;
+        const optionLabel = typeof optionRecord.label === "string" ? optionRecord.label.trim() : "";
+        const optionValue = typeof optionRecord.value === "string" ? optionRecord.value : "";
+        return optionLabel && optionValue ? [{ label: optionLabel, value: optionValue }] : [];
+      }) : void 0
+    }];
+  });
+}
+function isToolRoutingResetError(error) {
+  return error.code === "tool_routing_error" && /tool not found/i.test(error.message);
+}
+function mapConnections(agent) {
+  return agent.getMcpServers().map((server) => ({
+    url: server.url,
+    name: server.name,
+    authStatus: server.authStatus,
+    canSignOut: server.canSignOut
+  }));
+}
+function normalizeConnections(connections) {
+  if (!connections?.length) {
+    return [];
+  }
+  const byUrl = /* @__PURE__ */ new Map();
+  for (const connection of connections) {
+    const url = connection.url?.trim();
+    if (!url) {
+      continue;
+    }
+    byUrl.set(url, {
+      ...connection,
+      url,
+      name: connection.name?.trim() || url
+    });
+  }
+  return Array.from(byUrl.values());
+}
+function mergeConnections(runtimeConnections, existingConnections) {
+  const byUrl = /* @__PURE__ */ new Map();
+  for (const connection of existingConnections) {
+    byUrl.set(connection.url, connection);
+  }
+  for (const connection of runtimeConnections) {
+    byUrl.set(connection.url, connection);
+  }
+  return Array.from(byUrl.values());
+}
+var AppAgentController = class {
+  constructor(config) {
+    this.config = config;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.recoveredConversationIds = /* @__PURE__ */ new Set();
+    this.approvalResolvers = /* @__PURE__ */ new Map();
+    this.inputResolvers = /* @__PURE__ */ new Map();
+    this.pendingToolCallsByAction = /* @__PURE__ */ new Map();
+    this.lifecycleUnsubscribers = [];
+    this.userMessageDisplayOverrides = /* @__PURE__ */ new Map();
+    this.started = false;
+    this.disposed = false;
+    this.initializationPromise = null;
+    this.pendingDisplayText = null;
+    this.getSnapshot = () => this.snapshot;
+    this.handleMessage = (message) => {
+      if (message.role === "user" && this.pendingDisplayText) {
+        this.userMessageDisplayOverrides.set(message.id, this.pendingDisplayText);
+        this.pendingDisplayText = null;
+      }
+      this.setState((current) => ({
+        ...current,
+        conversation: {
+          ...current.conversation,
+          messages: [...current.conversation.messages, message],
+          id: this.agent.getConversationId(),
+          streamingContent: "",
+          hasOlderMessages: this.agent.getHasOlderMessages(),
+          pendingTurnSawActivity: current.conversation.pendingTurn ? true : current.conversation.pendingTurnSawActivity
+        }
+      }));
+      void this.persistResumeRecord();
+      this.finalizePendingTurnIfSettled();
+    };
+    this.handleContentDelta = (delta) => {
+      this.setState((current) => ({
+        ...current,
+        conversation: {
+          ...current.conversation,
+          streamingContent: current.conversation.streamingContent + delta.text,
+          pendingTurnSawActivity: current.conversation.pendingTurn ? true : current.conversation.pendingTurnSawActivity
+        }
+      }));
+    };
+    this.handleToolCall = (toolCall) => {
+      if (toolCall.toolName === APP_AGENT_APPROVAL_ACTION || toolCall.toolName === APP_AGENT_INPUT_ACTION) {
+        const queue = this.pendingToolCallsByAction.get(toolCall.toolName) ?? [];
+        queue.push(toolCall.toolCallId);
+        this.pendingToolCallsByAction.set(toolCall.toolName, queue);
+      }
+      this.setState((current) => ({
+        ...current,
+        conversation: {
+          ...current.conversation,
+          id: this.agent.getConversationId(),
+          messages: [
+            ...current.conversation.messages,
+            {
+              id: crypto.randomUUID(),
+              role: "tool_call",
+              content: `Calling ${toolCall.toolLabel ?? toolCall.toolName}...`,
+              toolName: toolCall.toolName,
+              toolLabel: toolCall.toolLabel,
+              toolCallId: toolCall.toolCallId,
+              timestamp: /* @__PURE__ */ new Date(),
+              toolCallStatus: "calling",
+              toolCallStartTime: Date.now()
+            }
+          ],
+          pendingTurnSawActivity: current.conversation.pendingTurn ? true : current.conversation.pendingTurnSawActivity
+        }
+      }));
+    };
+    this.handleToolResult = (data) => {
+      this.setState((current) => ({
+        ...current,
+        conversation: {
+          ...current.conversation,
+          messages: current.conversation.messages.map(
+            (message) => message.role === "tool_call" && message.toolCallId === data.toolCallId ? {
+              ...message,
+              toolCallStatus: "completed",
+              toolCallDuration: data.duration,
+              toolResult: typeof data.result === "string" ? data.result : JSON.stringify(data.result)
+            } : message
+          )
+        }
+      }));
+      this.finalizePendingTurnIfSettled();
+    };
+    this.handleToolError = (data) => {
+      this.setState((current) => ({
+        ...current,
+        conversation: {
+          ...current.conversation,
+          messages: current.conversation.messages.map(
+            (message) => message.role === "tool_call" && message.toolCallId === data.toolCallId ? {
+              ...message,
+              toolCallStatus: "error",
+              toolCallDuration: data.duration,
+              toolError: data.error
+            } : message
+          )
+        }
+      }));
+      this.finalizePendingTurnIfSettled();
+    };
+    this.handleThinking = (thinking) => {
+      this.setState((current) => ({
+        ...current,
+        conversation: {
+          ...current.conversation,
+          isThinking: thinking
+        }
+      }));
+      this.finalizePendingTurnIfSettled();
+    };
+    this.handleLoading = (loading) => {
+      this.setState((current) => ({
+        ...current,
+        conversation: {
+          ...current.conversation,
+          isLoading: loading,
+          error: loading ? null : current.conversation.error,
+          streamingContent: loading ? "" : current.conversation.streamingContent
+        }
+      }));
+      this.finalizePendingTurnIfSettled();
+    };
+    this.handleError = (error) => {
+      this.setState((current) => ({
+        ...current,
+        budget: error.budget ?? current.budget,
+        conversation: {
+          ...current.conversation,
+          error,
+          pendingTurn: null,
+          pendingTurnSawActivity: false
+        }
+      }));
+      if (isToolRoutingResetError(error)) {
+        const conversationId = this.agent.getConversationId();
+        if (conversationId && !this.recoveredConversationIds.has(conversationId)) {
+          this.recoveredConversationIds.add(conversationId);
+          void this.handleStaleConversation(error);
+          return;
+        }
+      }
+      this.setState((current) => ({
+        ...current,
+        conversation: {
+          ...current.conversation,
+          issue: {
+            code: "runtime_error",
+            message: error.message,
+            recoverable: false
+          }
+        }
+      }));
+    };
+    this.handleBudgetSnapshot = (budget) => {
+      this.setState((current) => ({
+        ...current,
+        budget
+      }));
+    };
+    this.handleMcpAuthStatus = () => {
+      this.setState((current) => ({
+        ...current,
+        connections: {
+          items: mergeConnections(mapConnections(this.agent), current.connections.items)
+        }
+      }));
+    };
+    this.handleAudioState = (voice) => {
+      this.setState((current) => ({
+        ...current,
+        voice
+      }));
+    };
+    this.platform = config.platform ?? createBrowserAppAgentPlatform();
+    const onAuthRequired = config.onAuthRequired ?? (!config.auth && this.platform.auth ? createPlatformAuthHandler({
+      platform: this.platform,
+      userIdentity: config.userIdentity,
+      oauthCallbackUrl: config.oauthCallbackUrl ?? ""
+    }) : void 0);
+    this.agent = new McpStackAgent({
+      apiKey: config.apiKey,
+      agentId: config.agentId,
+      agentServiceUrl: config.serviceUrl,
+      oauthCallbackUrl: config.oauthCallbackUrl,
+      oauthClientMetadataUrl: config.oauthClientMetadataUrl,
+      getAuthToken: config.getAuthToken,
+      authSessionKey: config.appSessionKey,
+      auth: config.auth,
+      embeddedAuth: config.userIdentity ? {
+        hostIdentity: config.userIdentity,
+        mismatchPolicy: "block_with_switch"
+      } : void 0,
+      useCookies: config.useCookies,
+      onAuthRequired,
+      externalUserId: config.externalUserId ?? config.userIdentity?.subject ?? config.userIdentity?.email,
+      context: config.appContext,
+      clientTools: this.buildClientTools(config.clientTools),
+      conversationHistoryPageSize: config.conversation?.historyPageSize ?? 50,
+      storage: config.storage
+    });
+    this.state = {
+      runtime: {
+        agentConfig: null
+      },
+      conversation: {
+        id: null,
+        messages: [],
+        streamingContent: "",
+        pendingTurn: null,
+        pendingTurnSawActivity: false,
+        statusLabel: "Connecting\u2026",
+        resumeKey: this.getResumeStorageKey(),
+        isReady: false,
+        isLoading: false,
+        isLoadingHistory: false,
+        isThinking: false,
+        hasOlderMessages: false,
+        error: null,
+        issue: null
+      },
+      connections: {
+        items: normalizeConnections(config.initialConnections)
+      },
+      approvals: {
+        pending: []
+      },
+      requests: {
+        pending: []
+      },
+      feedback: {
+        isSubmitting: false,
+        error: null,
+        lastSubmittedAt: null,
+        lastFeedback: null
+      },
+      voice: this.agent.getAudioInputState(),
+      budget: this.agent.getBudgetSnapshot()
+    };
+    this.recomputeDerivedState();
+    this.snapshot = this.buildSnapshot();
+  }
+  getAgent() {
+    return this.agent;
+  }
+  buildSnapshot() {
+    const messages = applyUserMessageOverrides(
+      this.state.conversation.messages,
+      Object.fromEntries(this.userMessageDisplayOverrides)
+    );
+    const visibleMessages = deriveVisibleMessages(messages);
+    const conversationMessages = deriveConversationMessages(messages);
+    const toolMessages = deriveToolMessages(visibleMessages);
+    const latestAssistantMessage = getLatestAssistantMessage(visibleMessages);
+    const latestToolMessage = getLatestToolMessage(toolMessages);
+    const latestUserMessage = getLatestUserMessage(visibleMessages);
+    const lastTurn = deriveLastTurnSummary(messages);
+    const renderedNodes = buildRenderedNodes(messages);
+    const inlineFeed = deriveInlineFeedState({
+      pendingTurn: this.state.conversation.pendingTurn,
+      toolMessages,
+      latestAssistantMessage: latestAssistantMessage ? { id: latestAssistantMessage.id, content: latestAssistantMessage.content } : null,
+      streamingContent: this.state.conversation.streamingContent,
+      isLoading: this.state.conversation.isLoading,
+      isThinking: this.state.conversation.isThinking
+    });
+    return {
+      runtime: {
+        agent: this.agent,
+        agentConfig: this.state.runtime.agentConfig
+      },
+      conversation: {
+        ...this.state.conversation,
+        messages,
+        visibleMessages,
+        conversationMessages,
+        toolMessages,
+        renderedNodes,
+        latestAssistantMessage,
+        latestToolMessage,
+        latestUserMessage,
+        lastTurn,
+        pendingTurn: this.state.conversation.pendingTurn,
+        inlineFeed
+      },
+      connections: {
+        ...this.state.connections,
+        needsAttention: this.state.connections.items.some((item) => item.authStatus === "needs_auth")
+      },
+      approvals: {
+        pending: this.state.approvals.pending
+      },
+      requests: {
+        pending: this.state.requests.pending
+      },
+      feedback: this.state.feedback,
+      budget: this.state.budget,
+      voice: this.state.voice
+    };
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  start() {
+    if (this.started || this.disposed) {
+      return;
+    }
+    this.started = true;
+    this.bindLifecycleSignals();
+    this.bindRuntimeEvents();
+    this.initializationPromise = this.initialize();
+  }
+  dispose() {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.started = false;
+    this.agent.off("message", this.handleMessage);
+    this.agent.off("content_delta", this.handleContentDelta);
+    this.agent.off("tool_call", this.handleToolCall);
+    this.agent.off("tool_result", this.handleToolResult);
+    this.agent.off("tool_error", this.handleToolError);
+    this.agent.off("thinking", this.handleThinking);
+    this.agent.off("loading", this.handleLoading);
+    this.agent.off("error", this.handleError);
+    this.agent.off("mcp_auth_status", this.handleMcpAuthStatus);
+    this.agent.off("audio_state", this.handleAudioState);
+    this.lifecycleUnsubscribers.splice(0).forEach((unsubscribe) => unsubscribe());
+    this.agent.cancelVoiceInput();
+    this.agent.cancel();
+    this.approvalResolvers.clear();
+    this.inputResolvers.clear();
+    this.listeners.clear();
+  }
+  updateDynamicConfig(config) {
+    this.config = {
+      ...this.config,
+      ...config
+    };
+    this.agent.setAppContext(this.config.appContext);
+    this.agent.setClientTools(this.buildClientTools(this.config.clientTools));
+  }
+  setAuthRequiredHandler(onAuthRequired) {
+    this.config = {
+      ...this.config,
+      onAuthRequired
+    };
+    this.agent.setOnAuthRequired(onAuthRequired);
+  }
+  async send(prompt, options) {
+    const trimmed = prompt.trim();
+    if (!trimmed) {
+      return;
+    }
+    const displayText = (options?.displayText ?? trimmed).trim() || trimmed;
+    this.pendingDisplayText = displayText;
+    this.setState((current) => ({
+      ...current,
+      conversation: {
+        ...current.conversation,
+        pendingTurn: createInlinePendingTurnState(displayText, current.conversation.messages),
+        pendingTurnSawActivity: false,
+        issue: null
+      }
+    }));
+    try {
+      await this.agent.sendMessage(trimmed);
+    } catch (error) {
+      this.pendingDisplayText = null;
+      const message = error instanceof Error ? error.message : "Could not send message.";
+      this.setState((current) => ({
+        ...current,
+        conversation: {
+          ...current.conversation,
+          pendingTurn: null,
+          pendingTurnSawActivity: false,
+          error: {
+            code: "send_message_error",
+            message
+          },
+          issue: {
+            code: "runtime_error",
+            message,
+            recoverable: false
+          }
+        }
+      }));
+      throw error;
+    }
+  }
+  cancel() {
+    this.agent.cancel();
+  }
+  async startVoiceInput() {
+    await this.agent.startVoiceInput();
+  }
+  async stopVoiceInput() {
+    await this.agent.stopVoiceInput();
+  }
+  cancelVoiceInput() {
+    this.agent.cancelVoiceInput();
+  }
+  async loadMore() {
+    this.setState((current) => ({
+      ...current,
+      conversation: {
+        ...current.conversation,
+        isLoadingHistory: true
+      }
+    }));
+    try {
+      const page = await this.agent.loadOlderMessages();
+      if (!page) {
+        return;
+      }
+      this.syncFromRuntime();
+    } finally {
+      this.setState((current) => ({
+        ...current,
+        conversation: {
+          ...current.conversation,
+          isLoadingHistory: false
+        }
+      }));
+    }
+  }
+  async resetConversation() {
+    this.agent.newConversation();
+    await this.clearResumeRecord();
+    this.recoveredConversationIds.clear();
+    this.pendingToolCallsByAction.clear();
+    this.approvalResolvers.clear();
+    this.inputResolvers.clear();
+    this.userMessageDisplayOverrides.clear();
+    this.pendingDisplayText = null;
+    this.setState((current) => ({
+      ...current,
+      conversation: {
+        ...current.conversation,
+        id: null,
+        messages: [],
+        streamingContent: "",
+        pendingTurn: null,
+        pendingTurnSawActivity: false,
+        hasOlderMessages: false,
+        error: null,
+        issue: null
+      },
+      approvals: {
+        pending: []
+      },
+      requests: {
+        pending: []
+      }
+    }));
+  }
+  async connect(serverUrl) {
+    await this.ensureInitialized();
+    const result = await this.agent.authenticate(serverUrl);
+    this.setState((current) => ({
+      ...current,
+      connections: {
+        items: mergeConnections(mapConnections(this.agent), current.connections.items)
+      },
+      budget: this.agent.getBudgetSnapshot()
+    }));
+    return result;
+  }
+  async disconnect(serverUrl) {
+    await this.agent.signOutMcpServer(serverUrl);
+    this.setState((current) => ({
+      ...current,
+      connections: {
+        items: mergeConnections(mapConnections(this.agent), current.connections.items)
+      }
+    }));
+  }
+  async submitFeedback(input) {
+    this.setState((current) => ({
+      ...current,
+      feedback: {
+        ...current.feedback,
+        isSubmitting: true,
+        error: null
+      }
+    }));
+    try {
+      const feedback = await this.agent.submitFeedback({
+        ...input,
+        source: this.config.feedbackSource ?? "app-agent"
+      });
+      this.setState((current) => ({
+        ...current,
+        feedback: {
+          isSubmitting: false,
+          error: null,
+          lastSubmittedAt: feedback.createdAt,
+          lastFeedback: feedback
+        }
+      }));
+      return feedback;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Could not save feedback.";
+      this.setState((current) => ({
+        ...current,
+        feedback: {
+          ...current.feedback,
+          isSubmitting: false,
+          error: message
+        }
+      }));
+      throw error;
+    }
+  }
+  resolveApproval(id, approved) {
+    const resolver = this.approvalResolvers.get(id);
+    if (!resolver) {
+      return;
+    }
+    this.approvalResolvers.delete(id);
+    this.setState((current) => ({
+      ...current,
+      approvals: {
+        pending: current.approvals.pending.filter((approval) => approval.id !== id)
+      }
+    }));
+    resolver.resolve({ approved });
+  }
+  submitRequest(id, values) {
+    const resolver = this.inputResolvers.get(id);
+    if (!resolver) {
+      return;
+    }
+    this.inputResolvers.delete(id);
+    this.setState((current) => ({
+      ...current,
+      requests: {
+        pending: current.requests.pending.filter((request) => request.id !== id)
+      }
+    }));
+    resolver.resolve({ submitted: true, values });
+  }
+  cancelRequest(id) {
+    const resolver = this.inputResolvers.get(id);
+    if (!resolver) {
+      return;
+    }
+    this.inputResolvers.delete(id);
+    this.setState((current) => ({
+      ...current,
+      requests: {
+        pending: current.requests.pending.filter((request) => request.id !== id)
+      }
+    }));
+    resolver.resolve({ submitted: false });
+  }
+  async initialize() {
+    try {
+      const agentConfig = await this.agent.init();
+      if (this.disposed) {
+        return;
+      }
+      this.setState((current) => ({
+        ...current,
+        runtime: {
+          agentConfig
+        },
+        conversation: {
+          ...current.conversation,
+          isReady: true
+        },
+        connections: {
+          items: mergeConnections(mapConnections(this.agent), current.connections.items)
+        },
+        budget: this.agent.getBudgetSnapshot()
+      }));
+      const resumeRecord = await this.readResumeRecord();
+      if (resumeRecord && resumeRecord.agentId === this.config.agentId && resumeRecord.appSessionKey === (this.config.appSessionKey ?? null) && resumeRecord.conversationResumeVersion === agentConfig.conversationResumeVersion) {
+        this.setState((current) => ({
+          ...current,
+          conversation: {
+            ...current.conversation,
+            isLoadingHistory: true
+          }
+        }));
+        try {
+          await this.agent.loadConversation(
+            resumeRecord.conversationId,
+            this.config.conversation?.historyPageSize ?? 50
+          );
+        } catch (error) {
+          this.setState((current) => ({
+            ...current,
+            conversation: {
+              ...current.conversation,
+              error: {
+                code: "conversation_history_error",
+                message: error instanceof Error ? error.message : "Failed to load conversation history."
+              }
+            }
+          }));
+          await this.clearResumeRecord();
+        } finally {
+          this.syncFromRuntime();
+          this.setState((current) => ({
+            ...current,
+            conversation: {
+              ...current.conversation,
+              isLoadingHistory: false
+            }
+          }));
+        }
+      } else {
+        this.syncFromRuntime();
+      }
+    } catch (error) {
+      const message = error instanceof Error && error.message.trim() ? error.message.trim() : "Failed to load agent configuration.";
+      this.setState((current) => ({
+        ...current,
+        conversation: {
+          ...current.conversation,
+          error: {
+            code: /api key|unauthorized|401/i.test(message) ? "agent_config_auth_error" : "agent_config_error",
+            message
+          },
+          issue: {
+            code: "config_error",
+            message,
+            recoverable: false
+          }
+        }
+      }));
+    }
+  }
+  async ensureInitialized() {
+    if (this.state.runtime.agentConfig) {
+      return;
+    }
+    this.initializationPromise ?? (this.initializationPromise = this.initialize());
+    await this.initializationPromise;
+  }
+  bindRuntimeEvents() {
+    this.agent.on("message", this.handleMessage);
+    this.agent.on("content_delta", this.handleContentDelta);
+    this.agent.on("tool_call", this.handleToolCall);
+    this.agent.on("tool_result", this.handleToolResult);
+    this.agent.on("tool_error", this.handleToolError);
+    this.agent.on("thinking", this.handleThinking);
+    this.agent.on("loading", this.handleLoading);
+    this.agent.on("error", this.handleError);
+    this.agent.on("mcp_auth_status", this.handleMcpAuthStatus);
+    this.agent.on("audio_state", this.handleAudioState);
+    this.agent.on("budget_snapshot", this.handleBudgetSnapshot);
+  }
+  async handleStaleConversation(error) {
+    await this.clearResumeRecord();
+    this.agent.newConversation();
+    this.pendingToolCallsByAction.clear();
+    this.approvalResolvers.clear();
+    this.inputResolvers.clear();
+    this.userMessageDisplayOverrides.clear();
+    this.pendingDisplayText = null;
+    this.setState((current) => ({
+      ...current,
+      conversation: {
+        ...current.conversation,
+        id: null,
+        messages: [],
+        streamingContent: "",
+        pendingTurn: null,
+        pendingTurnSawActivity: false,
+        hasOlderMessages: false,
+        issue: {
+          code: "stale_conversation",
+          message: error.message,
+          recoverable: true
+        }
+      },
+      approvals: {
+        pending: []
+      },
+      requests: {
+        pending: []
+      }
+    }));
+  }
+  bindLifecycleSignals() {
+    const lifecycle = this.platform.lifecycle;
+    if (!lifecycle) {
+      return;
+    }
+    const foregroundUnsubscribe = lifecycle.onForegroundChange?.(() => {
+      this.emit();
+    });
+    if (foregroundUnsubscribe) {
+      this.lifecycleUnsubscribers.push(foregroundUnsubscribe);
+    }
+    const connectivityUnsubscribe = lifecycle.onConnectivityChange?.(() => {
+      this.emit();
+    });
+    if (connectivityUnsubscribe) {
+      this.lifecycleUnsubscribers.push(connectivityUnsubscribe);
+    }
+  }
+  buildClientTools(clientTools) {
+    const approvalAction = {
+      description: "Ask the host app to approve a multi-step plan before you continue.",
+      selection: {
+        categories: ["approval"],
+        alwaysInclude: true,
+        risk: "medium"
+      },
+      parameters: {
+        title: { type: "string", description: "Short title for the approval request.", required: true },
+        rationale: { type: "string", description: "Optional reason for the plan." },
+        steps: { type: "array", description: "Ordered steps that need approval.", required: true },
+        confirmLabel: { type: "string", description: "Optional label for the approve action." },
+        cancelLabel: { type: "string", description: "Optional label for the reject action." }
+      },
+      execute: async (params) => {
+        const approvalId = createId("approval");
+        const toolCallId = this.shiftPendingToolCallId(APP_AGENT_APPROVAL_ACTION);
+        const approval = {
+          id: approvalId,
+          title: typeof params.title === "string" ? params.title : "Approval required",
+          rationale: typeof params.rationale === "string" ? params.rationale : void 0,
+          steps: normalizeSteps(params.steps),
+          toolCallId,
+          confirmLabel: typeof params.confirmLabel === "string" ? params.confirmLabel : void 0,
+          cancelLabel: typeof params.cancelLabel === "string" ? params.cancelLabel : void 0
+        };
+        this.setState((current) => ({
+          ...current,
+          approvals: {
+            pending: [...current.approvals.pending, approval]
+          }
+        }));
+        return await new Promise((resolve) => {
+          this.approvalResolvers.set(approvalId, { resolve });
+        });
+      }
+    };
+    return {
+      ...clientTools ?? {},
+      [APP_AGENT_APPROVAL_ACTION]: {
+        ...approvalAction
+      },
+      [APP_AGENT_INPUT_ACTION]: {
+        description: "Ask the host app for structured user input before you continue.",
+        selection: {
+          categories: ["approval"],
+          alwaysInclude: true,
+          risk: "medium"
+        },
+        parameters: {
+          title: { type: "string", description: "Short title for the input request.", required: true },
+          prompt: { type: "string", description: "Optional explainer shown above the fields." },
+          fields: { type: "array", description: "Structured fields to collect.", required: true },
+          submitLabel: { type: "string", description: "Optional submit button label." },
+          cancelLabel: { type: "string", description: "Optional cancel button label." }
+        },
+        execute: async (params) => {
+          const requestId = createId("input");
+          const toolCallId = this.shiftPendingToolCallId(APP_AGENT_INPUT_ACTION);
+          const request = {
+            id: requestId,
+            title: typeof params.title === "string" ? params.title : "Input required",
+            prompt: typeof params.prompt === "string" ? params.prompt : void 0,
+            fields: normalizeInputFields(params.fields),
+            toolCallId,
+            submitLabel: typeof params.submitLabel === "string" ? params.submitLabel : void 0,
+            cancelLabel: typeof params.cancelLabel === "string" ? params.cancelLabel : void 0
+          };
+          this.setState((current) => ({
+            ...current,
+            requests: {
+              pending: [...current.requests.pending, request]
+            }
+          }));
+          return await new Promise((resolve) => {
+            this.inputResolvers.set(requestId, { resolve });
+          });
+        }
+      }
+    };
+  }
+  shiftPendingToolCallId(actionName) {
+    const queue = this.pendingToolCallsByAction.get(actionName) ?? [];
+    const next = queue.shift() ?? null;
+    if (queue.length === 0) {
+      this.pendingToolCallsByAction.delete(actionName);
+    } else {
+      this.pendingToolCallsByAction.set(actionName, queue);
+    }
+    return next;
+  }
+  syncFromRuntime() {
+    this.setState((current) => ({
+      ...current,
+      conversation: {
+        ...current.conversation,
+        id: this.agent.getConversationId(),
+        messages: this.agent.getMessages(),
+        hasOlderMessages: this.agent.getHasOlderMessages()
+      },
+      connections: {
+        items: mergeConnections(mapConnections(this.agent), current.connections.items)
+      }
+    }));
+    void this.persistResumeRecord();
+  }
+  finalizePendingTurnIfSettled() {
+    const current = this.state.conversation;
+    if (current.pendingTurn && current.pendingTurnSawActivity && !current.isLoading && !current.isThinking && !current.streamingContent) {
+      this.setState((state) => ({
+        ...state,
+        conversation: {
+          ...state.conversation,
+          pendingTurn: null,
+          pendingTurnSawActivity: false
+        }
+      }));
+    }
+  }
+  getResumeStorageKey() {
+    const durable = this.platform.storage?.durable;
+    if (!durable) {
+      return null;
+    }
+    const namespace = this.config.conversation?.namespace ?? "mcpstack.app-agent.resume";
+    const sessionKey = this.config.appSessionKey?.trim() || "anonymous";
+    return `${namespace}:${this.config.agentId}:${sessionKey}`;
+  }
+  async readResumeRecord() {
+    const durable = this.platform.storage?.durable;
+    const resumeKey = this.getResumeStorageKey();
+    if (!durable || !resumeKey) {
+      return null;
+    }
+    try {
+      const raw = await resolveStoreValue(durable.getItem(resumeKey));
+      if (!raw) {
+        return null;
+      }
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  async persistResumeRecord() {
+    const durable = this.platform.storage?.durable;
+    const resumeKey = this.getResumeStorageKey();
+    const conversationId = this.agent.getConversationId();
+    const agentConfig = this.state.runtime.agentConfig;
+    if (!durable || !resumeKey || !conversationId || !agentConfig) {
+      return;
+    }
+    const record = {
+      conversationId,
+      agentId: this.config.agentId,
+      appSessionKey: this.config.appSessionKey ?? null,
+      conversationResumeVersion: agentConfig.conversationResumeVersion,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    try {
+      await resolveStoreValue(durable.setItem(resumeKey, JSON.stringify(record)));
+    } catch {
+    }
+  }
+  async clearResumeRecord() {
+    const durable = this.platform.storage?.durable;
+    const resumeKey = this.getResumeStorageKey();
+    if (!durable || !resumeKey) {
+      return;
+    }
+    try {
+      await resolveStoreValue(durable.removeItem(resumeKey));
+    } catch {
+    }
+  }
+  setState(update) {
+    if (this.disposed) {
+      return;
+    }
+    this.state = update(this.state);
+    this.recomputeDerivedState();
+    this.snapshot = this.buildSnapshot();
+    this.emit();
+  }
+  recomputeDerivedState() {
+    const hasAttention = this.state.connections.items.some((item) => item.authStatus === "needs_auth");
+    this.state.conversation.statusLabel = deriveConversationStatusLabel({
+      isReady: this.state.conversation.isReady,
+      isLoading: this.state.conversation.isLoading,
+      isThinking: this.state.conversation.isThinking,
+      streamingContent: this.state.conversation.streamingContent,
+      hasError: this.state.conversation.error != null,
+      hasIssue: this.state.conversation.issue != null,
+      hasAttention
+    });
+    this.state.conversation.resumeKey = this.getResumeStorageKey();
+  }
+  emit() {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+};
+
+// src/framework/useAppAgentBinding.tsx
+function useAppAgentBinding(config, options, auth = {}) {
+  const enabled = options?.enabled ?? true;
+  const disposeTimerRef = useRef(null);
+  const controller = useMemo(() => new AppAgentController({
+    ...config,
+    onAuthRequired: auth.onAuthRequired ?? config.onAuthRequired
+  }), [
+    auth.onAuthRequired,
+    config.agentId,
+    config.apiKey,
+    config.appSessionKey,
+    config.auth?.appId,
+    config.auth?.getToken,
+    config.auth?.mode,
+    config.conversation?.historyPageSize,
+    config.conversation?.namespace,
+    config.externalUserId,
+    config.getAuthToken,
+    config.oauthCallbackUrl,
+    config.oauthClientMetadataUrl,
+    config.onAuthRequired,
+    config.platform,
+    config.serviceUrl,
+    config.storage,
+    config.useCookies,
+    config.userIdentity?.subject,
+    enabled
+  ]);
+  useEffect(() => {
+    if (disposeTimerRef.current) {
+      clearTimeout(disposeTimerRef.current);
+      disposeTimerRef.current = null;
+    }
+    return () => {
+      disposeTimerRef.current = setTimeout(() => {
+        controller.dispose();
+        disposeTimerRef.current = null;
+      }, 0);
+    };
+  }, [controller]);
+  useEffect(() => {
+    controller.updateDynamicConfig({
+      appContext: config.appContext,
+      clientTools: config.clientTools,
+      feedbackSource: config.feedbackSource
+    });
+  }, [config.appContext, config.clientTools, config.feedbackSource, controller]);
+  useEffect(() => {
+    controller.setAuthRequiredHandler(auth.onAuthRequired ?? config.onAuthRequired);
+  }, [auth.onAuthRequired, config.onAuthRequired, controller]);
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    controller.start();
+  }, [controller, enabled]);
+  const snapshot = useSyncExternalStore(
+    controller.subscribe.bind(controller),
+    controller.getSnapshot,
+    controller.getSnapshot
+  );
+  return {
+    controller,
+    runtime: snapshot.runtime,
+    conversation: {
+      ...snapshot.conversation,
+      loadMore: () => controller.loadMore(),
+      reset: () => controller.resetConversation()
+    },
+    composer: {
+      send: (prompt, sendOptions) => controller.send(prompt, sendOptions),
+      cancel: () => controller.cancel()
+    },
+    connections: {
+      ...snapshot.connections,
+      connect: (serverUrl) => controller.connect(serverUrl),
+      disconnect: (serverUrl) => controller.disconnect(serverUrl)
+    },
+    approvals: {
+      ...snapshot.approvals,
+      resolve: (id, approved) => controller.resolveApproval(id, approved)
+    },
+    requests: {
+      ...snapshot.requests,
+      submit: (id, values) => controller.submitRequest(id, values),
+      cancel: (id) => controller.cancelRequest(id)
+    },
+    feedback: {
+      ...snapshot.feedback,
+      submit: (input) => controller.submitFeedback(input)
+    },
+    budget: snapshot.budget,
+    voice: {
+      ...snapshot.voice,
+      start: () => controller.startVoiceInput(),
+      stop: () => controller.stopVoiceInput(),
+      cancel: () => controller.cancelVoiceInput()
+    },
+    popupAuthState: auth.popupAuthState ?? null,
+    startOrRetryPopupAuth: auth.startOrRetryPopupAuth ?? (() => void 0),
+    cancelPopupAuth: auth.cancelPopupAuth ?? (() => void 0)
+  };
+}
+
+// src/react/usePopupOAuthController.ts
+import { useCallback, useEffect as useEffect2, useMemo as useMemo2, useRef as useRef2, useState } from "react";
+var OAUTH_CALLBACK_CHANNEL_NAME = "mcpstack-oauth";
+var OAUTH_CALLBACK_STORAGE_PREFIX = "mcpstack-oauth-callback:";
+function generateCodeVerifier() {
+  const array = new Uint8Array(32);
+  crypto.getRandomValues(array);
+  return btoa(String.fromCharCode(...array)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function generateCodeChallenge(verifier) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(verifier);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return btoa(String.fromCharCode(...new Uint8Array(hash))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function createPopupState(request, phase, statusMessage, errorMessage) {
+  return {
+    serverName: request.serverName,
+    serverUrl: request.serverUrl,
+    phase,
+    statusMessage: statusMessage ?? null,
+    errorMessage: errorMessage ?? null,
+    hostIdentityLabel: request.hostIdentityLabel ?? null
+  };
+}
+function normalizeOptionalValue2(value) {
+  if (!value) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function formatUserIdentityLabel(identity) {
+  if (!identity) {
+    return null;
+  }
+  return normalizeOptionalValue2(identity.displayName) ?? normalizeOptionalValue2(identity.email) ?? normalizeOptionalValue2(identity.subject) ?? null;
+}
+function isGatewayAuthorizeUrl2(authConfig) {
+  const loginUrl = authConfig.authorizationEndpoint ?? authConfig.loginUrl;
+  if (!loginUrl) {
+    return false;
+  }
+  try {
+    const url = new URL(loginUrl);
+    return /\/api\/v1\/gateway\/[^/]+\/authorize$/i.test(url.pathname);
+  } catch {
+    return false;
+  }
+}
+function usePopupOAuthController(options) {
+  const [popupState, setPopupState] = useState(null);
+  const popupStateRef = useRef2(null);
+  const activeRequestRef = useRef2(null);
+  const mountedRef = useRef2(true);
+  const optionsRef = useRef2(options);
+  const authSessionKeyRef = useRef2(normalizeAuthSessionKey(options.appSessionKey));
+  useEffect2(() => {
+    popupStateRef.current = popupState;
+  }, [popupState]);
+  useEffect2(() => {
+    optionsRef.current = options;
+  }, [options]);
+  const getCallbackUrl = useCallback((config) => config.callbackUrl ?? optionsRef.current.oauthCallbackUrl, []);
+  const clearStoredCallbackPayload = useCallback((state) => {
+    if (!state) {
+      return;
+    }
+    try {
+      localStorage.removeItem(`${OAUTH_CALLBACK_STORAGE_PREFIX}${state}`);
+    } catch {
+    }
+  }, []);
+  const clearPollTimer = useCallback((request) => {
+    if (request?.pollTimer) {
+      clearInterval(request.pollTimer);
+      request.pollTimer = void 0;
+    }
+  }, []);
+  const dismissPopupState = useCallback((serverUrl) => {
+    if (!mountedRef.current) {
+      return;
+    }
+    if (!popupStateRef.current && !activeRequestRef.current) {
+      return;
+    }
+    setPopupState((currentState) => {
+      if (!currentState) {
+        popupStateRef.current = null;
+        return null;
+      }
+      if (!serverUrl || currentState.serverUrl === serverUrl) {
+        popupStateRef.current = null;
+        return null;
+      }
+      return currentState;
+    });
+  }, []);
+  const closePopupWindow = useCallback((request) => {
+    if (request?.popupWindow && !request.popupWindow.closed) {
+      request.popupWindow.close();
+    }
+    if (request) {
+      request.popupWindow = null;
+    }
+  }, []);
+  useEffect2(() => {
+    const previousAuthSessionKey = authSessionKeyRef.current;
+    const nextAuthSessionKey = normalizeAuthSessionKey(options.appSessionKey);
+    authSessionKeyRef.current = nextAuthSessionKey;
+    if (previousAuthSessionKey === nextAuthSessionKey) {
+      return;
+    }
+    const request = activeRequestRef.current;
+    if (!request) {
+      if (mountedRef.current) {
+        setPopupState(null);
+      }
+      return;
+    }
+    clearPollTimer(request);
+    closePopupWindow(request);
+    clearStoredCallbackPayload(request.state);
+    activeRequestRef.current = null;
+    request.resolve(void 0);
+    if (mountedRef.current) {
+      setPopupState(null);
+    }
+  }, [
+    clearPollTimer,
+    clearStoredCallbackPayload,
+    closePopupWindow,
+    options.appSessionKey
+  ]);
+  const resolveAndClearActiveRequest = useCallback((tokenResponse) => {
+    const request = activeRequestRef.current;
+    if (!request) {
+      dismissPopupState();
+      return;
+    }
+    clearPollTimer(request);
+    closePopupWindow(request);
+    clearStoredCallbackPayload(request.state);
+    activeRequestRef.current = null;
+    request.resolve(tokenResponse);
+    dismissPopupState(request.serverUrl);
+  }, [clearPollTimer, clearStoredCallbackPayload, closePopupWindow, dismissPopupState]);
+  const transitionActiveRequest = useCallback((phase, errorMessage, statusMessage) => {
+    const request = activeRequestRef.current;
+    if (!request) {
+      return;
+    }
+    clearPollTimer(request);
+    closePopupWindow(request);
+    request.handledCallback = false;
+    if (mountedRef.current) {
+      setPopupState(createPopupState(request, phase, statusMessage, errorMessage));
+    }
+  }, [clearPollTimer, closePopupWindow]);
+  const setActivePopupPhase = useCallback((phase, errorMessage, statusMessage) => {
+    const request = activeRequestRef.current;
+    if (!request) {
+      return;
+    }
+    clearPollTimer(request);
+    closePopupWindow(request);
+    if (mountedRef.current) {
+      setPopupState(createPopupState(request, phase, statusMessage, errorMessage));
+    }
+  }, [clearPollTimer, closePopupWindow]);
+  const exchangeCodeForToken = useCallback(async (code) => {
+    const request = activeRequestRef.current;
+    if (!request) {
+      return;
+    }
+    const effectiveAuthConfig = request.resolvedAuthConfig;
+    const callbackUrl = getCallbackUrl(effectiveAuthConfig);
+    const tokenUrl = effectiveAuthConfig.tokenEndpoint ?? effectiveAuthConfig.tokenUrl;
+    if (!tokenUrl) {
+      request.handledCallback = false;
+      transitionActiveRequest("error", "This MCP server is missing a token endpoint.");
+      return;
+    }
+    if (mountedRef.current) {
+      setPopupState(
+        createPopupState(
+          request,
+          "exchanging",
+          "Exchanging authorization code..."
+        )
+      );
+    }
+    try {
+      const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        code_verifier: request.codeVerifier,
+        redirect_uri: callbackUrl
+      });
+      if (effectiveAuthConfig.clientId) {
+        body.set("client_id", effectiveAuthConfig.clientId);
+      }
+      if (effectiveAuthConfig.resource) {
+        body.set("resource", effectiveAuthConfig.resource);
+      }
+      const response = await fetch(tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body
+      });
+      if (response.ok) {
+        const data = await response.json();
+        if (data.access_token) {
+          resolveAndClearActiveRequest({
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token,
+            expiresIn: data.expires_in,
+            tokenType: data.token_type,
+            resolvedAuthConfig: effectiveAuthConfig
+          });
+          return;
+        }
+      }
+      const errorMessage = await response.text().catch(() => "Token exchange failed.");
+      if (effectiveAuthConfig.clientMode === "dcr") {
+        clearStoredRegistration(
+          buildRegistrationCacheKey(effectiveAuthConfig, callbackUrl, "dcr")
+        );
+      }
+      request.handledCallback = false;
+      transitionActiveRequest("error", errorMessage || "Token exchange failed.");
+    } catch {
+      request.handledCallback = false;
+      transitionActiveRequest("error", "Token exchange failed. Please try again.");
+    }
+  }, [getCallbackUrl, resolveAndClearActiveRequest, transitionActiveRequest]);
+  const handleAuthPayload = useCallback((payload) => {
+    const request = activeRequestRef.current;
+    if (!request || !payload || typeof payload !== "object") {
+      return;
+    }
+    const data = payload;
+    const responseState = typeof data.state === "string" ? data.state : "";
+    if (!request.state || responseState !== request.state || request.handledCallback) {
+      return;
+    }
+    request.handledCallback = true;
+    clearPollTimer(request);
+    clearStoredCallbackPayload(responseState);
+    if (data.type === "mcpstack-oauth-callback" && typeof data.token === "string") {
+      resolveAndClearActiveRequest({
+        accessToken: data.token,
+        resolvedAuthConfig: request.resolvedAuthConfig
+      });
+      return;
+    }
+    if (data.type === "mcpstack-oauth-callback" && typeof data.accessToken === "string") {
+      resolveAndClearActiveRequest({
+        accessToken: data.accessToken,
+        refreshToken: typeof data.refreshToken === "string" ? data.refreshToken : void 0,
+        expiresIn: typeof data.expiresIn === "number" ? data.expiresIn : void 0,
+        tokenType: typeof data.tokenType === "string" ? data.tokenType : void 0,
+        resolvedAuthConfig: request.resolvedAuthConfig
+      });
+      return;
+    }
+    if (data.type === "mcpstack-oauth-code" && typeof data.code === "string") {
+      void exchangeCodeForToken(data.code);
+      return;
+    }
+    if (data.type === "mcpstack-oauth-error" && typeof data.error === "string") {
+      const description = typeof data.errorDescription === "string" ? data.errorDescription : typeof data.error_description === "string" ? data.error_description : "Sign in could not be completed.";
+      setActivePopupPhase(
+        data.error === "access_denied" ? "canceled" : "error",
+        description
+      );
+      return;
+    }
+    request.handledCallback = false;
+  }, [
+    clearStoredCallbackPayload,
+    exchangeCodeForToken,
+    resolveAndClearActiveRequest,
+    setActivePopupPhase
+  ]);
+  const startOrRetryPopupAuth = useCallback(async () => {
+    const request = activeRequestRef.current;
+    if (!request) {
+      return;
+    }
+    const width = 500;
+    const height = 600;
+    const left = window.screenX + (window.outerWidth - width) / 2;
+    const top = window.screenY + (window.outerHeight - height) / 2;
+    const popupWindow = window.open(
+      "about:blank",
+      "mcpstack-auth-popup",
+      `popup=yes,width=${width},height=${height},left=${left},top=${top},resizable=yes,scrollbars=yes`
+    );
+    if (!popupWindow) {
+      transitionActiveRequest(
+        "blocked",
+        "Your browser blocked the sign-in popup. Allow popups and try again."
+      );
+      return;
+    }
+    request.popupWindow = popupWindow;
+    request.popupWindow.focus?.();
+    clearStoredCallbackPayload(request.state);
+    clearPollTimer(request);
+    request.codeVerifier = generateCodeVerifier();
+    request.state = crypto.randomUUID();
+    request.handledCallback = false;
+    const popupContext = encodeURIComponent(JSON.stringify({
+      openerOrigin: window.location.origin,
+      expectedState: request.state
+    }));
+    try {
+      request.popupWindow.name = `mcpstack-auth:${popupContext}`;
+    } catch {
+      closePopupWindow(request);
+      transitionActiveRequest(
+        "error",
+        "The sign-in popup could not be opened. Try again."
+      );
+      return;
+    }
+    if (mountedRef.current) {
+      setPopupState(
+        createPopupState(request, "preparing", "Preparing secure sign in...")
+      );
+    }
+    let effectiveAuthConfig = request.authConfig;
+    try {
+      if (effectiveAuthConfig.authType === "oauth2" && !effectiveAuthConfig.clientMode) {
+        const registration = await resolveOAuthRegistration(effectiveAuthConfig, {
+          callbackUrl: getCallbackUrl(effectiveAuthConfig),
+          oauthClientMetadataUrl: optionsRef.current.oauthClientMetadataUrl,
+          clientName: "MCP Stack MCP Client",
+          clientUri: window.location.origin
+        });
+        effectiveAuthConfig = applyResolvedRegistration(effectiveAuthConfig, registration);
+      }
+      request.resolvedAuthConfig = effectiveAuthConfig;
+    } catch (error) {
+      closePopupWindow(request);
+      transitionActiveRequest(
+        "error",
+        error instanceof Error ? error.message : "Failed to prepare OAuth sign in for this MCP server."
+      );
+      return;
+    }
+    const callbackUrl = getCallbackUrl(effectiveAuthConfig);
+    const loginUrl = effectiveAuthConfig.authorizationEndpoint ?? effectiveAuthConfig.loginUrl;
+    if (!loginUrl) {
+      closePopupWindow(request);
+      transitionActiveRequest("error", "This MCP server is missing an authorization endpoint.");
+      return;
+    }
+    const codeVerifier = request.codeVerifier;
+    let authUrl = "";
+    if (effectiveAuthConfig.tokenEndpoint ?? effectiveAuthConfig.tokenUrl) {
+      const codeChallenge = await generateCodeChallenge(codeVerifier);
+      const params = new URLSearchParams({
+        response_type: "code",
+        code_challenge: codeChallenge,
+        code_challenge_method: "S256",
+        state: request.state,
+        redirect_uri: callbackUrl
+      });
+      if (effectiveAuthConfig.clientId) {
+        params.set("client_id", effectiveAuthConfig.clientId);
+      }
+      if (effectiveAuthConfig.scopes?.length) {
+        params.set("scope", effectiveAuthConfig.scopes.join(" "));
+      }
+      if (effectiveAuthConfig.resource) {
+        params.set("resource", effectiveAuthConfig.resource);
+      }
+      if (request.userIdentity && isGatewayAuthorizeUrl2(effectiveAuthConfig)) {
+        const subject = normalizeOptionalValue2(request.userIdentity.subject);
+        const email = normalizeOptionalValue2(request.userIdentity.email);
+        const organizationId = normalizeOptionalValue2(request.userIdentity.organizationId);
+        const displayName = normalizeOptionalValue2(request.userIdentity.displayName);
+        if (subject) {
+          params.set("mcpstack_host_subject", subject);
+        }
+        if (email) {
+          params.set("mcpstack_host_email", email);
+        }
+        if (organizationId) {
+          params.set("mcpstack_host_organization_id", organizationId);
+        }
+        if (displayName) {
+          params.set("mcpstack_host_display_name", displayName);
+        }
+        params.set(
+          "mcpstack_mismatch_policy",
+          "block_with_switch"
+        );
+      }
+      authUrl = `${loginUrl}${loginUrl.includes("?") ? "&" : "?"}${params.toString()}`;
+    } else {
+      const params = new URLSearchParams({
+        state: request.state,
+        redirect_uri: callbackUrl,
+        mode: "popup"
+      });
+      if (effectiveAuthConfig.clientId) {
+        params.set("client_id", effectiveAuthConfig.clientId);
+      }
+      if (effectiveAuthConfig.resource) {
+        params.set("resource", effectiveAuthConfig.resource);
+      }
+      authUrl = `${loginUrl}${loginUrl.includes("?") ? "&" : "?"}${params.toString()}`;
+    }
+    if (request.popupWindow.closed) {
+      transitionActiveRequest(
+        "canceled",
+        "The sign-in window was closed before authentication completed."
+      );
+      return;
+    }
+    try {
+      request.popupWindow.location.replace(authUrl);
+    } catch {
+      closePopupWindow(request);
+      transitionActiveRequest(
+        "error",
+        "The sign-in popup could not be opened. Try again."
+      );
+      return;
+    }
+    request.popupWindow.focus?.();
+    request.pollTimer = setInterval(() => {
+      const activeRequest = activeRequestRef.current;
+      if (!activeRequest || activeRequest !== request) {
+        clearPollTimer(request);
+        return;
+      }
+      if (request.popupWindow?.closed) {
+        clearPollTimer(request);
+        if (mountedRef.current) {
+          setPopupState(
+            createPopupState(
+              request,
+              "canceled",
+              null,
+              "The sign-in window was closed before authentication completed."
+            )
+          );
+        }
+      }
+    }, 500);
+    if (mountedRef.current) {
+      setPopupState(
+        createPopupState(
+          request,
+          "waiting",
+          "Finish sign in in the popup window to connect your account."
+        )
+      );
+    }
+  }, [
+    clearPollTimer,
+    clearStoredCallbackPayload,
+    closePopupWindow,
+    getCallbackUrl,
+    transitionActiveRequest
+  ]);
+  const cancelPopupAuth = useCallback(() => {
+    if (!activeRequestRef.current) {
+      dismissPopupState();
+      return;
+    }
+    resolveAndClearActiveRequest(void 0);
+  }, [dismissPopupState, resolveAndClearActiveRequest]);
+  const handleServerAuthStatus = useCallback((serverUrl, authStatus) => {
+    if (authStatus !== "connected") {
+      return;
+    }
+    const request = activeRequestRef.current;
+    if (request && request.serverUrl === serverUrl) {
+      clearPollTimer(request);
+      closePopupWindow(request);
+      clearStoredCallbackPayload(request.state);
+      activeRequestRef.current = null;
+    }
+    dismissPopupState(serverUrl);
+  }, [clearPollTimer, clearStoredCallbackPayload, closePopupWindow, dismissPopupState]);
+  const requestAuth = useCallback((serverUrl, authConfig) => {
+    const activeRequest = activeRequestRef.current;
+    if (activeRequest) {
+      if (activeRequest.serverUrl === serverUrl) {
+        return activeRequest.promise;
+      }
+      if (mountedRef.current) {
+        setPopupState((currentState) => currentState ? {
+          ...currentState,
+          errorMessage: "Another MCP server sign-in is already in progress. Finish or cancel it first."
+        } : createPopupState(
+          activeRequest,
+          "error",
+          null,
+          "Another MCP server sign-in is already in progress. Finish or cancel it first."
+        ));
+      }
+      return Promise.reject(
+        new Error("Another MCP server sign-in is already in progress. Finish or cancel it first.")
+      );
+    }
+    const serverName = optionsRef.current.resolveServerName(serverUrl);
+    let resolvePromise = () => {
+    };
+    const promise = new Promise((resolve) => {
+      resolvePromise = resolve;
+    });
+    const request = {
+      serverName,
+      serverUrl,
+      authConfig,
+      resolvedAuthConfig: authConfig,
+      promise,
+      resolve: resolvePromise,
+      state: "",
+      codeVerifier: "",
+      handledCallback: false,
+      popupWindow: null,
+      userIdentity: optionsRef.current.userIdentity,
+      hostIdentityLabel: formatUserIdentityLabel(optionsRef.current.userIdentity)
+    };
+    activeRequestRef.current = request;
+    setPopupState(createPopupState(request, "prompt"));
+    return promise;
+  }, []);
+  useEffect2(() => {
+    const handleMessage = (event) => {
+      const request = activeRequestRef.current;
+      if (!request) {
+        return;
+      }
+      try {
+        const callbackOrigin = new URL(getCallbackUrl(request.resolvedAuthConfig)).origin;
+        if (event.origin !== callbackOrigin) {
+          return;
+        }
+      } catch {
+        return;
+      }
+      handleAuthPayload(event.data);
+    };
+    const handleStorage = (event) => {
+      if (!event.key?.startsWith(OAUTH_CALLBACK_STORAGE_PREFIX) || !event.newValue) {
+        return;
+      }
+      try {
+        const parsed = JSON.parse(event.newValue);
+        handleAuthPayload(parsed);
+      } catch {
+      }
+    };
+    const channel = typeof BroadcastChannel !== "undefined" ? new BroadcastChannel(OAUTH_CALLBACK_CHANNEL_NAME) : null;
+    if (channel) {
+      channel.onmessage = (event) => {
+        handleAuthPayload(event.data);
+      };
+    }
+    window.addEventListener("message", handleMessage);
+    window.addEventListener("storage", handleStorage);
+    return () => {
+      window.removeEventListener("message", handleMessage);
+      window.removeEventListener("storage", handleStorage);
+      channel?.close();
+    };
+  }, [getCallbackUrl, handleAuthPayload]);
+  useEffect2(() => () => {
+    mountedRef.current = false;
+    const request = activeRequestRef.current;
+    if (!request) {
+      return;
+    }
+    clearPollTimer(request);
+    closePopupWindow(request);
+    clearStoredCallbackPayload(request.state);
+    activeRequestRef.current = null;
+    request.resolve(void 0);
+  }, [clearPollTimer, clearStoredCallbackPayload, closePopupWindow]);
+  return useMemo2(() => ({
+    popupState,
+    requestAuth,
+    startOrRetryPopupAuth,
+    cancelPopupAuth,
+    handleServerAuthStatus
+  }), [
+    cancelPopupAuth,
+    handleServerAuthStatus,
+    popupState,
+    requestAuth,
+    startOrRetryPopupAuth
+  ]);
+}
+
+// src/react-app/index.tsx
+import { jsx } from "react/jsx-runtime";
+var AppAgentContext = createContext(null);
+function useAppAgent(config, options) {
+  const shouldUseBuiltInPopupAuth = !config.onAuthRequired && !config.auth;
+  const popupRequestAuthRef = useRef3(null);
+  const builtInPopupAuthHandler = useMemo3(() => {
+    const handler = (serverUrl, authConfig) => popupRequestAuthRef.current?.(serverUrl, authConfig) ?? Promise.resolve(void 0);
+    handler.__mcpStackBuiltinPopupAuth = true;
+    return handler;
+  }, []);
+  const base = useAppAgentBinding(
+    config,
+    options,
+    shouldUseBuiltInPopupAuth ? { onAuthRequired: builtInPopupAuthHandler } : void 0
+  );
+  const popup = usePopupOAuthController({
+    resolveServerName: (serverUrl) => base.runtime.agentConfig?.mcpServers.find((server) => server.url === serverUrl)?.name ?? "MCP Server",
+    oauthCallbackUrl: base.runtime.agent.getOAuthCallbackUrl(),
+    oauthClientMetadataUrl: base.runtime.agent.getOAuthClientMetadataUrl(),
+    userIdentity: config.userIdentity,
+    appSessionKey: config.appSessionKey
+  });
+  popupRequestAuthRef.current = popup.requestAuth;
+  useEffect3(() => {
+    if (!shouldUseBuiltInPopupAuth) {
+      return;
+    }
+    base.controller.setAuthRequiredHandler(builtInPopupAuthHandler);
+  }, [base.controller, builtInPopupAuthHandler, shouldUseBuiltInPopupAuth]);
+  useEffect3(() => {
+    base.connections.items.forEach((server) => {
+      popup.handleServerAuthStatus(server.url, server.authStatus);
+    });
+  }, [base.connections.items, popup.handleServerAuthStatus]);
+  const visiblePopupState = shouldUseBuiltInPopupAuth && popup.popupState ? base.connections.items.find((server) => server.url === popup.popupState?.serverUrl)?.authStatus === "connected" ? null : popup.popupState : null;
+  return {
+    ...base,
+    popupAuthState: visiblePopupState,
+    startOrRetryPopupAuth: popup.startOrRetryPopupAuth,
+    cancelPopupAuth: popup.cancelPopupAuth
+  };
+}
+function AppAgentProvider({
+  children,
+  ...config
+}) {
+  const value = useAppAgent(config);
+  return /* @__PURE__ */ jsx(AppAgentContext.Provider, { value, children });
+}
+function useAppAgentContext() {
+  const context = useContext(AppAgentContext);
+  if (!context) {
+    throw new Error("useAppAgentContext must be used within an AppAgentProvider.");
+  }
+  return context;
+}
+export {
+  AppAgentProvider,
+  useAppAgent,
+  useAppAgentContext
+};
+//# sourceMappingURL=index.mjs.map